SupportConsoleDevelopersStart a trialContact

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, 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.

  2. Prepare the VMs:

    • proxy.example.com: 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.
    • openshift.example.com: A VM to use to run OpenShift Enterprise.
Note

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

    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/proxy.example.com.crt' \
    --key='/etc/origin/proxy/proxy.example.com.key' \
    --hostnames=proxy.example.com \
    --signer-cert=/etc/origin/master/ca.crt \
    --signer-key='/etc/origin/master/ca.key' \
    --signer-serial='/etc/origin/master/ca.serial.txt'
    Important

    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
  --serial='/etc/origin/proxy/proxyca.serial.txt'
    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' \
    --user='system:proxy'

    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.

12.2.4.1. Step 1: Copy Certificates

From openshift.example.com, securely copy the necessary certificates to the proxy machine: 

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

# scp /etc/origin/proxy/proxy.example.com.crt \
      /etc/origin/proxy/authproxy.pem \
      root@proxy.example.com:/etc/pki/tls/certs/

# scp /etc/origin/proxy/proxy.example.com.key \
      root@proxy.example.com:/etc/pki/tls/private/

12.2.4.2. 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 \
                 mod_authnz_pam

    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/mod_authnz_pam.so

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

    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.
Note

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 pam_sss.so.

12.2.4.3. 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 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.

  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.

    Note

    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/mod_request.so
LoadModule lookup_identity_module modules/mod_lookup_identity.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/proxy.example.com.crt
  ServerName proxy.example.com

  DocumentRoot /var/www/html
  SSLEngine on
  SSLCertificateFile /etc/pki/tls/certs/proxy.example.com.crt
  SSLCertificateKeyFile /etc/pki/tls/private/proxy.example.com.key
  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.
    ProxyPass https://openshift.example.com:8443/oauth/authorize
    AuthType Basic
    AuthBasicProvider PAM
    AuthPAMService openshift
    Require valid-user
  </Location>

  <ProxyMatch /oauth/authorize>
    AuthName openshift
    RequestHeader set X-Remote-User %{REMOTE_USER}s env=REMOTE_USER
  </ProxyMatch>
</VirtualHost>

RequestHeader unset X-Remote-User
    Note

    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: 

      identityProviders:
  - name: any_provider_name
    challenge: true
    login: false
    mappingMethod: claim
    provider:
      apiVersion: v1
      kind: RequestHeaderIdentityProvider
      challengeURL: "https://proxy.example.com/challenging-proxy/oauth/authorize?${query}"
      clientCA: /etc/origin/master/proxy/proxyca.crt
      headers:
      - X-Remote-User
    Note

    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=https://openshift.example.com:8443 \
    --master-config=/etc/origin/master/master-config.yaml \
    --node-config=/etc/origin/node-node1.example.com/node-config.yaml

  4. Test logins: 

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

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

# curl -o /var/www/html/login.html \
    https://raw.githubusercontent.com/openshift/openshift-extras/master/misc/form_auth/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.
  ProxyPass https://openshift.example.com:8443/oauth/authorize

  InterceptFormPAMService openshift
  InterceptFormLogin httpd_username
  InterceptFormPassword httpd_password

  RewriteCond %{REQUEST_METHOD} GET
  RewriteRule ^.*$ /login.html [L]
</Location>

    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: 

    identityProviders:
- name: any_provider_name
  challenge: true
  login: true 1
  mappingMethod: claim
  provider:
    apiVersion: v1
    kind: RequestHeaderIdentityProvider
    challengeURL: "https://proxy.example.com/challenging-proxy/oauth/authorize?${query}"
    loginURL: "https://proxy.example.com/login-proxy/oauth/authorize?${query}" 2
    clientCA: /etc/origin/master/proxy/proxyca.crt
    headers:
    - X-Remote-User
    1
    Note that login is set to true, not false.
    2
    Newly added line.

  2. Restart OpenShift Enterprise with the updated configuration.

    Note

    You should be able to browse to https://openshift.example.com:8443 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: 

    [domain/example.com]
...
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: 

    [ifp]
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/mod_lookup_identity.so

  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
</ProxyMatch>
    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: 

    identityProviders:
 - name: sssd
 challenge: true
 login: true
 mappingMethod: claim
 provider:
   apiVersion: v1
   kind: RequestHeaderIdentityProvider
   challengeURL: "https://proxy.example.com/challenging-proxy/oauth/authorize?${query}"
   loginURL: "https://proxy.example.com/login-proxy/oauth/authorize?${query}"
   clientCA: /home/example/workspace/openshift/configs/openshift.example.com/proxy/proxyca.crt
   headers:
   - 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.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.