Configuring LDAP failover

OKD provides an authentication provider for use with Lightweight Directory Access Protocol (LDAP) setups, but it can connect to only a single LDAP server. During OKD installation, you can configure the System Security Services Daemon (SSSD) for LDAP failover to ensure access to your cluster if one LDAP server fails.

The setup for this configuration is advanced and requires a separate authentication server, also called an remote basic authentication server, for OKD to communicate with. You configure this server to pass extra attributes, such as email addresses, to OKD so it can display them in the web console.

This topic describes how to complete this set up on a dedicated physical or virtual machine (VM), but you can also configure SSSD in containers.

You must complete all sections of this topic.

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, ldap.example.com.

    • 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:

    • remote-basic.example.com: 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.
  1. -   ***openshift.example.com***: A new installation of OKD.
  3.     -   You must not have an authentication method configured for this cluster.
  5.     -   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:

    1. # openshift start \
    2.     --public-master=https://openshift.example.com:8443 \
    3.     --write-config=/etc/origin/

    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:

    1. # mkdir -p /etc/origin/remote-basic/
    2. # oc adm ca create-server-cert \
    3.     --cert='/etc/origin/remote-basic/remote-basic.example.com.crt' \
    4.     --key='/etc/origin/remote-basic/remote-basic.example.com.key' \
    5.     --hostnames=remote-basic.example.com \ (1)
    6.     --signer-cert='/etc/origin/master/ca.crt' \
    7.     --signer-key='/etc/origin/master/ca.key' \
    8.     --signer-serial='/etc/origin/master/ca.serial.txt'
    1A 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:

    1. # scp /etc/origin/master/ca.crt \
    2.       root@remote-basic.example.com:/etc/pki/CA/certs/
    4. # scp /etc/origin/remote-basic/remote-basic.example.com.crt \
    5.       root@remote-basic.example.com:/etc/pki/tls/certs/
    7. # scp /etc/origin/remote-basic/remote-basic.example.com.key \
    8.       root@remote-basic.example.com:/etc/pki/tls/private/

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:

    1. # yum install -y sssd \
    2.                  sssd-dbus \
    3.                  realmd \
    4.                  httpd \
    5.                  mod_session \
    6.                  mod_ssl \
    7.                  mod_lookup_identity \
    8.                  mod_authnz_pam \
    9.                  php \
    10.                  mod_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.

    1. # realm join ldap.example.com

    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:

    1. [domain/example.com]
    2. ...
    3. ldap_user_extra_attrs = mail (1)
    1Specify 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.

    1. domains = example.com

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

    1. [ifp]
    2. user_attributes = +mail
    3. allowed_uids = apache, root

  7. To ensure that all of the changes are applied properly, restart SSSD:

    1. $ systemctl restart sssd.service

  8. Test that the user information can be retrieved properly:

    1. $ getent passwd <username>
    2. 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:

    1. # dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe \
    2.     /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserAttr \
    3.     string:username \ (1)
    4.     array:string:mail (2)
    6. method return time=1528091855.672691 sender=:1.2787 -> destination=:1.2795 serial=13 reply_serial=2
    7.    array [
    8.       dict entry(
    9.          string "mail"
    10.          variant             array [
    11.                string "username@example.com"
    12.             ]
    13.       )
    14.    ]
    1Provide a user name in your LDAP solution.
    2Specify 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:

    1. auth required pam_sss.so
    2. account required pam_sss.so

    This configuration enables PAM, the pluggable authentication module, to use pam_sss.so 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:

    1. LoadModule authnz_pam_module modules/mod_authnz_pam.so

  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.

    1. LoadModule request_module modules/mod_request.so
    2. LoadModule php7_module modules/libphp7.so
    4. # Nothing needs to be served over HTTP.  This virtual host simply redirects to
    5. # HTTPS.
    6. <VirtualHost *:80>
    7.   DocumentRoot /var/www/html
    8.   RewriteEngine              On
    9.   RewriteRule     ^(.*)$     https://%{HTTP_HOST}$1 [R,L]
    10. </VirtualHost>
    12. <VirtualHost *:443>
    13.   # This needs to match the certificates you generated.  See the CN and X509v3
    14.   # Subject Alternative Name in the output of:
    15.   # openssl x509 -text -in /etc/pki/tls/certs/remote-basic.example.com.crt
    16.   ServerName remote-basic.example.com
    18.   DocumentRoot /var/www/html
    20.   # Secure all connections with TLS
    21.   SSLEngine on
    22.   SSLCertificateFile /etc/pki/tls/certs/remote-basic.example.com.crt
    23.   SSLCertificateKeyFile /etc/pki/tls/private/remote-basic.example.com.key
    24.   SSLCACertificateFile /etc/pki/CA/certs/ca.crt
    26.   # Require that TLS clients provide a valid certificate
    27.   SSLVerifyClient require
    28.   SSLVerifyDepth 10
    30.   # Other SSL options that may be useful
    31.   # SSLCertificateChainFile ...
    32.   # SSLCARevocationFile ...
    34.   # Send logs to a specific location to make them easier to find
    35.   ErrorLog logs/remote_basic_error_log
    36.   TransferLog logs/remote_basic_access_log
    37.   LogLevel warn
    39.   # PHP script that turns the Apache REMOTE_USER env var
    40.   # into a JSON formatted response that OpenShift understands
    41.   <Location /check_user.php>
    42.     # all requests not using SSL are denied
    43.     SSLRequireSSL
    44.     # denies access when SSLRequireSSL is applied
    45.     SSLOptions +StrictRequire
    46.     # Require both a valid basic auth user (so REMOTE_USER is always set)
    47.     # and that the CN of the TLS client matches that of the OpenShift master
    48.     <RequireAll>
    49.       Require valid-user
    50.       Require expr %{SSL_CLIENT_S_DN_CN} == 'system:openshift-master'
    51.     </RequireAll>
    52.     # Use basic auth since OpenShift will call this endpoint with a basic challenge
    53.     AuthType Basic
    54.     AuthName openshift
    55.     AuthBasicProvider PAM
    56.     AuthPAMService openshift
    58.     # Store attributes in environment variables. Specify the email attribute that
    59.     # you confirmed.
    60.     LookupOutput Env
    61.     LookupUserAttr mail REMOTE_USER_MAIL
    62.     LookupUserGECOS REMOTE_USER_DISPLAY_NAME
    64.     # Other options that might be useful
    66.     # While REMOTE_USER is used as the sub field and serves as the immutable ID,
    67.     # REMOTE_USER_PREFERRED_USERNAME could be used to have a different username
    68.     # LookupUserAttr <attr_name> REMOTE_USER_PREFERRED_USERNAME
    70.     # Group support may be added in a future release
    71.     # LookupUserGroupsIter REMOTE_USER_GROUP
    72.   </Location>
    74.   # Deny everything else
    75.   <Location ~ "^((?!\/check_user\.php).)*$">
    76.       Deny from all
    77.   </Location>
    78. </VirtualHost>

  4. Create the check_user.php script in the /var/www/html directory. Include the following code:

    1. <?php
    2. // Get the user based on the Apache var, this should always be
    3. // set because we 'Require valid-user' in the configuration
    4. $user = apache_getenv('REMOTE_USER');
    6. // However, we assume it may not be set and
    7. // build an error response by default
    8. $data = array(
    9.     'error' => 'remote PAM authentication failed'
    10. );
    12. // Build a success response if we have a user
    13. if (!empty($user)) {
    14.     $data = array(
    15.         'sub' => $user
    16.     );
    17.     // Map of optional environment variables to optional JSON fields
    18.     $env_map = array(
    19.         'REMOTE_USER_MAIL' => 'email',
    20.         'REMOTE_USER_DISPLAY_NAME' => 'name',
    21.         'REMOTE_USER_PREFERRED_USERNAME' => 'preferred_username'
    22.     );
    24.     // Add all non-empty environment variables to JSON data
    25.     foreach ($env_map as $env_name => $json_name) {
    26.         $env_data = apache_getenv($env_name);
    27.         if (!empty($env_data)) {
    28.             $data[$json_name] = $env_data;
    29.         }
    30.     }
    31. }
    33. // We always output JSON from this script
    34. header('Content-Type: application/json', true);
    36. // Write the response as JSON
    37. echo json_encode($data);
    38. ?>

  5. Enable Apache to load the module. Modify the /etc/httpd/conf.modules.d/55-lookup_identity.conf file and uncomment the following line:

    1. LoadModule lookup_identity_module modules/mod_lookup_identity.so

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

    1. # setsebool -P httpd_dbus_sssd on

  7. Set a boolean to tell SELinux that it is acceptable for Apache to contact the PAM subsystem:

    1. # setsebool -P allow_httpd_mod_auth_pam on

  8. Start Apache:

    1. # 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:

    1.   identityProviders:
    2.   - name: sssd
    3.     challenge: true
    4.     login: true
    5.     mappingMethod: claim
    6.     provider:
    7.       apiVersion: v1
    8.       kind: BasicAuthPasswordIdentityProvider
    9.       url: https://remote-basic.example.com/check_user.php
    10.       ca: /etc/origin/master/ca.crt
    11.       certFile: /etc/origin/master/openshift-master.crt
    12.       keyFile: /etc/origin/master/openshift-master.key

  3. Restart OKD with the updated configuration:

    1. # /usr/local/bin/master-restart api api
    3. # /usr/local/bin/master-restart controllers controllers

  4. Test a login by using the oc CLI:

    1. $ oc login https://openshift.example.com:8443

    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:

    1. $ oc get identity -o yaml