Configuring LDAP failover | Installation and Configuration

Prerequisites for configuring basic remote authentication
Generating and sharing certificates with the remote basic authentication server
Configuring SSSD for LDAP failover
Configuring Apache to use SSSD
Configuring OKD to use SSSD as the basic remote authentication server

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.
- openshift.example.com: 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.

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=https://openshift.example.com:8443 \
    --write-config=/etc/origin/
```
The output inclues the /etc/origin/master/ca.crt and /etc/origin/master/ca.key signing certificates.

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/remote-basic.example.com.crt' \
    --key='/etc/origin/remote-basic/remote-basic.example.com.key' \
    --hostnames=remote-basic.example.com \ (1)
    --signer-cert='/etc/origin/master/ca.crt' \
    --signer-key='/etc/origin/master/ca.key' \
    --signer-serial='/etc/origin/master/ca.serial.txt'

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.

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

# scp /etc/origin/master/ca.crt \
      root@remote-basic.example.com:/etc/pki/CA/certs/

# scp /etc/origin/remote-basic/remote-basic.example.com.crt \
      root@remote-basic.example.com:/etc/pki/tls/certs/

# scp /etc/origin/remote-basic/remote-basic.example.com.key \
      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:

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 \
                 mod_php

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 ldap.example.com
```
For more advanced cases, see the System-Level Authentication Guide
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.
Modify the [domain/DOMAINNAME] section of the /etc/sssd/sssd.conf file and add this attribute:
```
[domain/example.com]
...
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.
Confirm that the domain parameter in the /etc/sssd/sssd.conf file contains only the domain name listed in the [domain/DOMAINNAME] section.
```
domains = example.com
```
Grant Apache permission to retrieve the email attribute. Add the following lines to the [ifp] section of the /etc/sssd/sssd.conf file:
```
[ifp]
user_attributes = +mail
allowed_uids = apache, root
```
To ensure that all of the changes are applied properly, restart SSSD:
```
$ systemctl restart sssd.service
```

Test that the user information can be retrieved properly:

$ getent passwd <username>
username:*:12345:12345:Example User:/home/username:/usr/bin/bash

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 "username@example.com"
            ]
      )
   ]

1	Provide a user name in your LDAP solution.
2	Specify the attribute that you configured.

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:

If you use IPA joined systems, configure host-based access control.
If you use Active Directory joined systems, use a group policy object.
For other cases, see the SSSD configuration documentation.

Configuring Apache to use SSSD

Create a /etc/pam.d/openshift file that contains the following contents:
```
auth required pam_sss.so
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.
Edit the /etc/httpd/conf.modules.d/55-authnz_pam.conf file and uncomment the following line:
```
LoadModule authnz_pam_module modules/mod_authnz_pam.so
```

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/mod_request.so
LoadModule php7_module modules/libphp7.so

# 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>

<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/remote-basic.example.com.crt
  ServerName remote-basic.example.com

  DocumentRoot /var/www/html

  # Secure all connections with TLS
  SSLEngine on
  SSLCertificateFile /etc/pki/tls/certs/remote-basic.example.com.crt
  SSLCertificateKeyFile /etc/pki/tls/private/remote-basic.example.com.key
  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
    SSLRequireSSL
    # 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
    <RequireAll>
      Require valid-user
      Require expr %{SSL_CLIENT_S_DN_CN} == 'system:openshift-master'
    </RequireAll>
    # 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
    LookupUserGECOS REMOTE_USER_DISPLAY_NAME

    # 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
  </Location>

  # Deny everything else
  <Location ~ "^((?!\/check_user\.php).)*$">
      Deny from all
  </Location>
</VirtualHost>

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

<?php
// 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);
?>

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/mod_lookup_identity.so
```
Set an SELinux boolean so that SElinux allows Apache to connect to SSSD over D-BUS:
```
# setsebool -P httpd_dbus_sssd on
```
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
```
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.

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

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

  identityProviders:
  - name: sssd
    challenge: true
    login: true
    mappingMethod: claim
    provider:
      apiVersion: v1
      kind: BasicAuthPasswordIdentityProvider
      url: https://remote-basic.example.com/check_user.php
      ca: /etc/origin/master/ca.crt
      certFile: /etc/origin/master/openshift-master.crt
      keyFile: /etc/origin/master/openshift-master.key

Restart OKD with the updated configuration:

# systemctl restart atomic-openshift-master-api

# systemctl restart atomic-openshift-master-controllers

Test a login by using the oc CLI:
```
$ oc login https://openshift.example.com:8443
```
You can log in only with valid LDAP credentials.
List the identities and confirm that an email address is displayed for each user name. Run the following command:
```
$ oc get identity -o yaml
```