Authenticate via LDAP
Last updated
Last updated
Portainer can be configured to accept Lightweight Directory Access Protocol (LDAP) authentication if your organization has implemented LDAP authentication. When users attempt to log into Portainer, the application will authenticate them against your LDAP directory. If authentication is successful, the user is allowed to log into Portainer.
To configure Portainer LDAP authentication, you first need to add a user to your directory service for the purpose of authenticating from Portainer to read the LDAP. The user should be a service account that needs read-only access to LDAP.
Log into Portainer as an administrator. From the menu select Settings, select Authentication then select the LDAP Authentication option. Extra fields will appear, allowing you to configure LDAP.
Enabling this setting automatically creates users within Portainer once they are successfully authenticated by LDAP. If you do not enable this, you must manually create users with the same username as the corresponding LDAP directory.
Here you can select a custom configuration or a preconfigured OpenLDAP template.
Enter the IP address/FQDN and port number of your LDAP server. Opt to either connect anonymously (your LDAP server must support this) or enter a user account that has READ access to the directory. Click Test connectivity to validate that you can connect.
For OpenLDAP, the Reader DN format should be set to cn=user,dc=domain,dc=tld. If your configuration differs you will need to adjust this to suit.
If you want to add additional LDAP servers to provide for authentication fallback, click Add additional server and fill in the server details.
Configure the remaining LDAP settings, using the table below as a guide:
| Field/Option | Overview |
|---|---|
Use StartTLS | Changes the insecure connection to secure after the initial connection. |
Use TLS | Initiates a connection to LDAP using TLS. |
Skip verification of server certificate | If you do not have access to the LDAP server certificate, skipping verification will enable encrypted communications. However, you must manually ensure that you are talking to the intended LDAP server that you specified in the URL. If that gets maliciously redirected, you could be talking to a different server. Use with caution. |
| Field/Option | Overview |
|---|---|
TLS CA certificate | Lets you upload your CA certificate for the secure connection. |
Enter dc=mydomain,dc=com to search your entire directory for the username attempting to login.
Enter ou=myou,dc=mydomain,dc=com to search for users only within the specified OU.
Enter cn=mycn,dc=mydomain,dc=com if your users are only in a container.
If you have a large number of users in your domain, narrow the scope Portainer searches on by using OUs.
For LDAP, enter uid unless your configuration differs.
These entries are case sensitive.
Enter filter criteria for the results returned from LDAP to Portainer. For example, to only allow users who are members of a group defined within an OU to login, set Filter to the following (the brackets are important, so copy the entire string):
In the example below, the domain portainer.local has an OU called Groups and within that OU is a group called PortainerDevUsers. This search filter will only allow users who are members of the PortainerDevUsers LDAP group to log into Portainer.
As an optional step, click Add user search configuration to define additional user-search configurations.
In addition to user search, Portainer also gives you the option to set up group search. When configured, if an LDAP user is a member of an LDAP group, and that LDAP Group corresponds to an identically named Portainer Team, then the LDAP user will automatically be placed into the Portainer Team based on their LDAP group membership. This is very useful for automatically granting access to Portainer environments via group membership.
Enter either:
Enter dc=mydomain,dc=com to search your entire directory for the list of groups.
Enter ou=myou,dc=mydomain,dc=com to search for groups only within the specified OU.
Enter cn=mycn,dc=mydomain,dc=com if your groups are only in a container.
If you have a large number of groups in your domain, narrow the scope Portainer searches on by using OUs.
Enter member as the attribute that determines if a user is a member of a group.
If you want to filter the list of groups to return only those that contain the string Portainer (for example: PortainerDev, PortainerProd, PortainerUAT), set up the filter like this:
As an optional step, click Add group search configuration to define additional group-search configurations.
If desired, Portainer can configure specified LDAP groups of users to become Portainer administrators automatically.
To configure this, first click add group search configuration and define the Group Base DN, Groups and Group Filter as required. Once done, click the Fetch Admin Group(s) button to retrieve the list of groups matching your search configuration.
When you're happy with the group selection, enable this feature by toggling Assign admin rights to group(s) on.
To test your configuration, you can enter a username and password and click the Test button.
This is an optional step and is required only if you do not use automatic user provisioning.
Once LDAP has been enabled, from the menu select Users. Create a username that matches your LDAP source users with the format defined when you enabled LDAP (either username or username@mydomain.com).
