Configuring LDAP authentication for IBM Cloud Private Cloud Foundry

You can use LDAP authentication for user authentication in IBM® Cloud Private Cloud Foundry and Cloud Foundry Enterprise Environment.

You can follow these instructions to configure LDAP authentication at any time before or after you install IBM Cloud Private Cloud Foundry (see Installing IBM Cloud Private Cloud Foundry) or Cloud Foundry Enterprise Environment (see Installing Cloud Foundry Enterprise Environment). The configuration is done by adding the included extension cfp-ext-ldap to the main IBM Cloud Private Cloud Foundry deployment. See Using extensions in IBM® Cloud Private Cloud Foundry. The cfp-ext-ldap extension modifies the deployment properties for the User Account and Authentication (UAA) server.

Before you configure LDAP authentication, you must create the users in your LDAP or Active Directory domain. You can use groups to filter access to the IBM Cloud Private Cloud Foundry environment.

Preparing your configuration

The LDAP configuration is stored in a YAML-formatted file, referred to as <ldap_config_file> in these instructions. Create the file, for example ldapconfig.yml, and place the configuration details in the uiconfig: section, as shown in the example configuration.

If you prefer to use the Cloud Foundry deployment tool, the cfp-ext-ldap extension offers guided editing of the configuration values. From the States page, click Add Extension and select cfp-ext-ldap, then complete the dialog. Go to the Configuration page and locate cfp-ext-ldap in the list of extensions. Select a configuration type of Simple Binding, Search and Bind, Groups Map to Scopes, or Groups as Scopes. The Cloud Foundry deployment tool displays the required and optional configuration values for the selected scenario. The Cloud Foundry deployment tool provides descriptions, sample values, and validation of the configuration values. For information about extensions, see Managing extensions and Configurations.

To configure LDAP authentication, you must make the following choices:

LDAP binding method
- simple-binding
  
  If the form of the distinguished name (DN) for users is known and contains the identifier that you would like to use as the user name, use the simple-binding configuration and supply one or more DN patterns to construct. UAA constructs the DNs then attempts to authenticate with the password provided by the user. The applicable lines are marked in the example configuration.
- search-and-bind
  
  If the form of the DN for users is unknown or varies, you can use the search-and-bind configuration that searches LDAP for a matching user. One common reason to use search-and-bind would be if you want to use email addresses as user names, and the common names (CNs) for user records on your LDAP server do not contain the email address. In this case, you need to provide the user name and password for an LDAP user that has (preferably read-only) access to the server to retrieve records and search for a match for the user. If there is exactly one match against the search filter, UAA then attempts to authenticate with the password provided by the user. The applicable lines are marked in the example configuration. Test your configuration values by substituting them into the command ldapsearch -H <url> -D <userDN> -w <userPassword> -b <searchBase> <searchFilter> and replacing '{0}' in the <searchFilter> value with an actual user name.
Groups mapping
- By default, LDAP users have the following privilege scopes:
```
cloud_controller.read
cloud_controller.write
cloud_controller_service_permissions.read
notification_preferences.read
notification_preferences.write
oauth.approvals
openid
password.write
profile
roles
scim.me
uaa.offline_token
uaa.user
user_attributes
```
  If you want to grant additional privilege scopes to LDAP users based on their group membership, there are two options:
  - groups-map-as-scopes
    
    Use the uaac CLI to manage the mapping between LDAP groups and privilege scopes. Scopes are recalculated on every user login, so you can remove privileges by unmapping groups by using uaac.
  - groups-as-scopes
    
    Specify the privilege scopes in the value of an attribute of the LDAP group. This requires administrative access to your LDAP server.
Activation method
- By default, all users that can be authenticated by using the chosen LDAP binding method is automatically activated when they first log in to IBM Cloud Private Cloud Foundry. If you prefer to allow login only for users that are manually activated, set add_shadow_user_on_login to false.

Note: If you are adding LDAP for Cloud Foundry Enterprise Environment after an initial deployment, you must select upgrade for the Installer action.

Example configuration

uiconfig:
  enabled: true 
  url: 'ldap://ldap.local.bluemix.net'  # LDAP server URL (space-separated list permitted)
  add_shadow_user_on_login: true        # Enable to allow any LDAP user to log in; otherwise, accounts
                                        #   must be created manually (default value is true)

# BEGIN Include and customize the following lines to use simple-binding
  profile_type: simple-bind
  userDNPattern: 'cn={0},dc=local,dc=bluemix,dc=net;cn={0},dc=example,dc=org'
# END

# BEGIN Include and customize the following lines to use search-and-bind
  profile_type: search-and-bind
  userDN: 'cn=admin,dc=local,dc=bluemix,dc=net'
  userPassword: '**********'
  searchBase: 'dc=local,dc=bluemix,dc=net'  # Specify if only part of the directory should be searched
  searchFilter: 'cn={0}'                    # User name is inserted into this filter in place of {0}
# END

# BEGIN Include the following lines to customize which LDAP attributes are used to populate the UAA user record
  mailAttributeName: emailAddress       # Attribute containing email address of user (default is 'mail')
  mailSubstitute: 'generated-{0}@ldap'  # Form for generated email address if none found in LDAP record
                                        #   (default is {0}@user.from.ldap.cf)
  mailSubstituteOverridesLdap: false    # Enable to always use the value from mailSubstitute as user email
  attributeMappings:
    family_name: lastName               # LDAP attribute to use for family name (default value is sn)
    given_name: preferredName           # LDAP attribute to use for given name (default value is givenName)
# END

# BEGIN Include and customize the following lines to use groups-map-to-scopes or groups-as-scopes
#         (Requires using the search-and-bind binding method)
  groups:
    groupSearchFilter: 'member={0}'           # Used to find the groups a user (or group for nested search) belongs to
    searchBase: 'dc=local,dc=bluemix,dc=net'  # Specify if only part of the directory should be searched for groups
                                              #   Can be set to 'memberOf' if using Active Directory to skip group search
                                              #   and use calculated 'memberOf' field on user records
    maxSearchDepth: 2                         # Number of levels to search groups (default is 1 - no nested search)
    searchSubtree: true                       # Enable to search below the search base (default value is true)

    # BEGIN Include the following line to use groups-map-to-scopes
    profile_type: groups-map-to-scopes
    # END

    # BEGIN Include and customize the following lines to use groups-as-scopes
    profile_type: groups-as-scopes
    groupRoleAttribute: cloudFoundryScope  # Name of the LDAP attribute that holds a list (comma-separated)
                                            #   of scope names applied to members of the group
    # END

# END

  ssl:
    skipverification: false  # Enable to skip server certificate validation when using LDAPS
    tls: none                # Use value 'simple' to enable StartTLS (default value is none)
  sslCertificate: |+         # Self-signed server certificate to be trusted if using LDAPS
    -----BEGIN CERTIFICATE-----
    <BASE64_ENCODED_CERT>
    -----END CERTIFICATE-----

These instructions and example configuration cover the most common options for LDAP authentication. For the complete list of valid properties, see the uaa.ldap properties for the BOSH uaa job. For further details, see User Account and Authentication LDAP Integration.

Activating the `cfp-ext-ldap` extension by using the configuration manager CLI

Push your configuration file to the inception container. <ldap_config_file> is the name of the LDAP configuration file that you created:
```
./cm extension -e cfp-ext-ldap save -c <ldap_config_file>
```
Insert the extension in the main IBM Cloud Private Cloud Foundry or Cloud Foundry Enterprise Environment deployment. The following command adds the deployment of the LDAP extension before the deployment of the IBM Cloud Private Cloud Foundry or Cloud Foundry Enterprise Environment components. The LDAP extension is automatically inserted at the correct place in the states file.
```
./cm states insert -i cfp-ext-ldap
```
Reset the engine:
```
./cm engine reset
```

Deploying Cloud Foundry with the `cfp-ext-ldap` extension

After you enable and configure the cfp-ext-ldap extension by using either the Cloud Foundry deployment tool or configuration manager CLI, you must relaunch the deployment of Cloud Foundry to update the affected components.

For IBM Cloud Private Cloud Foundry, follow the instructions in the previous section to activate the cfp-ext-ldap extension. Restart the IBM Cloud Private Cloud Foundry deployment process. <cf_config_file> is your main configuration file for the IBM Cloud Private Cloud Foundry deployment, such as uiconfig.yml:
```
 ./launch_deployment.sh -c <cf_config_file>
```
You can use the Cloud Foundry deployment tool by clicking the Start deployment button on the States page.
For Cloud Foundry Enterprise Environment, use the Cloud Foundry deployment tool to change Installer action to Upgrade in the main configuration. Click Start deployment on the States page.

Activating users

If you chose to manually activate users, for each user that needs to access IBM Cloud Private Cloud Foundry, run the following command. <username> is an LDAP user ID that matches the userDNPattern or searchFilter property in the LDAP configuration, depending on the binding method you selected:

cf create-user <username> --origin ldap

Revoking user access

If you chose to manually activate users, you can revoke access for a user by deleting their account:

cf delete-user <username>

Otherwise, in addition to deleting the user by using the cf CLI, to revoke user access the user must be removed from LDAP. Or the user's group membership must be changed such that they no longer meet the criteria as defined by your LDAP binding configuration.

Assigning users to organizations and spaces

LDAP users cannot be automatically granted access to specific organizations or spaces, but you can grant permission before first login by first activating the user with the cf create-user <username> --origin ldap command and then assigning organization and space roles as usual. For more information, see Managing user permissions to organizations and spaces. These actions might be scripted if you have many LDAP users that you want to assign to certain organizations and spaces based on information in their LDAP records.

Mapping LDAP groups to scopes

If you chose to use groups-map-to-scopes to automatically assign extra privilege scopes to LDAP users based on the group membership, you can use the uaac CLI to manage the mappings.

Install the uaac Ruby gem by using the following command:
```
gem install cf-uaac
```
Target the UAA server of your installation. Replace <bluemix_env_domain> with the environment domain used for your installation. Add the --skip-ssl-validation option to the command if your environment domain certificate is self-signed.
```
uaac target https://uaa.<bluemix_env_domain>
```
Find the UAA admin client secret.
- For IBM Cloud Private Cloud Foundry, log in with the uaac CLI by finding the uaa_admin_client_secret value in the file <data_directory>/CloudFoundry/deployment-vars.yml.
- For Cloud Foundry Enterprise Environment, obtain the <uaa_admin_client_secret> value by running the following command:
```
kubectl get -n uaa secret secrets -o jsonpath='{.data.uaa-admin-client-secret}' | base64 --decode
```
Substitute the UAA admin client secret into the following command:
```
uaac token client get admin -s <uaa_admin_client_secret>
```

Now you can manage group mappings by issuing commands as shown in the following example:

uaac group mappings                      # List all group mappings
uaac group map --name <scope> <groupDN>  # Create a new group mapping by specifying the privilege scope
                                         #   and distinguished name (DN) of the LDAP group
uaac group unmap <scope> <groupDN>       # Delete a group mapping by specifying the privilege scope
                                         #   and distinguished name (DN) of the LDAP group
uaac user get <username>                 # Retrieve user information to verify which groups have been mapped