SPNEGO authentication

SPNEGO authentication enables users who are logged into their Windows workstation with their domain account to automatically authenticate into CAS and, transitively, into services using CAS authentication. As a result, authentication is seamlessly delegated to Active Directory.

Steps to set up SPNEGO authentication

  1. Prerequisites

  2. MS AD settings and keytab generation

  3. Configuration file preparation

  4. CAS configuration

  5. Browser settings

  6. Testing

Prerequisites

The tutorial uses following values and examples. Change them according to your environment.

Table 1. Configuration values used in the tutorial
Item Value in examples

Domain controller (DC), Microsoft Active Directory (MSAD, AD)

ad.domain.tld

Appliance hostname on which the services are available

iam-appliance.tld

You must always use the full hostname. NetBIOS-style (or other) hostname fragments without specifying the domain are not supported.

AD domain

DOMAIN.TLD

The value must always be in uppercase.

Name of the service registered in AD (Service principal name, SPN).

HTTP/iam-appliance.tld@DOMAIN.TLD

The user account name in AD (UPN logon name) to which the registered service is bound.

cas-user@domain.tld

MS AD settings and keytab generation

  1. Create a dedicated user in MS AD.

    1. In the Active Directory Administrative Center application, navigate to the relevant domain and create a new user account.

    2. Set the user’s UPN logon to cas-user@domain.tld.

    3. Set sAMAccountName to cas-user. The value is usually the same as UPN but without the domain. The ktpass utility used later will change the user’s name to the correct value.

    4. Set any first and last name.

    5. Set following account properties:

      1. Account expires: never

      2. Password never expires (under Password options, Other password options)

      3. User cannot change password (under Password options, Other password options)

      4. Under Encryption options, set:

        1. This account supports Kerberos AES 128 bit encryption

        2. This account supports Kerberos AES 256 bit encryption

    6. Set a password for the account and save it. The password must be set after all the configuration above is finished, otherwise some settings may not take effect.

  2. Open the command line (cmd) and generate the user’s keytab with the command:

    ktpass -out file.keytab -princ HTTP/iam-appliance.tld@DOMAIN.TLD -mapUser cas-user@domain.tld -crypto all -pass * -ptype KRB5_NT_PRINCIPAL

  3. Enter new password. It doesn’t need to be the same as the password for the user.

  4. Download the keytab file file.keytab, you will need to upload it to the appliance.

If you make a mistake when using the ktpass tool, you cannot simply run it again. If you do, multiple SPN records will be created in AD and the integration would not work. If you make a mistake, delete the cas-user@domain.tld completely and create it again.

Configuration file preparation

You need to prepare the following files for the SPNEGO authentication in CAS:

  1. file.keytab - we generated it in the previous step, upload it to the appliance server

  2. krb5.conf - there is a template in the appliance which needs to be modified

  3. login.conf - there is a template in the appliance but it usually doesn’t require any modification

file.keytab

Upload the generated file file.keytab to the appliance, to the /data/volumes/cas/spnego/ directory.

krb5.conf

The file contains information about the domain and its KDC (Key Distribution Center, in the case of AD, this service is provided by the domain controller).

The file template is located in /data/volumes/cas/spnego/krb5.conf. In the file, you need to change the domain name. It is present in several places in different formats, such as EXAMPLE.COM or example.com. Replace all these occurrences with the domain name, while preserving the current format (lower vs. upper case, periods at the beginning of the string, etc.).

Furthermore, the KDC hostname needs to be changed (on line kdc = kdc.example.com:88), use the domain controller as the KDC.

In our example, the resulting file will look like this:

[logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log

[libdefaults]
 ticket_lifetime = 24000
 default_realm = DOMAIN.TLD
 default_keytab_name = /etc/cas/config/file.keytab
 dns_lookup_realm = false
 dns_lookup_kdc = false
 default_tgs_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96
 default_tkt_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96

[realms]
 DOMAIN.TLD = {
  kdc = ad.domain.tld:88
 }

[domain_realm]
 .domain.tld = DOMAIN.TLD
 domain.tld = DOMAIN.TLD

CAS configuration

Using nano or vim, edit the CAS configuration file located in /data/registry/node-active-config/docker-compose-cas.yml. Find the following keys, uncomment them and change the values. In our example, the result will look like this:

- CAS_SPNEGO_ENABLED=true
- CAS_KERBEROS_REALM=DOMAIN.TLD
- CAS_KERBEROS_DEBUG=false
- CAS_KERBEROS_KDC=ad.domain.tld
- CAS_KERBEROS_SERVICE_PRINCIPAL=HTTP/iam-appliance.tld@DOMAIN.TLD

After editing the configuration, restart CAS with the command systemctl restart iam-cas.service.

You can add multiple items to - CAS_KERBEROS_KDC if you use multiple KDCs. Separate each KDC with one space.

Browser settings

If you use Google Chrome or Microsoft Edge, set the configuration in the dialog "Internet Options" in Internet Explorer. These browsers load the SPNEGO configuration from IE.

Internet Explorer

Start Internet Explorer and navigate to Internet Options (under the gear wheel) > Security > Trusted Sites. Click on Sites, then under Add this website to the zone, write https://iam-appliance.tld (appliance hostname).

Then, navigate to Internet Options > Security > Trusted Sites > Custom level, under User Authentication > Logon, check the option Automatic logon with current user name and password.

Firefox

To the Firefox address line, enter about:config and confirm that you want to make changes. To the search field, enter network.negotiate-auth.trusted-uris, open the option and enter https://iam-appliance.tld (appliance hostname).

Testing

Log in to Windows with you domain account. In a configured browser, go to https://iam-appliance.tld/cas/login. If the SPNEGO is working, you will see in the browser that you were logged in successfully. If not, you will see the CAS login dialog. If that happens, the configuration needs to be debugged. The CAS log can be found in /data/logs/cas/cas.log.

For testing and debugging, we recommend you change the debug level in the configuration file /data/registry/node-active-config/docker-compose-czechidm.yml, key - CAS_KERBEROS_DEBUG=, to the value true. Once you finished testing, do not forget to change the value back to false, otherwise the size of the logs will increase significantly and the log will be difficult to make sense of.