LDAP Integration for Authentication

LDAP Users and their Access to OpenShift
- Example LDAP Tree Structure
Configure OpenShift to use LDAP for User Authentication
Testing LDAP queries
- ldapsearch
What''s Next?
Resources

The OpenShift Container Platform provides support for leveraging users and groups stored in an Lightweight Directory Access Protocol (LDAP) V3 server using simple bind authentication.

The official OpenShift documentation provides a high level overview for authenticating a user against an LDAP server:

During authentication, the LDAP directory is searched for an entry that matches the provided user name. If a single unique match is found, a simple bind is attempted using the distinguished name (DN) of the entry plus the provided password.

— Configuring Authentication and User Agent
https://docs.openshift.com/container-platform/3.7/install_config/configuring_authentication.html

LDAP Users and their Access to OpenShift

Once it has been determined that access to OpenShift will be governed by users defined in an LDAP server, the next step is to determine the criteria for determining a valid user. Common use cases are listed below:

A user exists either at the same level or underneath a particular location of the LDAP tree (known as a base DN)
A user must be a member of a particular LDAP group

Note	The conditions above assume the user has provided valid credentials

Example LDAP Tree Structure

The organization and structure of objects in an LDAP server is critical for its interaction with OpenShift. The following is an example of an LDAP structure that will be used for the rest of the discussion:

+ dc=example,dc=com # domain/organization
  + dn: ou=Users,dc=myorg,dc=com
    + dn: uid=jdoe,ou=Users,dc=myorg,dc=com
      cn: jdoe
      givenName: John Doe
      mail: jdoe@myorg.com
      member: uid=admins,ou=Groups,dc=myorg,dc=com
      member: uid=openshift,ou=Groups,dc=myorg,dc=com
      phone: 919-555-1234
      uid: jdoe
    + dn: uid=csmith,ou=Users,dc=myorg,dc=com
      cn: csmith
      uid: csmith
      mail: csmith@redhat.com
      member: uid=openshift,ou=Groups,dc=myorg,dc=com
      givenName: Chris Smith
      phone: 919-555-4321
  + dn: ou=Groups,dc=myorg,dc=com
    + dn: uid=admins,ou=Groups,dc=myorg,dc=com
      member: uid=jdoe,ou=Users,dc=myorg,dc=com
    + dn: uid=openshift,ou=Groups,dc=myorg,dc=com
      member: uid=jdoe,ou=Users,dc=myorg,dc=com
      member: uid=csmith,ou=Users,dc=myorg,dc=com

Two primary organizational units (OU) are defined within the myorg.com domain (ou=Users,dc=myorg,dc=com and dn: ou=Groups,dc=myorg,dc=com). This example represents a flat hierarchy where all users within the organization are contained within the Users OU and all groups are contained within the Groups OU.

Configure OpenShift to use LDAP for User Authentication

To configure OpenShift to restrict access to the platform based on users managed in an LDAP server, an Identity Provider leveraging the LDAPPasswordIdentityProvider must be configured. The following information must be available to configure LDAP based authentication:

Username (referred to Bind DN) and password (referred to Bind Password) of a user that has access to traverse the LDAP tree (if anonymous access disabled)
Protocol, hostname and port of the LDAP server
CA bundle of the LDAP server (if secured. It is recommended that communication occur over a secure connection)
Base DN location for which users will be searched
Additional filtering logic, such as the scope of the user query and a filter (optional)

The LDAPPasswordIdentityProvider provider can be configured either by editing the OpenShift master configuration file located at /etc/origin/master/master-config.yaml or through the Ansible based installer.

The LDAP Identity Provider

Based on the previous LDAP tree structure, to allow any authenticated user from the set of users defined in the ou=Users,dc=myorg,dc=com OU, specify the following Identity Provider configuration:

  identityProviders:
  - name: "my_ldap_provider"
    challenge: true
    login: true
    provider:
      apiVersion: v1
      kind: LDAPPasswordIdentityProvider (1)
      attributes:
        id:
        - dn (2)
        email:
        - mail (3)
        name:
        - cn  (4)
        preferredUsername:
        - uid (5)
      bindDN: "" (6)
      bindPassword: "" (7)
      ca: my-ldap-ca-bundle.crt (8)
      insecure: false (9)
      url: "ldaps://ldap.example.com/ou=Users,dc=myorg,dc=com?uid" (10)

The name of the LDAP Identity Provider
The LDAP field of the user to use as the unique identifier within OpenShift
The LDAP field of the user to use as their email address
The LDAP field of the user to use as their friendly name
The LDAP field of the user to use as their user name when logging into OpenShift
The distinguished name (DN) of the user used to traverse the LDAP tree and validate users
The Password of the user used to traverse the LDAP tree to validate users. This value may also be provided in an environment variable, external file, or encrypted file.
If communicating securely and the certificate is not in the system trust store, the location of the CA bundle
Whether to communicates securely with the LDAP server (true by default)
RFC 2255 based URL specifying the host and search parameters.

Note	If anonymous bind access is enabled, the `bindDN` and `bindPassword` options can be set as `""`

In the example above, the url parameter specifies that the query connect securely to the LDAP server on 636 (389 if not connecting securely). The baseDN which indicates where all searches should start from is specified after the /. uid references the LDAP attribute that should be used to match username provided by the user attempting to log in.

Another option is to add a filter to the query in which to further limit the users that are allowed to authenticate to OpenShift. To limit only user who are members of the openshift group, the (member=uid=admins,ou=Groups,dc=myorg,dc=com) can be applied which results in a url represented as url: "ldaps://ldap.myorg.com/ou=Users,dc=myorg,dc=com?uid??(member=uid=admins,ou=Groups,dc=myorg,dc=com).

OpenShift Ansible Configuration

The Ansible based OpenShift installer contains functionality to automate the configuration of the LDAPPasswordIdentityProvider. Several cluster variables of the Ansible inventory can be specified to tune the configuration of identity providers. For LDAP, these include:

openshift_master_identity_providers - An array of identity providers to configure within the OpenShift master configuration file
openshift_master_ldap_ca - Text value of the LDAP CA
openshift_master_ldap_ca_file - Location of the LDAP CA file on the Ansible control host. This file will be copied to the OpenShift master configuration directory (/etc/origin/master)

The following can be added to the [OSEv3:vars] section of the OpenShift inventory file to configure the LDAPPasswordIdentityProvider for the LDAP structure referenced above.

[OSEv3:vars]
...
openshift_master_identity_providers=[{'name': 'my_ldap_provider', 'challenge': 'true', 'login': 'true', 'kind': 'LDAPPasswordIdentityProvider', 'attributes': {'id': ['dn'], 'email': ['mail'], 'name': ['cn'], 'preferredUsername': ['uid']}, 'bindDN': '', 'bindPassword': '', 'ca': 'my-ldap-ca-bundle.crt', 'insecure': 'false', 'url': 'ldap://ldap.myorg.com:389/uid=users,dc=myorg,dc=com?uid'}]
openshift_master_ldap_ca_file=/home/myuser/my-ldap-ca-bundle.crt
...

Run the ansible-playbook command referencing the inventory file and playbook which will be used to apply the changes to the cluster.

ansible-playbook -i c1-ocp.myorg.com/hosts /usr/share/ansible/openshift-ansible/playbooks/byo/config.yml

Manual Configuration

Instead of using Ansible, the LDAPPasswordIdentityProvider can be configured manually by modifying the OpenShift master configuration file located at /etc/orgin/master/master-config.yaml

Locate the identityProviders section of the OpenShift master configuration located at /etc/origin/master/master-config.yaml and configure the section with the value provided in the previous section.

Once complete, restart the atomic-openshift-master-api (or atomic-openshift-master if running a single master) service to apply and enable the changes

systemctl restart atomic-openshift-master-api

Important

These configurations must be applied on each master instance

Testing LDAP queries

As part of the configuring OpenShift to make use of an LDAP server, it may be helpful to manually connect and perform queries against the server in order to validate the configurations.

There are several tools available that allow for browsing an LDAP server:

ldapsearch - Linux based command line query tool
JXplorer - Cross platform LDAP browser and editor

ldapsearch

To make use of the ldapsearch tool, first ensure that it is installed on the local machine:

yum install -y openldap-clients -y

Common Use Cases

Common use cases for using the ldapsearch tool include searching for users, groups and members within a group. The following are examples of each of these queries:

Search for a user

ldapsearch -h ldap.myorg.com -p 636 -x -s base -b uid=jdoe,ou=Users,dc=myorg,dc=com

Search for groups

ldapsearch -h ldap.example.com -p 636 -x -s sub -b "ou=Groups,dc=myorg,dc=com" "objectClass: groupOfUniqueNames"

Get members of a group

ldapsearch -h ldap.myorg.com -p 636 -x -s base -b "uid=openshift,ou=Groups,dc=myorg,dc=com" "member"

In each of the above queries, the following signify the parameters being specified:

-h - The LDAP Host
-p - The LDAP port
-x - Perform a simple bind
-Z - Connect via TLS
-b - Base DN where all queries should start from
-s - Search scope of the query

Common Issues

When using ldapsearch, issues can arise that affect the operation and expected results.

TLS: can’t accept: TLS error -12195:Peer does not recognize and trust the CA that issued your certificate..

The CA to a secure LDAP server is not currently trusted by ldapsearch. Modify the /etc/openldap/ldap.conf file to include either a directory containing the certificates or a certificate bundle file

TLS_CACERTDIR   /etc/openldap/certs (1)
TLS_CACERT      /etc/openldap/certs/ca.cert.pem (2)

Directory containing certificates
Location of the CA bundle

What''s Next?

This guide focused on authenticating users into OpenShift against an LDAP server. To synchronize groups defined within the LDAP server into OpenShift, please refer to the LDAP Group Synchronization guide.