Configuring Active Directory and LDAP Authentication Without Triggers
New in 2014.2 release of the Perforce Server is native support for authentication against LDAP servers (including Active Directory and OpenLDAP). This means that Perforce administrators no longer need to use external authentication triggers when configuring Perforce to authenticate users against directory servers.
Here’s an overview/quick start guide for using the new LDAP integration:
Creating LDAP Configurations
LDAP configurations define how to connect to and authenticate users against an LDAP server. They can be accessed with the new ‘p4 ldap’ command and listed with ‘p4 ldaps’, for example:
p4 ldap example-ldap-configuration
This will open the LDAP configuration spec for a configuration named ‘example -ldap-configuration.' This is the first field in the spec. The next three fields, ‘Hostname’, ‘Port’ and ‘Encryption’, provide basic connection details such as where to find the LDAP server, what port is it listening on, and whether encryption (SSL or TLS) should be used, for example:
Name: example-ldap-configuration Hostname: ldap.example.com Port: 389 Encryption: TLS
The next field, ‘BindMethod’, defines which method should be used to map Perforce users to directory objects. There are three authentication options to choose from:
Simple bind authentication takes the DN (distinguished name) of a user to be authenticated and replaces the username with the ‘%user%’ placeholder. This is set on the ‘SimplePattern’ field, for example:
BindMethod: simple SimplePattern: uid=%user%,ou=users,dc=example,dc=com
This pattern is expanded when a user is being logged in. For example, if the user ‘jsmith’ attempted to log in, the Perforce Server would attempt to bind against the DN ‘uid=jsmith,ou=users,dc=example,dc=com’ using the password the user provided. The downside is that this bind method will only work in environments where the user’s username is part of their DN and all of the users that you’d want to authenticate are in the same organizational unit (OU).
This bind method performs a search for the user’s record in the directory, overcoming the restrictions of the simple bind method. Instead of a DN pattern, an LDAP search query is provided to identify the user’s record (the ‘%user%’ placeholder is also used here). A starting point and scope for the search are also provided, allowing control over how much of the directory is to be searched. This example will search in the ‘users’ OU and any OU’s below it for any objects that have an object class of ‘inetOrgPerson’ and a ‘uid’ attribute that matches the user’s username:
BindMethod: search SearchBaseDN: ou=users,dc=example,dc=com SearchFilter: (&(objectClass=inetOrgPerson)(uid=%user%)) SearchScope: subtree
In most cases this search will require authentication. If this is the case, you can set the ‘SearchBindDN’ and ‘SearchPasswd’ fields to those of a known read-only user within the directory, for example:
SearchBindDN: uid=read-only,dc=example,dc=com SearchPasswd: ******
One complication of the previous bind method is the Perforce administrator needs to know about the structure of the directory. Most LDAP servers have the option of binding using SASL, which only require a username and password to authenticate a user; all efforts to resolve the user inside the directory is delegated to the LDAP server. This means that in most cases, SASL bind will require no configuration on the Perforce side, for example:
If your LDAP server has multiple realms (or domains if you’re using Active Directory), you may need to specify which one the LDAP configuration should be using. In this case, you’ll need to set the ‘SaslRealm’ field too, for example:
BindMethod: sasl SaslRealm: example
Active Directory supports SASL out of the box, and most LDAP servers support SASL; however, configuring SASL in the LDAP server is not always easy.
Authorization with LDAP Groups
While bind methods configure user authentication, you probably don’t want to give everyone in your organization the ability to log in to your Perforce Server, especially if everyone in your organization is in the same directory. Instead, create a group object in the directory that contains only authorized users. The new LDAP integration has optional support for group membership checking to facilitate this.
LDAP groups work just like the search bind method where an LDAP search query is provided to identify whether a user is a member of an allowed group and a search base and scope are also provided. For example, if there is a group in the LDAP directory named ‘perforce,’ whose users are allowed access to Perforce, you might have a configuration like this:
GroupBaseDN: ou=groups,dc=example,dc=com SearchFilter: (&(objectClass=posixGroup) (cn=perforce) (memberUid=%user%)) SearchScope: subtree
Testing LDAP Configurations
LDAP configurations can be tested, even before they are enabled. This can be done using the ‘-t’ flag on ‘p4 ldap’ and ‘p4 ldaps’, for example:
p4 ldap -t jsmith example-ldap-configuration
The output of the test will either be a success message or the error message returned by the LDAP server. This error message is not reported to users if they ran ‘p4 login’; they will only see the normal authentication failure message.
Enabling LDAP Configurations
LDAP configurations are enabled by adding them to the list configurable ‘auth.ldap.order.N’. This is an ordered list of LDAP configurations, where configurations are queried starting with the lowest number, for example:
p4 configure set auth.ldap.order.1=example-ldap-configuration
Enabled configurations can be seen in the list of configurables, ‘p4 configure show’, or by running ‘p4 ldaps -A’. Make sure to restart your Perforce server after enabling LDAP; it will not kick in until the server has been restarted.
Configuring Users to Use the LDAP Integration
Not all Perforce users exist in LDAP servers. Usage policies frequently prevent non-human background users from being added to LDAP servers (i.e., those used by Commons and Swarm). To address this issue, an ‘AuthMethod’ field was added to the user spec.
If ‘AuthMethod’ is set to ‘perforce’ (the default) the user will authenticate against the Perforce database. If the ‘AuthMethod’ is set to ‘ldap’ they will authenticate against the new LDAP integration, using the enabled LDAP configurations.
Here are some additional resources to help you configure and build LDAP/AD authentication into the latest release of the Perforce Server 2014.2:
- p4 help ldap
- p4 help ldaps
- p4 help configurables
- Free tool for visualizing LDAP Server trees: Apache Directory Studio
- MERGE 2014 Presentation: AD and LDAP Authentication Without Triggers