Chapter 13. Configuring LDAP failover

To ensure that communication between the remote basic authentication server and OpenShift Container Platform 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'

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/

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

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

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"
            ]
      )
   ]

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:

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

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 OpenShift Container Platform with the updated configuration:

# /usr/local/bin/master-restart api api

# /usr/local/bin/master-restart controllers 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