<commit_before>[[setting-up-for-ldap-failover]]
= Setting up SSSD for LDAP Failover
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
{product-title} provides an
xref:../configuring_authentication.adoc#LDAPPasswordIdentityProvider[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 {product-title}.
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
{product-title} 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.

[[sssd-prerequisites-for-authenticating-proxy-setup]]
== Prerequisites for Authenticating Proxy Setup

. Before starting setup, you need to know the following information about your
LDAP server.
+
* Whether the directory server is powered by
http://www.freeipa.org/page/Main_Page[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 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 {product-title}.

[NOTE]
====
These VMs can be configured to run on the same system, but for the examples used
in this topic they are kept separate.
====

[[sssd-phase-1-certificate-generation]]
== Phase 1: Certificate Generation

. To ensure that communication between the authenticating proxy and
{product-title} is trustworthy, create a set of Transport Layer Security (TLS)
certificates to use during the other phases of this setup. In the
{product-title} 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.
====

. Generate the API client certificate that the authenticating proxy will use
to prove its identity to {product-title}. This is necessary and prevents
malicious users from impersonating the proxy and sending fake identities.

. Create a new CA to sign this client certificate:
+
====
----
# 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,172.16.17.32 \
    --signer-cert=/etc/origin/master/ca.crt \
    --signer-key='/etc/origin/master/ca.key' \
    --signer-serial='/etc/origin/master/ca.serial.txt'
----
====
+
Make `*UNIQUESTRING*`` something unique:
+
====
----
# oadm ca create-signer-cert \
  --cert='/etc/origin/proxy/proxyca.crt' \
  --key='/etc/origin/proxy/proxyca.key' \
  --name='openshift-proxy-signer@UNIQUESTRING' \
  --serial='/etc/origin/proxy/proxyca.serial.txt'
----
====

[[sssd-phase-2-authenticating-proxy-setup]]
== Phase 2: Authenticating Proxy Setup

This section guides you through the steps to authenticate the proxy setup.

[[phase-2-step-1-copy-certificates]]
=== Step 1: Copy Certificates

From *_openshift.example.com_*, securely copy the necessary certificates to the
proxy machine:

====
----
# scp /etc/origin/proxy/master/ca.crt \
      root@proxy.<EMAIL>:/etc/pki/CA/certs/

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

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

[[phase-2-step-2-sssd-configuration]]
=== Step 2: SSSD Configuration
. 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.

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

. 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
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System-Level_Authentication_Guide/authconfig-ldap.html[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.<commit_msg>edits as per customer feedback<commit_after>[[setting-up-for-ldap-failover]]
= Setting up SSSD for LDAP Failover
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
{product-title} provides an
xref:../configuring_authentication.adoc#LDAPPasswordIdentityProvider[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 {product-title}.
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
{product-title} 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.

[[sssd-prerequisites-for-authenticating-proxy-setup]]
== Prerequisites for Authenticating Proxy Setup

. Before starting setup, you need to know the following information about your
LDAP server.
+
* Whether the directory server is powered by
http://www.freeipa.org/page/Main_Page[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 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 {product-title}.

[NOTE]
====
These VMs can be configured to run on the same system, but for the examples used
in this topic they are kept separate.
====

[[sssd-phase-1-certificate-generation]]
== Phase 1: Certificate Generation

. To ensure that communication between the authenticating proxy and
{product-title} is trustworthy, create a set of Transport Layer Security (TLS)
certificates to use during the other phases of this setup. In the
{product-title} 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.
====

. Generate the API client certificate that the authenticating proxy will use
to prove its identity to {product-title}:
+
====
----
# 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'
----
====

. 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
----
====
+
This prevents malicious users from impersonating the proxy and sending fake
identities.

. Create a new CA to sign this client certificate:
+
====
----
# 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,172.16.17.32 \
    --signer-cert=/etc/origin/master/ca.crt \
    --signer-key='/etc/origin/master/ca.key' \
    --signer-serial='/etc/origin/master/ca.serial.txt'
----
====
+
Make `*UNIQUESTRING*`` something unique:
+
====
----
# oadm ca create-signer-cert \
  --cert='/etc/origin/proxy/proxyca.crt' \
  --key='/etc/origin/proxy/proxyca.key' \
  --name='openshift-proxy-signer@UNIQUESTRING' \
  --serial='/etc/origin/proxy/proxyca.serial.txt'
----
====

[[sssd-phase-2-authenticating-proxy-setup]]
== Phase 2: Authenticating Proxy Setup

This section guides you through the steps to authenticate the proxy setup.

[[phase-2-step-1-copy-certificates]]
=== 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.<EMAIL>.com:/etc/pki/CA/certs/

# scp /etc/origin/proxy/proxy.example.com.crt \
      /etc/origin/proxy/authproxy.pem \
      <EMAIL>:/etc/pki/tls/certs/

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

[[phase-2-step-2-sssd-configuration]]
=== Step 2: SSSD Configuration
. 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.

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

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

. 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
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System-Level_Authentication_Guide/authconfig-ldap.html[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.
{'fraction_non_alphanumeric': 0.11804955344281187, 'fraction_numerical': 0.00648228176318064, 'mean_word_length': 3.518385942076147, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 8, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5629996', 'n_tokens_mistral': 4329, 'n_tokens_neox': 4177, 'n_words': 1431}