Configure AD Bridge and Apache for SSO

This topic describes how to configure AD Bridge and the Apache HTTP Server to provide single sign-on authentication through Active Directory with Kerberos. The instructions assume that you know how to administer Active Directory, the Apache HTTP Server, and computers running Linux.

Single sign-on for the Apache HTTP server uses SPNEGO to negotiate authentication with Kerberos. The mod_auth_gssapi module lets an Apache web server running on Linux or Unix authenticate and authorize users based on their Active Directory domain credentials. This replaces the mod_auth_kerb module that previously shipped bundled with the AD Bridge agent.

Prerequisites

AD Bridge installed on the Linux computer and joined to Active Directory.
Install Apache Server and mod_auth_gssapi package from the Linux system.

Install AD Bridge and join system to Active Directory

Refer to Install the AD Bridge agent and join to the domain. Run update-dns to allow for name resolution.

/opt/pbis/bin/domainjoin-cli join --ou web/apache example.com
/opt/pbis/bin/update-dns

Install Apache and mod_auth_gssapi from the system repositories

dnf install httpd mod_auth_gssapi
- httpd -M | grep auth_gssapi
apt install apache2 libapache2-mod-auth-gssapi; a2enmod auth_gssapi
- apache2ctl -M | grep gssapi

Configure Apache HTTP server for SSO

The following instructions show how to configure AD Bridge and Apache for SSO. The steps vary by operating system and by Apache version. Ubuntu, in particular, uses apache2 or httpd for RHEL, the name of the daemon, the configuration directory, the name of the configuration file, etc.

⚠️
Important
Configuring web servers is complex. Implement and test your configuration in a test environment first. Before you change your web server's configuration:

Read the Apache HTTP Server documentation at http://httpd.apache.org/docs/

Back up a file before applying any changes.

Create an AD service account and generate the keytab using the AD Bridge adtool binary on the Linux host

Use the AD Bridge adtool binary to generate a keytab to be used with Apache.

Important

First login as an AD user with rights to create a user on the apache server to run adtool.
SPN needs to match the systems and url the requests will be coming from.
If the password or keytab creation fails the account will still be created.
Apache expects a CAPITALIZED Service class in the SPN.

/opt/pbis/bin/adtool -a new-user \
  --dn OU=apache,OU=web,DC=example,DC=com \
  --cn=apache-account \
  --logon-name=apache-account \
  --password=RANDOMPASSWORD \
  --keytab-file=./http.keytab \
  --spn=HTTP/apache-rhel.example.com \
  --no-must-change-password \
  --no-password-expires \
  --account-enabled

Confirm the keytab contains the correct SPN

/opt/pbis/bin/klist -tk ./http.keytab

⚠️
Important
The Kerberos keytab file is necessary to authenticate incoming requests. It contains an encrypted, local copy of the host’s key and, if compromised, might allow unrestricted access to the host computer. It is therefore crucial to protect it with file-access permissions.

Configure the AD service account to support AES encryption

Without this, the KDC may issue RC4-encrypted tickets that the keytab cannot satisfy.

In Active Directory Users and Computers, open the apache-account properties > Account tab > Account options and enable:

This account supports Kerberos AES 128 bit encryption
This account supports Kerberos AES 256 bit encryption

Copy the keytab to the Apache configuration directory and set permissions

Move and set the permissions of the keytab file to be readable by the ID under which the Apache web server runs and no one else.

For Apache2

cp ./http.keytab /etc/apache2/http.keytab
chown www-data:www-data /etc/apache2/http.keytab
chmod 640 /etc/apache2/http.keytab

For httpd

cp ./http.keytab /etc/httpd/conf/http.keytab
chown apache:apache /etc/httpd/conf/http.keytab
chmod 640 /etc/httpd/conf/http.keytab

Configure authentication using mod_auth_gssapi directives

Configure authentication for Kerberos using your keytab.

<Directory "/var/www/html/secure">
  Options Indexes MultiViews FollowSymLinks
  Order deny,allow
  Deny from all
  Allow from 192.0.0.0/8
  AuthType GSSAPI
  AuthName "Kerberos Login"
  GssapiCredStore keytab:/etc/httpd/conf/http.keytab
  AllowOverride None
  Require valid-user
</Directory>

Restart the web server

Using the appropriate command for your Apache version

Apache2

apache2ctl configtest
systemctl restart apache2
systemctl status apache2

httpd

httpd -t
systemctl enable --now httpd
systemctl status httpd

Access the web server

Accessing the web server by Full Qualified Domain Name(FQDN) rather then IP to allow for Kerberos negotiations. IP address will still work but it will fallback to basic authentication.

⚠️
Important
If SSO fails and you have not turned on SSL, your server will prompt you for an ID and password, which will be sent in clear text. SSL encrypts all data that passes between the client browser and the web server. SSL can also perform Basic Authentication securely, providing a fallback mechanism if Kerberos authentication fails. Using SSL is especially important if the protected website also needs to be accessible from outside the corporate network.

Troubleshoot single sign-on and Kerberos authentication

The following tools and procedures can help diagnose and resolve problems with Kerberos authentication when using the Apache HTTP Server for single sign-on (SSO).

Apache log file

The location of the Apache error logs is specified in the Apache configuration file under the ErrorLog directive. The default value is, depending on your Apache version, one of the following:

/var/log/httpd/
/var/log/apache2/

Klist utility

You can use the klist utility in /opt/pbis/bin/klist to check the Kerberos keytab file on a Linux or Unix computer. The command shows all the service principal tickets contained in the keytab file so you can verify that the correct service principal names appear.

Confirm that HTTP/[email protected] and HTTP/[email protected] appear in the list. It is normal to see multiple entries for the same name.

✅

Example

$ /opt/pbis/bin/klist -k /etc/httpd/httpd.ktb
Keytab name: WRFILE:/etc/httpd/httpd.ktb
KVNO Principal
---- --------------------------------------------------------------------------
5 HTTP/[email protected]

If your service principal names are incorrect, generate a new Kerberos keytab file.

ℹ️
Because you cannot store credentials for more than one principal in a Kerberos credentials cache at a time, you must maintain two or more credential caches by using the KRB5CCNAME environment variable and then switch to the cache that you want to use. To use an alternate Kerberos cache with AD Bridge, for example, you could execute the following sequence of commands as root:

[root@oracle1 ~]# KRB5CCNAME=/var/lib/pbis/krb5cc_lsass
[root@oracle1 ~]# export KRB5CCNAME
[root@oracle1 ~]# klist
Ticket cache: FILE:/var/lib/pbis/krb5cc_lsass

Confirm user received an HTTP ticket

Run Klist on Linux and UNIX systems running AD Bridge or on Windows from the command prompt.

Linux klist:

apacheuser@rhel:/home/apacheuser$ /opt/pbis/bin/klist
Ticket cache: FILE:/tmp/krb5cc_2066220575
Default principal: [email protected]
   Valid starting     Expires            Service principal
   04/05/17 11:46:28  04/05/17 21:46:28
      krbtgt/[email protected]
      renew until 04/05/17 23:46:28
   04/05/17 11:46:28  04/05/17 21:46:28
      host/[email protected]
      renew until 04/05/17 23:46:28
   04/05/17 11:46:28  04/05/17 21:46:28  ldap/[email protected]
      renew until 04/05/17 23:46:28
   04/05/17 11:46:28  04/05/17 21:46:28  HTTP/[email protected]
      renew until 04/05/17 23:46:28

Windows klist:

C:\>klist
Current LogonId is 0:0x816aded2
Cached Tickets: (5)
#0> Client: apacheuser @ EXAMPLE.COM
   Server: krbtgt/EXAMPLE.COM @ EXAMPLE.COM
   KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96
   Ticket Flags 0x60a00000 -> forwardable forwarded renewable pre_authent
   Start Time: 4/5/2017 9:09:52 (local)
   End Time:   4/5/2017 19:09:52 (local)
   Renew Time: 4/12/2017 9:09:52 (local)
   Session Key Type: AES-256-CTS-HMAC-SHA1-96
   Cache Flags: 0x2 -> DELEGATION
   Kdc Called: dc.example.com
#1> Client: apacheuser @ EXAMPLE.COM
   Server: krbtgt/EXAMPLE.COM @ EXAMPLE.COM
   KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96
   Ticket Flags 0x40e00000 -> forwardable renewable initial pre_authent
   Start Time: 4/5/2017 9:09:52 (local)
   End Time:   4/5/2017 19:09:52 (local)
   Renew Time: 4/12/2017 9:09:52 (local)
   Session Key Type: AES-256-CTS-HMAC-SHA1-96
   Cache Flags: 0x1 -> PRIMARY
   Kdc Called: dc.example.com
#2> Client: apacheuser @ EXAMPLE.COM
   Server: HTTP/rhel.example.com @ EXAMPLE.COM
   KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
   Ticket Flags 0x40a00000 -> forwardable renewable pre_authent
   Start Time: 4/5/2017 9:15:36 (local)
   End Time:   4/5/2017 19:09:52 (local)
   Renew Time: 4/12/2017 9:09:52 (local)
   Session Key Type: RSADSI RC4-HMAC(NT)
   Cache Flags: 0
   Kdc Called: dc.example.com

Resolve common problems

Authentication problems can be difficult to diagnose. First, check all the configuration parameters, including the validity of the keytab file. Second, review the common problems in the following table.

Problem	Solution
System clock out of sync	Clocks must be within 5 minutes. Synchronize the DC, web server, and client.
User not on the require list	Check error_log for authorization failures. Add the user or group to the Require directive.
IE/Edge not treating URL as intranet zone	Access by short hostname or add the URL to Local Intranet / Trusted Sites.
Duplicate SPN on multiple AD objects	Run setspn -Q HTTP/your-server-fqdn on the DC. If more than one object is returned, remove the duplicate: setspn -D HTTP/your-server-fqdn old-account. Commonly occurs after recreating the service account without cleaning up the old one.
KVNO mismatch between keytab and KDC	Run /opt/pbis/bin/kvno HTTP/your-fqdn@EXAMPLE and compare to klist -kt. If they differ, regenerate the keytab with adtool and purge client tickets with klist purge (Windows) or kdestroy (Linux). This could also be a signal that there is a duplicate SPN.
GSS ERROR: enctype rc4-hmac not found in keytab	Enable AES encryption on the service account in AD Users and Computers > Account tab > enable This account supports Kerberos AES 128/256 bit encryption. Purge client ticket cache and retry.
SELinux blocking keytab read	Run ausearch -m avc -ts recent \| grep keytab to confirm. Fix: semanage fcontext -a -t httpd_config_t /etc/httpd/conf/http.keytab; restorecon -v /etc/httpd/conf/http.keytab; ls -lZ /etc/httpd/conf/http.keytab
SELinux blocking Apache connection to AD Bridge LSASS socket	Occurs when GssapiLocalName On is set. Remove that directive to avoid the LSASS socket dependency, or create a custom SELinux policy to allow httpd_t to connect to the socket.