DocumentationRelease Notes
Documentation

Apache HTTP Server

Suggest Edits

This topic describes how to configure AD Bridge 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 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.

ℹ️

Note

For more information, see the following articles:

Prerequisites

  • AD Bridge installed on the Linux computer running your Apache HTTP Server
  • The Apache module ships with the AD Bridge 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 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.

⚠️

Important

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

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

✅

Example

Server version: Apache/2.4.6 (Red Hat Enterprise Linux)
Server built:   Aug  3 2016 08:33:27
  1. Edit the Apache configuration file to add a directive to load the AD Bridge auth_kerb_module for your version of Apache. Use one of the following:
/etc/httpd/conf/httpd.conf

/etc/apache2/apache2.conf

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.

✅

Example

LoadModule auth_kerb_module /opt/pbis/lib64/apache2.4/mod_auth_kerb.so
  1. 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>
  1. Restart the web server, using the appropriate command for your Apache version:
systemctl restart httpd.service

ℹ️

Note

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://github.com/DRN88/mod_authz_unixgroup.

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

ℹ️

Note

For instructions on configuring your web server for SSL, see the Apache HTTP Server documentation.

⚠️

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. For more information, 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) 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.

ℹ️

Note

For information on ktpass, see Ktpass Syntax.

✅

Example

C:\>ktpass /out keytabfile /princ HTTP/[email protected] /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/[email protected] ptype 0 (KRB5_NT_UNKNOWN) vno 3 etype 0x17 (RC4-
HMAC) keylength 16 (0x2998807dc299940e2c6c81a08315c596)
  1. 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 configuration in httpd.conf. For example, using the configuration shown in Step 3 above, copy the keytab file to /etc/apache2/http.ktb.
  2. Set the permissions of the keytab file to be readable by the ID under which the Apache web server runs and no one else.

⚠️

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 a Microsoft browser for SSO

You can configure Microsoft Internet Explorer or Microsoft Edge to use SPNEGO and Kerberos. The settings might vary depending on the browser. See the browser's documentation for more information.

  1. Start Internet Explorer.
  2. On the Tools menu, click Internet Options.
  3. Click the Advanced tab and check the Enable Integrated Windows Authentication box.
  4. Click the Security tab.
  5. Select a zone, for example, Local intranet, and then click Custom level.
  6. In the Settings list, under User Authentication, click Automatic logon with current user name and password for a trusted site, or Automatic logon only in Intranet zone for a site you added to IE's list of Intranet sites. For more information, see the browser's documentation.
  7. Return to the Security tab for Internet Options and set your web server as a trusted site.
  8. Restart the browser.

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.

ℹ️

Note

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

Klist can be used on the current user to verify that they receive a service ticket for HTTP.

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

Linux klist:

apacheuser@rhel7:/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: dc1.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: dc1.example.com
#2> Client: apacheuser @ EXAMPLE.COM
   Server: HTTP/rhel7.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: dc1.example.com
#3> Client: apacheuser @ EXAMPLE.COM
   Server: ldap/DC13.example.com/example.com @ EXAMPLE.COM
   KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96
   Ticket Flags 0x40a40000 -> forwardable renewable pre_authent ok_as_delegate
   Start Time: 4/5/2017 9:09:53 (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: 0
   Kdc Called: dc1.example.com
#4> Client: apacheuser @ EXAMPLE.COM
   Server: cifs/DC11 @ EXAMPLE.COM
   KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96
   Ticket Flags 0x40a40000 -> forwardable renewable pre_authent ok_as_delegate
   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: 0
   Kdc Called: dc1.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.

ProblemSolution
The system's clock is out of sync.The Kerberos standard requires that system clocks be no more than 5 minutes apart. Make sure that the system clocks on the Active Directory domain controller, the Linux or Unix web server, and the client are synchronized.
The user accessing the website is not on the require list.If the Kerberos ticket was obtained on the client or the user correctly entered his credentials during the Basic Authentication prompt, it might be because authentication worked but the authorization failed. If so, the Apache error_log will contain a line like this:
access to / failed, reason: user EXAMPLE\user not allowed access Add the user to the require user directive or add the user’s group to the require group directive.
The user accessing the website is logged on the wrong domain.If the client user is logged on a domain different from the domain of the web server, one of two things will happen:
  1. If the KrbMethodK5Passwd directive is set to on, or was not specified and thus defaults to on, the user will be prompted for credentials.
  2. If KrbMethodK5Passwd is set to off, authentication will fail and the Authorization Required page will be displayed.
Internet Explorer does not consider the URL to be part of the Local Intranet zone or the Trusted sites.This problem commonly occurs when the website is accessed by using a URL that includes the full domain name, such ashttps://myserver.example.com. Internet Explorer tries to obtain Kerberos tickets only for websites that are in the Local Intranet zone.
Try to access the website by using only the server name, for example https://myserver.
Or, you can add the URL to a list of Local Intranet sites or the trusted sites by changing your options in Internet Explorer.
The service principal name of the website is mapped to more than one object in the Active Directory.Although this problem is rare, it is difficult to diagnose because the error messages are vague. The problem can occur after the ktpass utility was used repeatedly to generate a Kerberos keytab file for the web server.
To check for this problem, log on your Active Directory domain controller and open the Event Viewer. Look for an event of type=Error, source=KDC, and event ID=11. The text of the event will be similar to the message below:
There are multiple accounts with name HTTP/myserver.example.com of type DS_SERVICE_PRINCIPAL_NAME.
To fix the problem, find the computer or user objects that were used to map the service principal name in Active Directory and then use the ADSI Edit to manually remove the HTTP/myserver.example.com string from the servicePrincipalName object property.
Below the table is a screen shot that provides an example of how to find an object named HTTP by using LDAP.

How to find an object named HTTP by using LDAP

Resolve Kerberos library mismatch

Because some operating systems, such as the 64-bit version of Red Hat Enterprise Linux 5, use an outdated version of /lib/libcom_err.so, the AD Bridge authentication agent cannot the locate the proper system library, leading to an error that looks like this:

httpd: Syntax error on line 202 of /etc/httpd/conf/httpd.conf:Cannot load /opt/pbis/apache/2.2/mod_auth_kerb.so into server:
/opt/pbis/lib/libcom_err.so.3: symbol krb5int_strlcpy, version
krb5support_0_MIT not defined in file libkrb5support.so.0 with link time reference

Solution: Force the httpd daemon to use the AD Bridge krb5 libraries by opening the startup script for the Apache HTTP Server: /etc/init.d/httpd Additionally, add the path to the AD Bridge Kerberos libraries on the line that starts Apache. The line that starts the daemon can vary by operating system. Example on a 64-bit system: LD_LIBRARY_PATH=/opt/pbis/lib64 LANG=$HTTPD_LANG daemon $httpd $OPTIONS

ℹ️

Note

This modification changes the version of the Kerberos libraries that are used by the Apache HTTP Server. The change might result in compatibility issues with other modules of Apache that use Kerberos.

Updated about 1 month ago

©2003-2025 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.