Pivotal Knowledge Base

Follow

Configuring LDAP Integration with Pivotal Cloud Foundry®

Purpose

When using Pivotal Cloud Foundry® (PCF), it is possible to integrate it with your LDAP system.  Because all LDAP systems are different, it takes a little bit of configuration for PCF to properly integrate with your LDAP system.  This article will walk through the configuration, provide some additional details about what information is needed and provide you with some tools for validating the configuration, prior to deploying PCF.

Products

PCF 1.3.x - no support for group search

PCF 1.4.x & 1.5.x - supports group search

Instructions

Configuration Fields

The LDAP configuration screen in Ops Manager will prompt you for the information that is needed to integrate with your LDAP system. In general, you'll need to enter the connection URL, credentials for the search account, a user search base, a user search filter, a group search base, a group search filter and the name of the attribute that stores the user's email address.  

For secure LDAP connections, you may also need to enter the public key used by your server, but this is only required if your LDAP server is using an SSL certificate that is not signed by a well-known certificate authority (like when you're using a self-signed certificate.)

If you need additional details about the particular fields and what should be entered in them, please see Step #4 of the docs here.

LDAP Authentication Process

When the UAA Server attempts to authenticate a user via LDAP, it's going to go through the following process.

  1. Connect to the LDAP Server, using the provided URL and the provided LDAP Credentials.
  2. If connecting via secure LDAP, the certificate on your LDAP server will be validated.  It must match the server name specified in the URL and it must be signed by a well-known certificate authority to pass this check.  If you specify a LDAP Server SSL Cert in your configuration then the certificate you specified will be trusted.  This means that if your server is using the listed certificate it will validate OK even if it's not signed by a well-known certificate authority (please note that the server name in your URL still needs to match what's listed on the certificate).
  3. Execute an LDAP Search starting from the search base using the provided LDAP user search filter.  This looks for the username provided by the user at login and attempts to find it on your LDAP server.
  4. If step #3 succeeds, UAA will then attempts to bind to the LDAP server as the user that it found.  If this succeeds then the user is authenticated.
  5. When the user is first authenticated, UAA will create a shadow user in the UAA database, based on the username and email address (loaded from the email attribute in LDAP).  The shadow user will have an origin of "LDAP", so that it does not conflict if a user with that name already exists (manually created users have an origin of "UAA").

It is also worth noting that UAA will search it's internal database for users before it consults the LDAP server.  This means if a user exists in the UAA database and the entered password matches, then the authentication will stop and LDAP will not be consulted.

LDAP Group Mappings

After a user is authenticated, UAA will attempt to look up roles for a user.  This is done based on the group search base and group search filter that are specified.  UAA will use these like it does the user search base and filter, but to locate LDAP groups associated with the authenticated user.  If any groups are found, UAA will then attempt to map the LDAP groups to UAA scopes.  If it succeeds, the user will be additionally granted that scope.  If it fails, the user will simply have the standard scopes.

LDAP User Search Filters

The LDAP user search filter is a critical part of the search process outlined above.  It instructs UAA how to find the user on your LDAP server.  It also defines the format of the username that your users will enter when they login PCF.  For example, if the user will need to enter an email address or just a username.  We suggested that you configure the user search filter so that user's authenticate with their email address (see Impact / Risks for an explanation of this), however this is not a requirement.

Testing LDAP Search Filters

While the PCF LDAP screen will validate the LDAP URL and credentials that you specify, it will not validate the LDAP search filters, user or group, that you specify.  This can make it a little tricky to configure, if you're not sure the exact value to use for the search filters.

The following instructions can be used to test potential LDAP user and group search filters without doing a full installation.

  1. Login to the Ops Manager VM.
  2. Run the command `sudo apt-get install ldap-utils`.  This installs the `ldapsearch` utility.  This command only needs to be run once.
  3. Run `ldapsearch -H "<ldap-url>" -D "<search-user>" -W -b "<search-base>" '<filter>'`, where the information in `<..>` is replaced with the corresponding information you entered on the PCF LDAP configuration screen.

    Ex:  LDAP user search filter = 'mail={0}'

        ldapsearch -H "ldap://my-server:389" -D "cn=user,ou=users,dc=example,dc=com" -W -b "ou=users,dc=example,dc=com" 'mail=user@your-company.com'

    Ex:  LDAP group search filter = 'member={0}'

        ldapsearch -H "ldap://my-server:389" -D "cn=user,ou=users,dc=example,dc=com" -W -b "ou=groups,dc=example,dc=com" 'member=uid=some.user,ou=users,dc=example,dc=com'

    Note:  For the user filter, use the test username directly and not '{0}'.  The '{0}' is where UAA will substitute the entered username.  For the group filter, use the full DN of your test user and not '{0}'.  The '{0}' is where UAA will substitute the full DN of the user that was authenticated.  You must do that manually here because the ldapsearch utility does not perform this substitution.

When the command in step #3 is executed, you'll be prompted for the password of the LDAP search user.  This is the password you entered on the PCF LDAP configuration screen.  After authenticating, the ldapsearch command will execute the search filter that you listed starting from the search base and running recursively down the tree.  

If the search filter works, you should see this command return the corresponding LDAP records.  If it does not return any records then the search filter has not matched the user or groups and needs to be adjusted.  

If multiple records are returned for the user search this is also bad, as that will cause authentication to fail.  The user search filter must return one and only one record.  Multiple records are OK for the group search filter.

Impact / Risks

In PCF 1.3.x, if you configure the LDAP search filter to use an attribute other than an email address, the invitation system will not work properly.  In order to support invitations, you must configure the LDAP search filter so that user's login with their email addresses.

In PCF 1.4, you must configure the LDAP search groups.  If not configured the LDAP group search it can impact the ability to login.  See the linked KB for more details.

Comments

Powered by Zendesk