Chapter 12. Advanced LDAP Configuration

12.1. Overview

OpenShift Enterprise Advanced Lightweight Directory Access Protocol (LDAP) Configuration covers the following topics:

12.2. Setting up SSSD for LDAP Failover

12.2.1. Overview

OpenShift Enterprise provides an authentication provider for use with Lightweight Directory Access Protocol (LDAP) setups, but it can only connect to a single LDAP server. This can be problematic if that LDAP server becomes unavailable. System Security Services Daemon (SSSD) can be used to solve the issue.

Originally designed to manage local and remote authentication to the host operating system, SSSD can now be configured to provide identity, authentication, and authorization services to web services like OpenShift Enterprise. SSSD provides advantages over the built-in LDAP provider, including the ability to connect to any number of failover LDAP servers, as well as the ability to cache authentication attempts in case it can no longer reach any of those servers.

The setup for this configuration is advanced and requires a separate authentication server (also called an authenticating proxy) for OpenShift Enterprise to communicate with. This topic describes how to do this setup on a dedicated physical or virtual machine (VM), but the concepts are also applicable to a setup in a container.

12.2.2. Prerequisites for Authenticating Proxy Setup

  1. 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.
  2. Prepare the VMs:

    • A VM to use as the authenticating proxy. This machine must have at least SSSD 1.12.0 available, which means a fairly recent operating system. This topic uses a Red Hat Enterprise Linux 7.2 server for its examples.
    • A VM to use to run OpenShift Enterprise.

These VMs can be configured to run on the same system, but for the examples used in this topic they are kept separate.

12.2.3. Phase 1: Certificate Generation

  1. To ensure that communication between the authenticating proxy and OpenShift Enterprise is trustworthy, create a set of Transport Layer Security (TLS) certificates to use during the other phases of this setup. In the OpenShift Enterprise system, start by using the auto-generated certificates created as part of running:

    # openshift start \
        --public-master= \

    Among other things, this generates a /etc/origin/master/ca.{cert|key}. Use this signing certificate to generate keys to use on the authenticating proxy.

    # mkdir -p /etc/origin/proxy/
    # oadm ca create-server-cert \
        --cert='/etc/origin/proxy/' \
        --key='/etc/origin/proxy/' \ \
        --signer-cert=/etc/origin/master/ca.crt \
        --signer-key='/etc/origin/master/ca.key' \

    Ensure that any host names and interface IP addresses that need to access the proxy are listed. Otherwise, the HTTPS connection will fail.

  2. Create a new CA to sign this client certificate:

    # oadm ca create-signer-cert \
      --cert='/etc/origin/proxy/proxyca.crt' \
      --key='/etc/origin/proxy/proxyca.key' \
      --name='openshift-proxy-signer@UNIQUESTRING' \ 1
    Make UNIQUESTRING something unique.
  3. Generate the API client certificate that the authenticating proxy will use to prove its identity to OpenShift Enterprise.

    # oadm create-api-client-config \
        --certificate-authority='/etc/origin/proxy/proxyca.crt' \
        --client-dir='/etc/origin/proxy' \
        --signer-cert='/etc/origin/proxy/proxyca.crt' \
        --signer-key='/etc/origin/proxy/proxyca.key' \
        --signer-serial='/etc/origin/proxy/proxyca.serial.txt' \

    This prevents malicious users from impersonating the proxy and sending fake identities.

  4. Copy the certificate and key information to the appropriate file for future steps:

    # cat /etc/origin/proxy/system\:proxy.crt \
          /etc/origin/proxy/system\:proxy.key \
          > /etc/origin/proxy/authproxy.pem

12.2.4. Phase 2: Authenticating Proxy Setup

This section guides you through the steps to authenticate the proxy setup. Step 1: Copy Certificates

From, securely copy the necessary certificates to the proxy machine:

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

# scp /etc/origin/proxy/ \
      /etc/origin/proxy/authproxy.pem \

# scp /etc/origin/proxy/ \ Step 2: SSSD Configuration

  1. Install a new VM with an operating system that includes 1.12.0 or later so that you can use the mod_identity_lookup module. The examples in this topic use a Red Hat Enterprise Linux 7.2 Server.
  2. Install all of the necessary dependencies:

    # yum install -y sssd \
                     sssd-dbus \
                     realmd \
                     httpd \
                     mod_session \
                     mod_ssl \
                     mod_lookup_identity \

    This gives you the needed SSSD and the web server components.

  3. Edit the /etc/httpd/conf.modules.d/55-authnz_pam.conf file and remove the comment from the following:

    LoadModule authnz_pam_module modules/
  4. Set up SSSD to authenticate this VM against the LDAP server. If the LDAP server is a FreeIPA or Active Directory environment, then realmd can be used to join this machine to the domain.

    # realm join

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

    If you want to use SSSD to manage failover situations for LDAP, this can be configured by adding additional entries in /etc/sssd/sssd.conf on the ldap_uri line. Systems enrolled with FreeIPA can automatically handle failover using DNS SRV records.

  5. Restart SSSD to ensure that all of the changes are applied properly:

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

    $ getent passwd <username>
    username:*:12345:12345:Example User:/home/username:/usr/bin/bash
  7. Attempt to log into the VM as an LDAP user and confirm that the authentication is properly set up. This can be done via the local console or a remote service such as SSH.

If you do not want LDAP users to be able to log into this machine, it is recommended to modify /etc/pam.d/system-auth and /etc/pam.d/password-auth to remove the lines containing Step 3: Apache Configuration

You need to set up Apache to communicate with SSSD. Create a PAM stack file for use with Apache. To do so:

  1. Create the /etc/pam.d/openshift file and add 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. Configure the Apache httpd.conf. The steps in this section focus on setting up the challenge authentication, which is useful for logging in with oc login and similar automated tools.


    Configuring Form-Based Authentication explains how to set up a graphical login using SSSD as well, but it requires the rest of this setup as a prerequisite.

  3. Create the new file openshift-proxy.conf in /etc/httpd/conf.d (substituting the correct host names where indicated):

    LoadModule request_module modules/
    LoadModule lookup_identity_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
      SSLEngine on
      SSLCertificateFile /etc/pki/tls/certs/
      SSLCertificateKeyFile /etc/pki/tls/private/
      SSLCACertificateFile /etc/pki/CA/certs/ca.crt
      # Send logs to a specific location to make them easier to find
      ErrorLog logs/proxy_error_log
      TransferLog logs/proxy_access_log
      LogLevel warn
      SSLProxyEngine on
      SSLProxyCACertificateFile /etc/pki/CA/certs/ca.crt
      # It's critical to enforce client certificates on the Master.  Otherwise
      # requests could spoof the X-Remote-User header by accessing the Master's
      # /oauth/authorize endpoint directly.
      SSLProxyMachineCertificateFile /etc/pki/tls/certs/authproxy.pem
      # Send all requests to the console
      RewriteEngine              On
      RewriteRule     ^/console(.*)$     https://%{HTTP_HOST}:8443/console$1 [R,L]
      # In order to using the challenging-proxy an X-Csrf-Token must be present.
      RewriteCond %{REQUEST_URI} ^/challenging-proxy
      RewriteCond %{HTTP:X-Csrf-Token} ^$ [NC]
      RewriteRule ^.* - [F,L]
      <Location /challenging-proxy/oauth/authorize>
        # Insert your backend server name/ip here.
        AuthType Basic
        AuthBasicProvider PAM
        AuthPAMService openshift
        Require valid-user
      <ProxyMatch /oauth/authorize>
        AuthName openshift
        RequestHeader set X-Remote-User %{REMOTE_USER}s env=REMOTE_USER
    RequestHeader unset X-Remote-User

    Configuring Form-Based Authentication explains how to add the login-proxy block to support form authentication.

  4. 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
  5. Start up Apache:

    # systemctl start httpd.service

12.2.5. Phase 3: OpenShift Enterprise Configuration

This section describes how to set up an OpenShift Enterprise server from scratch in an "all in one" configuration. Master and Node Configuration provides more information on alternate configurations.

Modify the default configuration to use the new identity provider just created. To do so:

  1. Modify the /etc/origin/master/master-config.yaml file.
  2. Scan through it and locate the identityProviders section and replace it with:

      - name: any_provider_name
        challenge: true
        login: false
        mappingMethod: claim
          apiVersion: v1
          kind: RequestHeaderIdentityProvider
          challengeURL: "${query}"
          clientCA: /etc/origin/master/proxy/proxyca.crt
          - X-Remote-User

    Configuring Form-Based Authentication explains how to add the login URL to support web logins.

    Configuring Extended LDAP Attributes explains how to add the email and full-name attributes. Note that the full-name attributes are only stored to the database on the first login.

  3. Start OpenShift Enterprise with the updated configuration:

    # openshift start \
        --public-master= \
        --master-config=/etc/origin/master/master-config.yaml \
  4. Test logins:

    oc login

    It should now be possible to log in with only valid LDAP credentials.

12.3. Configuring Form-Based Authentication

12.3.1. Overview

This topic builds upon Setting up SSSD for LDAP Failover and describes how to set up form-based authentication for signing into the OpenShift Enterprise web console.

12.3.2. Prepare a Login Page

The OpenShift Enterprise upstream repositories have a template for forms. Copy that to your authenticating proxy on

# curl -o /var/www/html/login.html \

Modify this .html file to change the logo icon and "Welcome" content for your environment.

12.3.3. Install Another Apache Module

To intercept form-based authentication, install an Apache module:

 # yum -y install mod_intercept_form_submit

12.3.4. Apache Configuration

  1. Modify /etc/httpd/conf.modules.d/55-intercept_form_submit.conf and uncomment the LoadModule line.
  2. Add a new section to your openshift-proxy.conf file inside the <VirtualHost *:443> block.

     <Location /login-proxy/oauth/authorize>
      # Insert your backend server name/ip here.
      InterceptFormPAMService openshift
      InterceptFormLogin httpd_username
      InterceptFormPassword httpd_password
      RewriteCond %{REQUEST_METHOD} GET
      RewriteRule ^.*$ /login.html [L]

    This tells Apache to listen for POST requests on the /login-proxy/oauth/authorize and to pass the user name and password over to the openshift PAM service.

  3. Restart the service and move back over to the OpenShift Enterprise configuration.

12.3.5. OpenShift Enterprise Configuration

  1. In the master-config.yaml file, update the identityProviders section:

    - name: any_provider_name
      challenge: true
      login: true 1
      mappingMethod: claim
        apiVersion: v1
        kind: RequestHeaderIdentityProvider
        challengeURL: "${query}"
        loginURL: "${query}" 2
        clientCA: /etc/origin/master/proxy/proxyca.crt
        - X-Remote-User
    Note that login is set to true, not false.
    Newly added line.
  2. Restart OpenShift Enterprise with the updated configuration.


    You should be able to browse to and use your LDAP credentials to sign in via the login form.

12.4. Configuring Extended LDAP Attributes

12.4.1. Overview

This topic builds upon Setting up SSSD for LDAP Failover and Configuring Form-Based Authentication and focuses on configuring extended Lightweight Directory Access Protocol (LDAP) attributes.

12.4.2. Prerequisites

  • SSSD 1.12.0 or later. This is available on Red Hat Enterprise Linux 7.0 and later.
  • mod_lookup_identity 0.9.4 or later.

    • The required version is not yet available on any version of Red Hat Enterprise Linux. However, compatible packages (RPMs) are available from upstream until they arrive in Red Hat Enterprise Linux.

12.4.3. Configuring SSSD

You need to ask System Security Services Daemon (SSSD) to look up attributes in LDAP that it normally does not care about for simple system-login use-cases. In the case of OpenShift Enterprise, there is only one such attribute: email. So, you need to:

  1. Modify the [domain/DOMAINNAME] section of /etc/sssd/sssd.conf on the authenticating proxy and add this attribute:

    ldap_user_extra_attrs = mail
  2. Tell SSSD that it is acceptable for this attribute to be retrieved by Apache. Add the following two lines to the [ifp] section of /etc/sssd/sssd.conf:

    user_attributes = +mail
    allowed_uids = apache, root
  3. Restart SSSD:

    # systemctl restart sssd.service
  4. Test this configuration.

12.4.4. Configuring Apache

Now that SSSD is set up and successfully serving extended attributes, configure the web server to ask for them and to insert them in the correct places.

  1. Enable the module to be loaded by Apache. To do so, modify /etc/httpd/conf.modules.d/55-lookup_identity.conf and uncomment the line:

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

    # setsebool -P httpd_dbus_sssd on
  3. Edit /etc/httpd/conf.d/openshift-proxy.conf and add the following lines inside the <ProxyMatch /oauth/authorize> section:

    <ProxyMatch /oauth/authorize>
      AuthName openshift
      LookupOutput Headers 1
      LookupUserAttr mail X-Remote-User-Email 2
      LookupUserGECOS X-Remote-User-Display-Name 3
      RequestHeader set X-Remote-User %{REMOTE_USER}s env=REMOTE_USER
    1 2 3
    Added line.
  4. Restart Apache to pick up the changes:

    # systemctl restart httpd.service

12.4.5. Configuring OpenShift Enterprise

Tell OpenShift Enterprise where to find these new attributes during login. To do so:

  1. Edit the /etc/origin/master/master-config.yaml file and add the following lines to the identityProviders section:

     - name: sssd
     challenge: true
     login: true
     mappingMethod: claim
       apiVersion: v1
       kind: RequestHeaderIdentityProvider
       challengeURL: "${query}"
       loginURL: "${query}"
       clientCA: /home/example/workspace/openshift/configs/
       - X-Remote-User
       emailHeaders: 1
       - X-Remote-User-Email 2
       nameHeaders: 3
       - X-Remote-User-Display-Name 4
    1 2 3 4
    Added line.
  2. Launch OpenShift Enterprise with this updated configuration and log in to the web as a new user.

    You should see their full name appear in the upper-right of the screen. You can also verify with oc get identities -o yaml that both email addresses and full names are available.

12.4.6. Debugging Notes

Currently, OpenShift Enterprise only saves these attributes to the user at the time of the first login and does not update them again after that. So, while you are testing (and only while testing), run oc delete users,identities --all to clear the identities out so you can log in again.