Authenticating with Kerberos

You can use Kerberos to authenticate Microsoft Windows™ accounts with Liferay DXP. This is done by using a combination of Liferay DXP’s LDAP support and a web server that supports the Kerberos protocol.

Note that this configuration is preferred above NTLM because security vulnerabilities persist.

Prerequisites

While it’s beyond the scope of this article to explain how to set up Kerberos and Active Directory on a Windows™ server, we can describe the minimum prerequisites for setting up Liferay authentication:

1. A Windows™ server with Active Directory and DNS set up so the AD server and Liferay DXP can resolve each other on the network. In other words, they must be able to ping each other by name.

2. An administrative user in AD Liferay DXP can use to bind to AD.

3. A Kerberos keytab file exported via the ktpass command containing the cryptographic information the Liferay DXP server must bind to AD.

4. A web server in front of Liferay DXP that supports Kerberos, such as Apache, NGNIX, or IIS. The web server must also support injecting a header to be used as a token in the Liferay DXP configuration (see below).

5. A Liferay DXP installation that can also resolve by name the other servers. It should never run on the same server as the Active Directory server.

When you have all of these prerequisites in place, you’re ready to configure Kerberos authentication.

How Kerberos Authentication Works

From the prerequisites, you may be able to guess that there are several moving parts to how SSO works with Kerberos.

First, a properly configured web browser sends a negotiate request using encrypted Windows user data. To configure this, the browser must recognize the site as a trusted site (explained below). The web server’s Kerberos module uses the keytab file to bind over the Kerberos protocol to AD and verify the user information. If this works, the AD server confirms the connection with a valid response.

The web server you choose must support both the Kerberos protocol and the injection of a custom header into the request that Liferay DXP can later read. When the web server forwards the request to Liferay DXP, it reads the header to obtain the user data and authenticate the user.

Next, learn how to get all of this working.

Configuring Kerberos Authentication

There are four components to configure:

1. A user keytab from Active Directory

2. A web server in front of your application server

3. Liferay DXP

4. Your Windows™ clients.

Step 1: Creating the User Keytab

1. Create a user so Liferay DXP can bind to Active Directory.

2. Generate a Kerberos keytab file using ktpass:

   ktpass -princ HTTP/[web server host name]@[domain] -mapuser [user name]@[domain] -crypto ALL -ptype KRB5_NT_PRINCIPAL -pass [password] -out c:\kerberos.keytab
   

   For example:

   ktpass -princ HTTP/[e-mail] -mapuser [e-mail] -crypto ALL -ptype KRB5_NT_PRINCIPAL -pass password-for-Marta -out c:\kerberos.keytab
   

3. Ensure that the AD domain controller and the web server can see each other on the network via DNS configuration or hosts file.

Step 2: Configuring Your Web Server

Kerberos authentication is configured at the web server level. Liferay DXP reads the authenticated user from request headers and does not manage Kerberos authentication directly.

1. Configure Kerberos on your web server. On Linux, install krb5 and configure it to match your Active Directory realm. For example,

   [libdefaults]
      default_realm = INTDOMAIN.LOCAL
   
   [domain_realm]
      mywebserver.intdomain.local = INTDOMAIN.LOCAL intdomain.local = INTDOMAIN.LOCAL .intdomain.local = INTDOMAIN.LOCAL
   
   [realms]
   INTDOMAIN.LOCAL = { admin_server = winserver.intdomain.local kdc = winserver.intdomain.local
   }
   

2. Copy the keytab file you generated on your AD server to your web server.

3. Configure your web server to authenticate users with Kerberos and forward the authenticated user in a request header.

   Note

   mod_auth_kerb is deprecated and not available in modern Linux distributions. Use mod_auth_gssapi or another supported Kerberos module for your web server.

   For example, using Apache HTTP Server with mod_auth_gssapi:

   LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so
   LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
   LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
   LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
   LoadModule proxy_ajp_module /usr/lib/apache2/modules/mod_proxy_ajp.so
   LoadModule auth_gssapi_module /usr/lib/apache2/modules/mod_auth_gssapi.so
   
   <VirtualHost *:10080>
     ProxyRequests Off
     ProxyPreserveHost On
     ProxyPass / ajp://localhost:8009/
     ProxyPassReverse / ajp://localhost:8009/
     ServerName mywebserver.intdomain.local
   
     <Location />
       AuthType GSSAPI
       AuthName "Kerberos Login"
       GssapiCredStore keytab:/etc/apache2/kerberos.keytab
       GssapiLocalName On
   
       Require valid-user
   
       RequestHeader unset X-User-Global-ID
       RewriteEngine On
       RewriteCond %{LA-U:REMOTE_USER} (.+)
       RewriteRule /.* - [E=RU:%1,L]
       RequestHeader set X-User-Global-ID %{RU}e
     </Location>
   </VirtualHost>
   
   Listen 10080
   

Ensure the header name matches the value configured for Token Based SSO in Liferay DXP.

Step 3: Connecting Liferay DXP to Active Directory over LDAP

1. Finally, configure Liferay DXP to access Active Directory via the LDAP protocol. Change authentication to be by Screen Name by selecting it in Configuration → Instance Settings → Authentication → General.

2. Connect Liferay DXP to AD over LDAP by navigating to Configuration → Instance Settings → Authentication → LDAP and adding an LDAP server. Provide the information appropriate to your installation:

   Configuration	Description
   Base Provider URL	Your AD server on the proper port.
   Base DN	Your domain configuration. The example above might be DC=INTDOMAIN.DC=LOCAL.
   Principal/Credentials	Supply the credentials for the user exported to the keytab file.
   Authentication Search Filter	Supply the appropriate search filter to return user objects. For example, (&(objectCategory=person)(sAMAccountName=*))
   UUID	Supply what uniquely identifies a user, such as sAMAccountName.
   Screen Name	Supply the field that should be mapped to Liferay DXP’s screen name field, such as sAMAccountName.
   Password	Supply the field that contains the user’s password, such as userPassword.

3. Test the connection, save, and enable the configuration.

4. Finally, configure the token for single sign-on at Configuration → System Settings → Security → SSO → Token Based SSO. Make sure the User Token Name matches exactly the token you configured in your web server. Click the Enabled and Import from LDAP boxes and click Save.

   

Excellent! You’ve configured your servers. All that’s left is to configure your clients.

Step 4: Configuring your Clients

You must do two things: make your computer log into the domain and configure your Liferay DXP server as a trusted Internet site.

1. Join your computer to your domain. In keeping with the example above, you’d make your computer a member of the INTDOMAIN.LOCAL domain.

2. Log in as a user in that domain.

3. Internet Explorer, Edge, and Chrome use the Windows™ settings for trusted sites. If you use these browsers, go to Internet Options → Security → Local Intranet Sites and add your Liferay DXP server’s URL. For example, add http://mywebserver.intdomain.local:10080.

4. Firefox can be configured by typing about:config in its address bar. Search for the below two preferences and add the Liferay DXP server’s URL as the value for both:

   • network.negotiate-auth.delegation-uris
   • network.negotiate-auth.trusted-uris

After configuring these things, test your configuration by accessing Liferay DXP through the web server’s URL. Since you are already logged into your client machine, you should be automatically logged into Liferay DXP without a user/password prompt.

Congratulations on configuring Kerberos with Liferay DXP!