Configuring LDAP in Portainer

A step by step guide on how to configure LDAP in Portainer

Follow the instructions in each section below to enable LDAP in Portainer.

Enter LDAP server details

Step 1. Navigate to the Authentication view and click on the LDAP tab.

Step 2. Next enter the configuration details of your LDAP server in the following fields:

• LDAP URL - FQDN or IP Address of your LDAP or Active Directory Server (e.g. MYSERVER.MYDOMAIN.com) followed by the port number (eg :389). For Active Directory this should be your Domain Controller.

• Reader DN - Enter the user account that has READ ONLY permissions in your Directory service. For Active Directory use the format [e-mail] or domain\userfirstname.userlastname For Native LDAP use the format cn=username,dc=mydomain,dc=com

• Password - Enter the password of the authenticated user you created

NOTE: If your LDAP server requires TLS, refer to LDAP with TLS before moving on to step 3.

Step 3. Click the Test connectivity button to check Portainer can successfully connect to the server. Result: You should recieve a green notification in the top right of the screen if Portainer's connection to the LDAP server was successful.

LDAP with TLS

If you require the use of TLS with LDAP in Portainer, you can use either StartTLS or TLS.

Step 1. Click a toggle to enable either StartTLS or TLS. The StartTLS option tells Portainer to elevate the insecure connection to secure after the initial connection. The TLS option will initiate a connection to LDAP using TLS.

Step 2. Click the below tab for the next step depending on your environment.

Use certificates (Secure)

Click the Select file button in the TLS CA certificate section to upload your certificates.

Don't use certificates (Less secure)

If you do not have access to the certificate of the LDAP server, enable the Skip Verification of Certificate option.

Note: skipping verification enables encrypted communications, but you must manually ensure that you are talking to the intended LDAP server that you gave in your URL. If that gets maliciously redirected then you could be talking to a different server. Use with caution.

Automatic LDAP users & groups

Automatic user provisioning

If you wish Portainer to automatically create accounts when LDAP users login, enable automatic user provisioning. Note: If you do not wish to enable this, you must manually add accounts for your users in Portainer, and your LDAP server will be used only for password authentication by Portainer.

Enabling Automatic user provisiong

Manually add LDAP Users

You must manually add users to Portainer if you don't wish for Portainer to automatically create them for LDAP users following authentication.

Step 1. Navigate to the Users view.

Step 2. Create a username that matches your LDAP source users with the format defined when enabling LDAP (either username or [e-mail]).

Defining LDAP users in Portainer

User/team/group association

In order to use user/team/group auto-association as mentioned in the Automatic user provisioning section, you must first pre-create teams in Portainer with team names that match the LDAP group names. Note: teams are case sensitive.

Step 1. Navigate to the Teams view

Step 2. Create the team names that correspond to LDAP groups you want to enable in Portainer (e.g. development and production).

Creating production team in Portainer to match production LDAP group

Step 3. Navigate to the Endpoints view and click manage access on the endpoint you want to grant the team access to

Managing access on an endpoint

Step 4. Click on the teams you want to allow access, they will move from the left side (unauthorised) to right side (authorised).

Authorizing teams in Portainer

Step 5. You can now logout as admin, and login as one of your LDAP users. You should see they have access to the authorised endpoints from the previous step and can directly start working them.

User can manage endpoint authorised to their LDAP group

User and group search

Configuring user search

Next you will need to enter the LDAP user search configuration so that Portainer can find your LDAP users. Note: Ask your LDAP server admin what is applicable to you before folowing this tutorial as you may have different LDAP criteria and attributes depending on your server schema and version.

Step 1. Enter in the base DN of your LDAP server for example DC=MYDOMAIN,DC=com.The base DN is used to search your entire Directory for the username attempting to login.

You can prefix this with OU=MYOUNAME if your Portainer users will exist only in a specific Organizational Unit. You can alternatively prefix with CN=NAMEif your users are only in a container. Note: In Active Directory, the default is that all users are in a container called users i.e CN=Users. Step 2. Next enter the Username attribute used by your LDAP server. Click on the below tab that matches your LDAP server configuration for the appropriate examples.

Native LDAP

For Native LDAP, the most common Username attribute used isuid

NOTE: This is case sensitive. DO NOT USE sAMAccountNameor userPrincipalNamewith Native LDAP as it will not work.

Active Directory

For Active Directory, commonly used examples are userPrincipalName if your usernames will be in the format of [e-mail] OR sAMAccountName if your usernames will be in the format username.

NOTE: These entries are case sensitive. DO NOT USE uid with Active Directory as it will not work.

Optional step 3. Optionally, you may enter a criteria in the filter field to pre-filter the results returned from LDAP to Portainer. As an example, (memberOf=CN=PortainerUsers,CN=Users,DC=MYDOMAIN,DC=com) would only allow users who are members of the group PortainerUsers to login. You could also use (objectClass=inetOrgPerson) to only search for users with the inetOrgPerson schema type.

Configuring group search

Next you will need to configure the LDAP group search criteria so that Portainer can find your LDAP groups. Note: Ask your LDAP server admin what is applicable to you before folowing this tutorial as you may have different LDAP criteria and attributes depending on your server schema and version.

Step 1. Enter in the base DN of your LDAP server for example DC=MYDOMAIN,DC=com.The base DN is used to search your entire Directory for groups.

Step 2. Next enter a Group membership attribute used in your LDAP server, a common example of this for Active Directory and Native LDAP is member.Note: this is case sensitive.

Optional Step 3. Optionally, you may enter a criteria in the Group filter field to pre-filter the results returned from LDAP to Portainer. As an example, (objectClass=groupOfNames) would only search for groups with the groupOfNames schema type.

Final step. Click the save settings button to save your settings in Portainer.