Configuring SSO with Kerberos for admin accounts

Configure the Windows Kerberos Authentication so that administrators can single sign on (SSO) to the Admin Console using Kerberos authentication.

Before you begin

The task requires the following:

You are using the Kerberos Version 5 protocol
You have connected the eperi sEcure Platform to your Active Directory (see Connecting your Active Directory to eperi sEcure Platform)
You have mapped the necessary AD groups to the respective administrator roles in the eperi sEcure Platform (see Mapping an AD group to administrator roles or Importing all AD groups of an OU at once)
You have created a service account in your AD which is used by Kerberos to pre-authenticate against your AD. In the account options, you have set the following:
- This account supports Kerberos AES 128 bit encryption
- This account supports Kerberos AES 256 bit encryption
- Password never expires
In the service account as User Logon name you entered the Principal name of the user. For example: HTTP/mygateway.example.com
Please consider the following in a cluster setup:
- Take the necessary steps for multiple services to be connected with Kerberos.
- Perform the configuration described below on all eperi sEcure Platform instances of the cluster.
- Set up Session stickiness in your loadbalancer.

Procedure

Create a keytab file for the mapping of the principal user to the service account (using the ktpass command on Windows server), for example:
```
ktpass /princ HTTP/mygateway.example.com /mapuser sampleuser@YOURREALM.COM /crypto AES256-SHA1 /pass * -SetPass /ptype KRB5_NT_PRINCIPAL /out example.keytab
```
For details about the ktpass parameters, please refer to the Microsoft documentation.
Upload the keytab file to the eperi sEcure Platform server and put it in this directory: /opt/eperi/gateway/tomcat/webapps/ROOT/etc
Create a krb5.conf file according to the Kerberos standard, see the example below. (For more details, see for example the MIT Kerberos Documentation.)

In the krb5.conf file configure the path to your keytab file, for example:

[libdefaults]
    default_realm = YOURREALM.COM
    default_keytab_name=FILE:/path/to/your/keytab/file/example.keytab
    forwardable=true 
[realms]
    YOURREALM.COM = {
        kdc = yourDomainController.yourRealm.com         
        default_domain = yourRealm.com     
    } 
[domain_realm]     
    .yourRealm.com = YOURREALM.COM     
    yourRealm.com = YOURREALM.COM

Upload the krb5.conf file to the eperi sEcure Platform server and put it in this directory: /opt/eperi/gateway/tomcat/webapps/ROOT/etc

Create a login.conf file with the following contents:

spnego-client {
        com.sun.security.auth.module.Krb5LoginModule required;
};
		
spnego-server {
        com.sun.security.auth.module.Krb5LoginModule required
        storeKey=true
        isInitiator=false
        doNotPrompt=true
        principal="HTTP/mygateway.example.com@EXAMPLE.com"
        keyTab="/opt/eperi/gateway/tomcat/webapps/ROOT/etc/example.keytab"
        useKeyTab=true;
};

In the login.conf file adjust the principal name and the path to your keytab file (see the lines marked in bold above).
Upload the login.conf file to the eperi sEcure Platform server and put it in this directory: /opt/eperi/gateway/tomcat/webapps/ROOT/etc
Change the owner and the group of the files krb5.conf, login.conf and the keytab file to eperi:
```
sudo chown eperi:eperi krb5.conf login.conf example.keytab
```
Open the connector.properties file in an editor. The file is located in the classpath of the eperi sEcure Platform, e.g. in /opt/eperi/gateway/tomcat/webapps/ROOT/.

Add the following properties to the connector.properties file:

loginWithKerberos=true
krb5.conf.path=/opt/eperi/gateway/tomcat/webapps/ROOT/etc/krb5.conf
login.conf.path=/opt/eperi/gateway/tomcat/webapps/ROOT/etc/login.conf

If necessary, adjust the paths to the krb5.conf and login.conf files.
Restart the eperi sEcure Platform:
```
systemctl restart eperi-gateway
```
Important: In a cluster setup, the changes must be made on every eperi sEcure Platform instance and each eperi sEcure Platform instance must be restarted.

Results

You have successfully configured SSO for admin accounts with Kerberos. The SSO will work out of the box, if an administrator uses a current version of Google Chrome to access the Admin Console. If this is not the case or other browsers such as Firefox or Internet Explorer are used, additional configuration in the browser settings is required. Additional information about this is for example available here: Configuring Kerberos Authentication in Different Browsers.

There are other optional configuration parameters that that you can use if necessary. For details, see all the parameters that start with "kerberos" in section Configuring local system settings.