Configuring LDAP authentication for IBM Cloud Private Cloud Foundry

You can use LDAP authentication for user authentication in IBM Cloud Private Cloud Foundry.

You can follow these instructions to configure LDAP authentication before running the launch_deployment.sh script during installation of IBM Cloud Private Cloud Foundry (see Installing IBM Cloud Private Cloud Foundry) or at any time after installation. 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 user interface, the cfp-ext-ldap extension offers guided editing of the configuration values. Select a configuration type of Simple Binding, Search and Bind, Groups Map to Scopes, or Groups as Scopes. The user interface displays the required and optional configuration values for the selected scenario. The user interface provides descriptions, sample values, and validation of the configuration values. For information about extensions, see 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 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 wish 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 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 using the chosen LDAP binding method will be automatically activated when they first log in to IBM Cloud Private Cloud Foundry. If you prefer to allow login only for users that have been manually activated, set add_shadow_user_on_login to false.

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.

Deploying IBM Cloud Private Cloud Foundry with the cfp-ext-ldap extension

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 deployment. The following command adds the deployment of the LDAP extension before the deployment of the IBM Cloud Private Cloud Foundry 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
```
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>
```

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 given user by deleting their account:

cf delete-user <username>

Otherwise, in addition to deleting the user using the cf CLI, to revoke user access the user must be removed from LDAP or their group membership 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 could be scripted if you have a large number of 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 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>
```
Log in with the uaac CLI by finding the uaa_admin_client_secret value in the file <data_directory>/CloudFoundry/deployment-vars.yml and substituting it 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