|
| 1 | +--- |
| 2 | +title: LDAP authentication |
| 3 | +sidebarTitle: LDAP |
| 4 | +--- |
| 5 | + |
| 6 | +LDAP (Lightweight Directory Access Protocol) authentication lets your team sign in to Plane using their existing corporate credentials. Instead of creating separate Plane passwords, users authenticate through your organization's directory service. |
| 7 | + |
| 8 | +## Before you begin |
| 9 | + |
| 10 | +You'll need: |
| 11 | + |
| 12 | +- Plane Commercial Edition with an active Enterprise plan license. |
| 13 | + - Don't have an Enterprise license? Contact Sales at [sales@plane.so](mailto:sales@plane.so) to get started. |
| 14 | + - Already have a license? See how to [activate your Enterprise license](/self-hosting/manage/manage-licenses/activate-enterprise). |
| 15 | +- Connection details for your LDAP server. |
| 16 | +- A service account on your LDAP server with read-only access to the user directory. |
| 17 | + |
| 18 | +## Configure LDAP authentication |
| 19 | + |
| 20 | +1. Sign in to your Plane instance in [God Mode](/self-hosting/govern/instance-admin). |
| 21 | +  |
| 22 | +2. Select **Authentication** from the left pane. |
| 23 | +3. Click **Configure** next to **LDAP** at the bottom of the page. |
| 24 | +4. Enter your LDAP server details. |
| 25 | +  |
| 26 | + - **Server URI (required)** |
| 27 | + This is the address of your LDAP server. Include the protocol and port number. |
| 28 | + |
| 29 | + **Format:** |
| 30 | + - For unencrypted connections: `ldap://hostname:389` |
| 31 | + - For encrypted connections (recommended): `ldaps://hostname:636` |
| 32 | + |
| 33 | + **Examples:** |
| 34 | + ``` |
| 35 | + ldap://ldap.company.com:389 |
| 36 | + ldaps://ad.company.com:636 |
| 37 | + ldap://192.168.1.100:389 |
| 38 | + ``` |
| 39 | + |
| 40 | + - **Bind DN (required)** |
| 41 | + |
| 42 | + This is the username of the service account that Plane will use to search your directory. Think of it as Plane's "read-only" account on your LDAP server. |
| 43 | + |
| 44 | + The format varies depending on your directory service: |
| 45 | + |
| 46 | + **Active Directory examples:** |
| 47 | + ``` |
| 48 | + cn=PlaneService,ou=Service Accounts,dc=company,dc=com |
| 49 | + plane-svc@company.com |
| 50 | + ``` |
| 51 | + |
| 52 | + **OpenLDAP examples:** |
| 53 | + ``` |
| 54 | + cn=admin,dc=example,dc=com |
| 55 | + cn=readonly,ou=services,dc=example,dc=com |
| 56 | + ``` |
| 57 | + |
| 58 | + - **Bind Password (required)** |
| 59 | + |
| 60 | + Enter the password for your service account (Bind DN). Plane encrypts and stores this securely in its database. |
| 61 | + |
| 62 | + - **User Search Base (required)** |
| 63 | + |
| 64 | + This defines where in your directory Plane should look for users. Think of it as the "starting folder" for user searches. |
| 65 | + |
| 66 | + Use the most specific path possible for better performance. |
| 67 | + |
| 68 | + **Examples:** |
| 69 | + ``` |
| 70 | + ou=users,dc=example,dc=com |
| 71 | + ou=employees,ou=people,dc=company,dc=com |
| 72 | + cn=users,dc=company,dc=local |
| 73 | + ``` |
| 74 | + |
| 75 | + - **User Search Filter (optional)** |
| 76 | + |
| 77 | + This tells Plane how to find users when they try to sign in. Use `{username}` as a placeholder - Plane replaces it with whatever the user types in the login field. |
| 78 | + |
| 79 | + **Common filters by directory type:** |
| 80 | + |
| 81 | + | Directory Type | Filter | What it does | |
| 82 | + |----------------|--------|--------------| |
| 83 | + | OpenLDAP | `(uid={username})` | Searches by user ID | |
| 84 | + | Active Directory | `(sAMAccountName={username})` | Searches by Windows login name | |
| 85 | + | Active Directory | `(userPrincipalName={username})` | Searches by email-style username | |
| 86 | + | Any | `(mail={username})` | Searches by email address | |
| 87 | + |
| 88 | + **Default:** If you don't specify a filter, Plane uses `(uid={username})`. |
| 89 | + |
| 90 | + **Combined filter example:**\ |
| 91 | + If you want users to sign in with either their username OR email: |
| 92 | + ``` |
| 93 | + (|(uid={username})(mail={username})) |
| 94 | + ``` |
| 95 | + |
| 96 | + - **User Attributes (optional)** |
| 97 | + |
| 98 | + List the LDAP attributes Plane should retrieve to create user profiles. Plane uses these to populate the user's display name and email in Plane. |
| 99 | + |
| 100 | + **How Plane maps attributes:** |
| 101 | + |
| 102 | + | Plane needs | LDAP provides (in order of preference) | |
| 103 | + |-------------|----------------------------------------| |
| 104 | + | Email address | `mail`, `userPrincipalName` | |
| 105 | + | First name | `givenName`, or first part of `cn` if `givenName` is missing | |
| 106 | + | Last name | `sn`, or last part of `cn` if `sn` is missing | |
| 107 | + |
| 108 | + **Recommended setting:** |
| 109 | + ``` |
| 110 | + mail,cn,givenName,sn,userPrincipalName,displayName |
| 111 | + ``` |
| 112 | + |
| 113 | + **Default:** If you don't specify attributes, Plane uses `mail,cn,givenName,sn`. |
| 114 | + |
| 115 | + - **Provider Name (optional)** |
| 116 | + |
| 117 | + This is the label that appears on Plane's login button. Choose something your team will recognize. |
| 118 | + |
| 119 | + **Examples:** |
| 120 | + - `Corporate Directory` |
| 121 | + - `Company SSO` |
| 122 | + - `Active Directory` |
| 123 | + |
| 124 | + **Default:** If you don't specify a name, Plane shows `LDAP`. |
| 125 | + |
| 126 | + The login button will display as: **"Sign in with [Provider Name]"** |
| 127 | + |
| 128 | +5. Click **Save changes** to apply your LDAP settings. Plane will validate the connection to your LDAP server. |
| 129 | + |
| 130 | +6. Users will see **Sign in with LDAP** on Plane's login page and can use their directory credentials to sign in. |
| 131 | +  |
| 132 | + |
| 133 | +## How LDAP authentication works |
| 134 | + |
| 135 | +LDAP authentication in Plane works through a two-phase process. First, Plane locates the user in your directory, then it verifies their credentials. This separation is fundamental to how LDAP works and explains why you need both a service account (Bind DN) and the user's own credentials. |
| 136 | + |
| 137 | +### The service account pattern |
| 138 | +Unlike simpler authentication systems where you might directly check a username and password against a database, LDAP uses what's called a "bind" operation. Plane needs to authenticate twice: once as itself (using the Bind DN) to search your directory, and once as the user to verify their password. |
| 139 | + |
| 140 | +This is why you configure a Bind DN and password - it's Plane's identity on your LDAP server. Think of it as Plane introducing itself before asking about your users. The Bind DN only needs read access because Plane is just looking up information, never modifying your directory. |
| 141 | + |
| 142 | +### The authentication flow |
| 143 | +When a user tries to sign in, here's what happens behind the scenes: |
| 144 | + |
| 145 | +**Connection and service authentication** |
| 146 | +Plane connects to your LDAP server using the Server URI, then authenticates using the Bind DN credentials. If this fails, no users can sign in; the service account must work first. |
| 147 | + |
| 148 | +**User search** |
| 149 | +Now authenticated, Plane searches for the user starting from the User Search Base and applying the User Search Filter. For example, if a user enters "jsmith" and your filter is `(uid={username})`, Plane searches for `(uid=jsmith)`. The search returns the user's distinguished name (DN), their full path in the directory. |
| 150 | + |
| 151 | +**User authentication** |
| 152 | +Plane now attempts to bind again using the user's DN and their entered password. If the bind succeeds, the password is correct. This is why LDAP authentication is secure. Plane never stores user passwords; they go straight to your LDAP server for verification. |
| 153 | + |
| 154 | +**Profile creation** |
| 155 | +Once authentication succeeds, Plane retrieves the User Attributes you configured (like email, first name, last name) from the user's LDAP record. If this is the user's first time signing in, Plane creates their profile using this information. If they've signed in before, Plane updates their profile with any changes from LDAP. |
| 156 | + |
| 157 | +**Session establishment** |
| 158 | +Finally, Plane creates a session for the user and redirects them into the workspace. From this point on, the user's session works identically to any other Plane session. The LDAP interaction is complete. |
| 159 | + |
| 160 | +### Why search filters matter |
| 161 | +The User Search Filter determines sign-in flexibility. A simple filter like `(uid={username})` requires exact usernames, but you can make it more flexible: |
| 162 | + |
| 163 | +`(mail={username})` lets users sign in with email |
| 164 | +`(|(uid={username})(mail={username}))` allows either username or email |
| 165 | + |
| 166 | +Filters can also restrict access: `(&(uid={username})(memberOf=cn=plane-users,ou=groups,dc=company,dc=com))` only permits specific group members. |
| 167 | + |
| 168 | +### The role of user attributes |
| 169 | +User Attributes tell Plane which LDAP fields to retrieve after authentication. This is separate from the search filter. The filter finds the user, the attributes populate their profile. |
| 170 | + |
| 171 | +Plane specifically looks for email addresses (required) and names (optional). If your LDAP server uses different attribute names, you need to include them. |
0 commit comments