# openshift start \ --public-master=https://openshift.example.com:8443 \ --write-config=/etc/origin/
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. |
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.
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 |
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/
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:
|
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
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