Configuring LDAP failover


Prerequisites for configuring basic remote authentication

  • Before starting setup, you need to know the following information about your LDAP server:

    • Whether the directory server is powered by FreeIPA, Active Directory, or another LDAP solution.

    • The Uniform Resource Identifier (URI) for the LDAP server, for example,

    • The location of the CA certificate for the LDAP server.

    • Whether the LDAP server corresponds to RFC 2307 or RFC2307bis for user groups.

  • Prepare the servers:

    • A VM to use as the remote basic authentication server.

      • Select an operating system that includes SSSD version 1.12.0 for this server such as Red Hat Enterprise Linux 7.0 or later.

    • A new installation of OKD.

      • You must not have an authentication method configured for this cluster.

      • Do not start OKD on this cluster.

Generating and sharing certificates with the remote basic authentication server

Complete the following steps on the first master host listed in the Ansible host inventory file, by default /etc/ansible/hosts.

  1. To ensure that communication between the remote basic authentication server and OKD is trustworthy, create a set of Transport Layer Security (TLS) certificates to use during the other phases of this set up. Run the following command:

    # openshift start \
        --public-master= \

    The output inclues the /etc/origin/master/ca.crt and /etc/origin/master/ca.key signing certificates.

  2. Use the signing certificate to generate keys to use on the remote basic authentication server:

    # mkdir -p /etc/origin/remote-basic/
    # oc adm ca create-server-cert \
        --cert='/etc/origin/remote-basic/' \
        --key='/etc/origin/remote-basic/' \ \ (1)
        --signer-cert='/etc/origin/master/ca.crt' \
        --signer-key='/etc/origin/master/ca.key' \
    1 A comma-separated list of all the host names and interface IP addresses that need to access the remote basic authentication server.

    The certificate files that you generate are valid for two years. You can alter this period by changing the --expire-days and --signer-expire-days values, but for security reasons, do not make them greater than 730.

    If you do not list all host names and interface IP addresses that need to access the remote basic authentication server, the HTTPS connection will fail.

  3. Copy the necessary certificates and key to the remote basic authentication server:

    # scp /etc/origin/master/ca.crt \

    # scp /etc/origin/remote-basic/ \

    # scp /etc/origin/remote-basic/ \

Configuring SSSD for LDAP failover

Complete these steps on the remote basic authentication server.

You can configure the SSSD to retrieve attributes, such as email addresses and display names, and pass them to OKD to display in the web interface. In the following steps, you configure the SSSD to provide email addresses to OKD:

  1. Install the required SSSD and the web server components:

    # yum install -y sssd \
                     sssd-dbus \
                     realmd \
                     httpd \
                     mod_session \
                     mod_ssl \
                     mod_lookup_identity \
                     mod_authnz_pam \
                     php \
  2. Set up SSSD to authenticate this VM against the LDAP server. If the LDAP server is a FreeIPA or Active Directory environment, then use realmd to join this machine to the domain.

    # realm join

    For more advanced cases, see the System-Level Authentication Guide

  3. To use SSSD to manage failover situations for LDAP, add more entries to the /etc/sssd/sssd.conf file on the ldap_uri line. Systems that are enrolled with FreeIPA can automatically handle failover by using DNS SRV records.

  4. Modify the [domain/DOMAINNAME] section of the /etc/sssd/sssd.conf file and add this attribute:

    ldap_user_extra_attrs = mail (1)
    1 Specify the correct attribute to retrieve email addresses for your LDAP solution. For IPA, specify mail. Other LDAP solutions might use another attribute, such as email.
  5. Confirm that the domain parameter in the /etc/sssd/sssd.conf file contains only the domain name listed in the [domain/DOMAINNAME] section.

    domains =
  6. Grant Apache permission to retrieve the email attribute. Add the following lines to the [ifp] section of the /etc/sssd/sssd.conf file:

    user_attributes = +mail
    allowed_uids = apache, root
  7. To ensure that all of the changes are applied properly, restart SSSD:

    $ systemctl restart sssd.service
  8. Test that the user information can be retrieved properly:

    $ getent passwd <username>
    username:*:12345:12345:Example User:/home/username:/usr/bin/bash
  9. Confirm that the mail attribute you specified returns an email address from your domain:

    # dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe \
        /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserAttr \
        string:username \ (1)
        array:string:mail (2)
    method return time=1528091855.672691 sender=:1.2787 -> destination=:1.2795 serial=13 reply_serial=2
       array [
          dict entry(
             string "mail"
             variant             array [
                   string ""
    1 Provide a user name in your LDAP solution.
    2 Specify the attribute that you configured.
  10. Attempt to log into the VM as an LDAP user and confirm that you can log in using LDAP credentials. You can use either the local console or a remote service like SSH to log in.

By default, all users can log into the remote basic authentication server by using their LDAP credentials. You can change this behavior:

Configuring Apache to use SSSD

  1. Create a /etc/pam.d/openshift file that contains the following contents:

    auth required
    account required

    This configuration enables PAM, the pluggable authentication module, to use to determine authentication and access control when an authentication request is issued for the openshift stack.

  2. Edit the /etc/httpd/conf.modules.d/55-authnz_pam.conf file and uncomment the following line:

    LoadModule authnz_pam_module modules/
  3. To configure the Apache httpd.conf file for remote basic authentication, create the openshift-remote-basic-auth.conf file in the /etc/httpd/conf.d directory. Use the following template to provide your required settings and values:

    Carefully review the template and customize its contents to fit your environment.

    LoadModule request_module modules/
    LoadModule php7_module modules/
    # Nothing needs to be served over HTTP.  This virtual host simply redirects to
    # HTTPS.
    <VirtualHost *:80>
      DocumentRoot /var/www/html
      RewriteEngine              On
      RewriteRule     ^(.*)$     https://%{HTTP_HOST}$1 [R,L]
    <VirtualHost *:443>
      # This needs to match the certificates you generated.  See the CN and X509v3
      # Subject Alternative Name in the output of:
      # openssl x509 -text -in /etc/pki/tls/certs/
      DocumentRoot /var/www/html
      # Secure all connections with TLS
      SSLEngine on
      SSLCertificateFile /etc/pki/tls/certs/
      SSLCertificateKeyFile /etc/pki/tls/private/
      SSLCACertificateFile /etc/pki/CA/certs/ca.crt
      # Require that TLS clients provide a valid certificate
      SSLVerifyClient require
      SSLVerifyDepth 10
      # Other SSL options that may be useful
      # SSLCertificateChainFile ...
      # SSLCARevocationFile ...
      # Send logs to a specific location to make them easier to find
      ErrorLog logs/remote_basic_error_log
      TransferLog logs/remote_basic_access_log
      LogLevel warn
      # PHP script that turns the Apache REMOTE_USER env var
      # into a JSON formatted response that OpenShift understands
      <Location /check_user.php>
        # all requests not using SSL are denied
        # denies access when SSLRequireSSL is applied
        SSLOptions +StrictRequire
        # Require both a valid basic auth user (so REMOTE_USER is always set)
        # and that the CN of the TLS client matches that of the OpenShift master
          Require valid-user
          Require expr %{SSL_CLIENT_S_DN_CN} == 'system:openshift-master'
        # Use basic auth since OpenShift will call this endpoint with a basic challenge
        AuthType Basic
        AuthName openshift
        AuthBasicProvider PAM
        AuthPAMService openshift
        # Store attributes in environment variables. Specify the email attribute that
        # you confirmed.
        LookupOutput Env
        LookupUserAttr mail REMOTE_USER_MAIL
        # Other options that might be useful
        # While REMOTE_USER is used as the sub field and serves as the immutable ID,
        # REMOTE_USER_PREFERRED_USERNAME could be used to have a different username
        # LookupUserAttr <attr_name> REMOTE_USER_PREFERRED_USERNAME
        # Group support may be added in a future release
        # LookupUserGroupsIter REMOTE_USER_GROUP
      # Deny everything else
      <Location ~ "^((?!\/check_user\.php).)*$">
          Deny from all
  4. Create the check_user.php script in the /var/www/html directory. Include the following code:

    // Get the user based on the Apache var, this should always be
    // set because we 'Require valid-user' in the configuration
    $user = apache_getenv('REMOTE_USER');
    // However, we assume it may not be set and
    // build an error response by default
    $data = array(
        'error' => 'remote PAM authentication failed'
    // Build a success response if we have a user
    if (!empty($user)) {
        $data = array(
            'sub' => $user
        // Map of optional environment variables to optional JSON fields
        $env_map = array(
            'REMOTE_USER_MAIL' => 'email',
            'REMOTE_USER_DISPLAY_NAME' => 'name',
            'REMOTE_USER_PREFERRED_USERNAME' => 'preferred_username'
        // Add all non-empty environment variables to JSON data
        foreach ($env_map as $env_name => $json_name) {
            $env_data = apache_getenv($env_name);
            if (!empty($env_data)) {
                $data[$json_name] = $env_data;
    // We always output JSON from this script
    header('Content-Type: application/json', true);
    // Write the response as JSON
    echo json_encode($data);
  5. Enable Apache to load the module. Modify the /etc/httpd/conf.modules.d/55-lookup_identity.conf file and uncomment the following line:

    LoadModule lookup_identity_module modules/
  6. Set an SELinux boolean so that SElinux allows Apache to connect to SSSD over D-BUS:

    # setsebool -P httpd_dbus_sssd on
  7. Set a boolean to tell SELinux that it is acceptable for Apache to contact the PAM subsystem:

    # setsebool -P allow_httpd_mod_auth_pam on
  8. Start Apache:

    # systemctl start httpd.service

Configuring OKD to use SSSD as the basic remote authentication server

Modify the default configuration of your cluster to use the new identity provider that you created. Complete the following steps on the first master host listed in the Ansible host inventory file.

  1. Open the /etc/origin/master/master-config.yaml file.

  2. Locate the identityProviders section and replace it with the following code:

      - name: sssd
        challenge: true
        login: true
        mappingMethod: claim
          apiVersion: v1
          kind: BasicAuthPasswordIdentityProvider
          ca: /etc/origin/master/ca.crt
          certFile: /etc/origin/master/openshift-master.crt
          keyFile: /etc/origin/master/openshift-master.key
  3. Restart OKD with the updated configuration:

    # /usr/local/bin/master-restart api api
    # /usr/local/bin/master-restart controllers controllers
  4. Test a login by using the oc CLI:

    $ oc login

    You can log in only with valid LDAP credentials.

  5. List the identities and confirm that an email address is displayed for each user name. Run the following command:

    $ oc get identity -o yaml