Configuring an LDAP identity provider

    By default, only a kubeadmin user exists on your cluster. To specify an identity provider, you must create a custom resource (CR) that describes that identity provider and add it to the cluster.

    About LDAP authentication

    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.

    These are the steps taken:

    1. Generate a search filter by combining the attribute and filter in the configured url with the user-provided user name.

    2. Search the directory using the generated filter. If the search does not return exactly one entry, deny access.

    3. Attempt to bind to the LDAP server using the DN of the entry retrieved from the search, and the user-provided password.

    4. If the bind is unsuccessful, deny access.

    5. If the bind is successful, build an identity using the configured attributes as the identity, email address, display name, and preferred user name.

    The configured url is an RFC 2255 URL, which specifies the LDAP host and search parameters to use. The syntax of the URL is:

    For this URL:

    URL componentDescription

    ldap

    For regular LDAP, use the string ldap. For secure LDAP (LDAPS), use ldaps instead.

    host:port

    The name and port of the LDAP server. Defaults to localhost:389 for ldap and localhost:636 for LDAPS.

    The DN of the branch of the directory where all searches should start from. At the very least, this must be the top of your directory tree, but it could also specify a subtree in the directory.

    attribute

    The attribute to search for. Although RFC 2255 allows a comma-separated list of attributes, only the first attribute will be used, no matter how many are provided. If no attributes are provided, the default is to use uid. It is recommended to choose an attribute that will be unique across all entries in the subtree you will be using.

    scope

    The scope of the search. Can be either one or sub. If the scope is not provided, the default is to use a scope of sub.

    filter

    A valid LDAP search filter. If not provided, defaults to (objectClass=*)

    When doing searches, the attribute, filter, and provided user name are combined to create a search filter that looks like:

    1. (&(<filter>)(<attribute>=<username>))

    For example, consider a URL of:

    1. ldap://ldap.example.com/o=Acme?cn?sub?(enabled=true)

    When a client attempts to connect using a user name of bob, the resulting search filter will be (&(enabled=true)(cn=bob)).

    If the LDAP directory requires authentication to search, specify a bindDN and bindPassword to use to perform the entry search.

    To use the identity provider, you must define an OKD Secret object that contains the bindPassword field.

    Procedure

    • Create a Secret object that contains the field:

      You can alternatively apply the following YAML to create the secret:

      1. apiVersion: v1
      2. kind: Secret
      3. metadata:
      4.   name: ldap-secret
      5.   namespace: openshift-config
      6. data:
      7.   bindPassword: <base64_encoded_bind_password>

    Creating a config map

    Procedure

    • Define an OKD ConfigMap object containing the certificate authority by using the following command. The certificate authority must be stored in the ca.crt key of the ConfigMap object.

      1. $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config

    The following custom resource (CR) shows the parameters and acceptable values for an LDAP identity provider.

    LDAP CR

    1. apiVersion: config.openshift.io/v1
    2. kind: OAuth
    3. metadata:
    4.   name: cluster
    5. spec:
    6.   identityProviders:
    7.   - name: ldapidp (1)
    8.     mappingMethod: claim (2)
    9.     type: LDAP
    10.     ldap:
    11.       attributes:
    12.         id: (3)
    13.         - dn
    14.         email: (4)
    16.         - cn
    17.         preferredUsername: (6)
    18.         - uid
    19.       bindDN: "" (7)
    20.       bindPassword: (8)
    21.         name: ldap-secret
    22.       ca: (9)
    23.         name: ca-config-map
    24.       insecure: false (10)
    25.       url: "ldap://ldap.example.com/ou=users,dc=acme,dc=com?uid" (11)
    1This provider name is prefixed to the returned user ID to form an identity name.
    2Controls how mappings are established between this provider’s identities and User objects.
    3List of attributes to use as the identity. First non-empty attribute is used. At least one attribute is required. If none of the listed attribute have a value, authentication fails. Defined attributes are retrieved as raw, allowing for binary values to be used.
    4List of attributes to use as the email address. First non-empty attribute is used.
    5List of attributes to use as the display name. First non-empty attribute is used.
    6List of attributes to use as the preferred user name when provisioning a user for this identity. First non-empty attribute is used.
    7Optional DN to use to bind during the search phase. Must be set if bindPassword is defined.
    8Optional reference to an OKD Secret object containing the bind password. Must be set if bindDN is defined.
    9Optional: Reference to an OKD ConfigMap object containing the PEM-encoded certificate authority bundle to use in validating server certificates for the configured URL. Only used when insecure is false.
    10When true, no TLS connection is made to the server. When false, ldaps:// URLs connect using TLS, and ldap:// URLs are upgraded to TLS. This must be set to false when ldaps:// URLs are in use, as these URLs always attempt to connect using TLS.
    11An RFC 2255 URL which specifies the LDAP host and search parameters to use.

    Additional resources

    Adding an identity provider to your clusters

    After you install your cluster, add an identity provider to it so your users can authenticate.

    Prerequisites

    • Create an OKD cluster.

    • Create the custom resource (CR) for your identity providers.

    • You must be logged in as an administrator.

    Procedure

    1. Apply the defined CR:

      1. $ oc apply -f </path/to/CR>

      If a CR does not exist, oc apply creates a new CR and might trigger the following warning: . In this case you can safely ignore this warning.

    3. Confirm that the user logged in successfully, and display the user name.

      1. $ oc whoami