Configure AD Bridge and Apache for SSO
This topic describes how to configure AD Bridge Enterprise and the Apache HTTP Server to provide single sign-on authentication through Active Directory with Kerberos 5. 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 the Simple and Protected GSS-API Negotiation Mechanism, or SPNEGO, to negotiate authentication with Kerberos. SPNEGO is an Internet standard documented in RFC 2478 and is commonly referred to as the negotiate authentication protocol. The AD Bridge Enterprise mod_auth_kerb module lets an Apache web server running on a Linux or Unix system authenticate and authorize users based on their Active Directory domain credentials.
For more information, please seethe following articles:
- RFC 2478
- Configure a Microsoft Browser for SSO.
- Troubleshoot Single Sign-on and Kerberos Authentication.
- AD Bridge Enterprise installed on the Linux computer running your Apache HTTP Server
- The Apache module ships with the AD Bridge Enterprise agent and is located in either /opt/pbis/lib64/ or /opt/pbis/lib/
- The Linux or Unix computer that is hosting the Apache web server is joined to Active Directory
- An Apache HTTP Server 2.0, 2.2, or 2.4 that supports dynamically loaded modules
To check whether your Apache web server supports dynamically loaded modules, execute the following command and verify that mod_so.c appears in the list of compiled modules: /usr/sbin/httpd -l or /usr/sbin/apache2 -1.
Compiled in modules: core.c prefork.c http_core.c mod_so.c
For Apache installations that are compiled from the source code, make sure that --enable-module=so is specified when ./configure is executed: ./configure --enable-module=so.
Configure Apache HTTP Server for SSO on RHEL
The following instructions show how to configure AD Bridge Enterprise and Apache for SSO on a Red Hat Enterprise Linux computer. The steps vary by operating system and by Apache version. Ubuntu, in particular, uses apache2 or httpd for commands, the name of the daemon, the configuration directory, the name of the configuration file, etc.
Configuring web servers is complex. Implement and test your configuration in a test environment first. Before you change your web server's configuration:
- Determine whether your Apache server is 2.0, 2.2 or 2.4 by running one of the following commands:
- /usr/sbin httpd -v
- /usr/sbin/apache2 -1
Server version: Apache/2.4.6 (Red Hat Enterprise Linux) Server built: Aug 3 2016 08:33:27
- Edit the Apache configuration file to add a directive to load the AD Bridge Enterprise auth_kerb_module for your version of Apache. Use one of the following:
Since this Red Hat computer is running Apache 2.4.6, the 2.4 version of the module is added, as demonstrated in the following example output:
LoadModule auth_kerb_module /opt/pbis/lib64/apache2.4/mod_auth_kerb.so
- In the configuration file, configure authentication for a directory. Example:
<Directory "/var/www/html/secure"> Options Indexes MultiViews FollowSymLinks Order deny,allow Deny from all Allow from 192.0.0.0/8 AuthType Kerberos AuthName "Kerberos Login" KrbAuthRealms EXAMPLE.COM krb5Keytab /etc/httpd/httpd.keytab AllowOverride None Require valid-user </Directory>
- Restart the web server, using the appropriate command for your Apache version:
systemctl restart httpd.service
systemctl restart apache2.service
You can require that a user be a member of a security group to access the Apache web server by replacing Require valid-user with Require unix-group name-of-your-group, as shown in the example below. To control group access by requiring group membership, however, you must first install and load mod_authz_unixgroup. For instructions on how to set up mod_authz_unixgroup, see https://code.google.com/archive/p/mod-auth-external/wikis/ModAuthzUnixGroup.wiki.
<Directory "/var/www/html/secure"> Options Indexes MultiViews FollowSymLinks Order deny,allow Deny from all Allow from 192.0.0.0/8 AuthType Kerberos AuthName "Kerberos Login" KrbAuthRealms EXAMPLE.COM Krb5Keytab /etc/httpd/httpd.keytab AllowOverride None Require unix-group example\linuxusers </Directory>
Configure your web server for Secure Socket Layer (SSL).
For instructions on configuring your web server for SSL, please see the Apache HTTP Server documentation.
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. For more information, please see http://modauthkerb.sourceforge.net/configure.html.
In Active Directory, create a user account for the Apache web server in the same OU (or Cell, with AD Bridge Enterprise) to which the Linux computer hosting the web server is joined. Set the password of the user account to never expire. In the examples that follow, the user account for the Apache web server is named httpUser.
On the domain controller, create an RC4-HMAC keytab for the Apache web server using Microsoft's ktpass utility. The keytab that you must create can vary by Windows version.
For information on ktpass, please see Ktpass Syntax.
C:\>ktpass /out keytabfile /princ HTTP/rhel7.example.com@EXAMPLE.COM /pass password /mapuser example\httpUser /ptype KRB5_NT_PRINCIPAL Targeting domain controller: dc1.example.com Using legacy password setting method Successfully mapped HTTP/rhel7.example.com to httpUser. Key created. Output keytab to keytabfile: Keytab version: 0x502 keysize 80 HTTP/rhel7.example.com@EXAMPLE.COM ptype 0 (KRB5_NT_UNKNOWN) vno 3 etype 0x17 (RC4- HMAC) keylength 16 (0x2998807dc299940e2c6c81a08315c596)
- Use secure FTP or another method to transfer the keytab file to the Linux computer that hosts your Apache web server and copy the file to the location specified in your <Directory> configuration in httpd.conf. For example, using the configuration shown in Step 3 above, copy the keytab file to /etc/apache2/http.ktb.
- Set the permissions of the keytab file to be readable by the ID under which the Apache web server runs and no one else.
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.