SPNEGO Authentication

SPNEGO is an authentication technology that is primarily used to provide transparent CAS authentication to browsers running on Windows running under Active Directory domain credentials. There are three actors involved: the client, the CAS server, and the Active Directory Domain Controller/KDC.

  1. Client sends CAS: HTTP GET to CAS for cas protected page
  2. CAS responds: HTTP 401 - Access Denied WWW-Authenticate: Negotiate
  3. Client sends ticket request: Kerberos(KRB_TGS_REQ) Requesting ticket for HTTP/cas.example.com@REALM
  4. Kerberos KDC responds: Kerberos(KRB_TGS_REP) Granting ticket for HTTP/cas.example.com@REALM
  5. Client sends CAS: HTTP GET Authorization: Negotiate w/SPNEGO Token
  6. CAS responds: HTTP 200 - OK WWW-Authenticate w/SPNEGO response + requested page.

The above interaction occurs only for the first request, when there is no CAS SSO session. Once CAS grants a ticket-granting ticket, the SPNEGO process will not happen again until the CAS ticket expires.

Requirements

  • Client is logged in to a Windows Active Directory domain.
  • Supported browser.
  • CAS is running MIT kerberos against the AD domain controller.
:information_source: JCE Requirement

It's safe to make sure you have the proper JCE bundle installed in your Java environment that is used by CAS, specially if you need to consume encrypted payloads issued by ADFS. Be sure to pick the right version of the JCE for your Java version. Java versions can be detected via the java -version command.

:information_source: Large Kerberos Tickets

If organization users have large kerberos tickets, likely cause by being a member of a large number of groups, the Tomcat connector will need to have the maxHttpHeaderSize value increased from the default amount to allow the ticket to be passed to the CAS Server application.

Components

SPNEGO support is enabled by including the following dependency in the WAR overlay:



1
2
3
4
5



<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-spnego-webflow</artifactId>
    <version>${cas.version}</version>
</dependency>





1



implementation "org.apereo.cas:cas-server-support-spnego-webflow:${project.'cas.version'}"





1
2
3
4
5
6
7
8
9



dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-spnego-webflow"
}





1
2
3
4
5
6



dependencies {
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

    implementation "org.apereo.cas:cas-server-support-spnego-webflow"
}

JCIFS SDK

Note that jcifs-ext library is no longer published to a public Maven repository. This means that you will need to download the necessary JAR files and include them in your build configuration. The SDK may be downloaded from the CAS codebase. Then, assuming the SDK is placed inside a lib directory of the WAR overlay directory, it can be referenced in the build configuration as such:



1



implementation files("${projectDir}/lib/jcifs-ext.jar")

Configuration

The following steps are required to turn on the SPNEGO functionality.

Create SPN Account

Create an Active Directory account for the Service Principal Name (SPN) and record the username. Password will be overwritten by the next step.

Create Keytab File

The keytab file enables a trust link between the CAS server and the Key Distribution Center (KDC); an Active Directory domain controller serves the role of KDC in this context. The ktpass tool is used to generate the keytab file, which contains a cryptographic key. Be sure to execute the command from an Active Directory domain controller as administrator (a member of domain administrators will not be able to use ktpass successfully).

Example:



1
2
3
4
5
6
7
8
9
10
11



C:\Users\administrator.DOMAIN>ktpass /out myspnaccount.keytab /princ HTTP/cas.example.com@REALM /pass * /mapuser domain-account@YOUR.REALM /ptype KRB5_NT_PRINCIPAL /crypto RC4-HMAC-NT
Targeting domain controller: DC.YOUR.REALM
Successfully mapped HTTP/cas.example.com to domaine-account.
Type the password for HTTP/cas.example.com:
Type the password again to confirm:
Password succesfully set!
Key created.
Output keytab to myspnaccount.keytab:
Keytab version: 0x502
keysize 69 HTTP/cas.example.com@REALM ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x17 (RC4-HMAC) keylength 16
(0x00112233445566778899aabbccddeeff)

Using ktpass requires Active Directory admin permissions. If that is not an option, you may be able to use ktab.exe from %JAVA_HOME%\bin\ktab.exe that is provided by the JDK:



1



%JAVA_HOME%\bin\ktab.exe -a service_xxx -n 0 -k cas.keytab

-k specifies key tab output file name and -n 0 specifies the KNVO number if available and found for the user account. This value may match the msDS-KeyVersionNumber on the user account.

Also note that the keytab file must be regenerated after password changes, if any.

Test SPN Account

Install and configure MIT Kerberos V on the CAS server host(s). The following sample krb5.conf file may be used as a reference.



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22



[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 = YOUR.REALM.HERE
 default_keytab_name = /home/cas/kerberos/myspnaccount.keytab
 dns_lookup_realm = false
 dns_lookup_kdc = false
 default_tkt_enctypes = rc4-hmac
 default_tgs_enctypes = rc4-hmac

[realms]
 YOUR.REALM.HERE = {
  kdc = your.kdc.your.realm.here:88
 }

[domain_realm]
 .your.realm.here = YOUR.REALM.HERE
 your.realm.here = YOUR.REALM.HERE

It is important to note that myspnaccount.keytab is declared as default keytab, otherwise CAS may not be able to find it and will raise an exception similar to



1



KrbException: Invalid argument (400) - Cannot find key of appropriate type to decrypt AP REP -RC4 with HMAC`

Then verify that your are able to read the keytab file:



1
2
3
4
5



klist -k
Keytab name: FILE:/home/cas/kerberos/myspnaccount.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   3 HTTP/cas.example.com@REALM

Then verify that your are able to use the keytab file:



1
2
3
4
5
6
7
8



kinit -k HTTP/cas.example.com@REALM
klist
Ticket cache: FILE:/tmp/krb5cc_999
Default principal: HTTP/cas.example.com@REALM

Valid starting       Expires              Service principal
12/08/2016 10:52:00  12/08/2016 20:52:00  krbtgt/REALM@REALM
    renew until 12/08/2016 20:52:00

Browser Configuration

  • Internet Explorer - Enable Integrated Windows Authentication and add the CAS server URL to the Local Intranet zone.
  • Firefox - Set the network.negotiate-auth.trusted-uris configuration parameter in about:config to the CAS server URL, e.g. https://cas.example.com.

Authentication Configuration

Make sure you have at least specified the JCIFS Service Principal in the CAS configuration.

The following settings and properties are available from the CAS configuration catalog:

The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.authn.spnego.principal-transformation.groovy.location=

    • The location of the resource. Resources can be URLs, or files found either on the classpath or outside somewhere in the file system.

    In the event the configured resource is a Groovy script, specially if the script set to reload on changes, you may need to adjust the total number of inotify instances. On Linux, you may need to add the following line to /etc/sysctl.conf: fs.inotify.max_user_instances = 256.

    You can check the current value via cat /proc/sys/fs/inotify/max_user_instances.

    org.apereo.cas.configuration.model.core.authentication.GroovyPrincipalTransformationProperties.
  • cas.authn.spnego.principal.principal-transformation.groovy.location=

    • The location of the resource. Resources can be URLs, or files found either on the classpath or outside somewhere in the file system.

    In the event the configured resource is a Groovy script, specially if the script set to reload on changes, you may need to adjust the total number of inotify instances. On Linux, you may need to add the following line to /etc/sysctl.conf: fs.inotify.max_user_instances = 256.

    You can check the current value via cat /proc/sys/fs/inotify/max_user_instances.

    org.apereo.cas.configuration.model.core.authentication.GroovyPrincipalTransformationProperties.
  • cas.authn.spnego.properties[0].jcifs-service-principal=HTTP/cas.example.com@EXAMPLE.COM

    • The Jcifs service principal.

    org.apereo.cas.configuration.model.support.spnego.SpnegoAuthenticationProperties.
  • cas.authn.spnego.ldap.base-dn=

    • Base DN to use. There may be scenarios where different parts of a single LDAP tree could be considered as base-dns. Rather than duplicating the LDAP configuration block for each individual base-dn, each entry can be specified and joined together using a special delimiter character. The user DN is retrieved using the combination of all base-dn and DN resolvers in the order defined. DN resolution should fail if multiple DNs are found. Otherwise the first DN found is returned. Usual syntax is: subtreeA,dc=example,dc=net|subtreeC,dc=example,dc=net.

    org.apereo.cas.configuration.model.support.spnego.SpnegoLdapProperties.
  • cas.authn.spnego.ldap.bind-credential=

    • The bind credential to use when connecting to LDAP.

    org.apereo.cas.configuration.model.support.spnego.SpnegoLdapProperties.
  • cas.authn.spnego.ldap.bind-dn=

    • The bind DN to use when connecting to LDAP. LDAP connection configuration injected into the LDAP connection pool can be initialized with the following parameters:

    • bindDn/bindCredential provided - Use the provided credentials to bind when initializing connections.
    • bindDn/bindCredential set to * - Use a fast-bind strategy to initialize the pool.
    • bindDn/bindCredential set to blank - Skip connection initializing; perform operations anonymously.
    • SASL mechanism provided - Use the given SASL mechanism to bind when initializing connections.

    org.apereo.cas.configuration.model.support.spnego.SpnegoLdapProperties.
  • cas.authn.spnego.ldap.ldap-url=

    • The LDAP url to the server. More than one may be specified, separated by space and/or comma.

    org.apereo.cas.configuration.model.support.spnego.SpnegoLdapProperties.
  • cas.authn.spnego.ldap.search-filter=

    • User filter to use for searching. Syntax is cn={user} or cn={0}.

    You may also provide an external groovy script in the syntax of file:/path/to/GroovyScript.groovy to fully build the final filter template dynamically.

    org.apereo.cas.configuration.model.support.spnego.SpnegoLdapProperties.
    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value. In other words, you should only include this field in your configuration if you need to modify the default value or if you need to turn on the feature controlled by the setting.

  • cas.authn.spnego.principal-transformation.blocking-pattern=

    • A regular expression that will be used against the username to match for blocking/forbidden values. If a match is found, an exception will be thrown and principal transformation will fail.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal-transformation.case-conversion=NONE

    • Indicate whether the principal identifier should be transformed into upper-case, lower-case, etc. Available values are as follows:

    • NONE: No conversion.
    • LOWERCASE: Lowercase conversion.
    • UPPERCASE: Uppercase conversion.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal-transformation.pattern=

    • A regular expression that will be used against the provided username for username extractions. On a successful match, the first matched group in the pattern will be used as the extracted username.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal-transformation.prefix=

    • Prefix to add to the principal id prior to authentication.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal-transformation.suffix=

    • Suffix to add to the principal id prior to authentication.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal.active-attribute-repository-ids=

    • Activated attribute repository identifiers that should be used for fetching attributes if attribute resolution is enabled. The list here may include identifiers separated by comma.

    org.apereo.cas.configuration.model.core.authentication.PersonDirectoryPrincipalResolverProperties.
  • cas.authn.spnego.principal.attribute-resolution-enabled=

    • Whether attribute repositories should be contacted to fetch person attributes. Defaults to true if not set.

    org.apereo.cas.configuration.model.core.authentication.PersonDirectoryPrincipalResolverProperties.
  • cas.authn.spnego.principal.principal-attribute=

    • Attribute name to use to indicate the identifier of the principal constructed. If the attribute is blank or has no values, the default principal id will be used determined by the underlying authentication engine. The principal id attribute usually is removed from the collection of attributes collected, though this behavior depends on the schematics of the underlying authentication strategy.

    org.apereo.cas.configuration.model.core.authentication.PersonDirectoryPrincipalResolverProperties.
  • cas.authn.spnego.principal.principal-resolution-conflict-strategy=last

    • In the event that the principal resolution engine resolves more than one principal, (specially if such principals in the chain have different identifiers), this setting determines strategy by which the principal id would be chosen from the chain. Accepted values are: last, first.

    org.apereo.cas.configuration.model.core.authentication.PersonDirectoryPrincipalResolverProperties.
  • cas.authn.spnego.principal.principal-resolution-failure-fatal=

    • When true, throws an error back indicating that principal resolution has failed and no principal can be found based on the authentication requirements. Otherwise, logs the condition as an error without raising a catastrophic error.

    org.apereo.cas.configuration.model.core.authentication.PersonDirectoryPrincipalResolverProperties.
  • cas.authn.spnego.principal.principal-transformation.blocking-pattern=

    • A regular expression that will be used against the username to match for blocking/forbidden values. If a match is found, an exception will be thrown and principal transformation will fail.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal.principal-transformation.case-conversion=NONE

    • Indicate whether the principal identifier should be transformed into upper-case, lower-case, etc. Available values are as follows:

    • NONE: No conversion.
    • LOWERCASE: Lowercase conversion.
    • UPPERCASE: Uppercase conversion.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal.principal-transformation.pattern=

    • A regular expression that will be used against the provided username for username extractions. On a successful match, the first matched group in the pattern will be used as the extracted username.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal.principal-transformation.prefix=

    • Prefix to add to the principal id prior to authentication.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal.principal-transformation.suffix=

    • Suffix to add to the principal id prior to authentication.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.core.authentication.PrincipalTransformationProperties.
  • cas.authn.spnego.principal.return-null=

    • Return a null principal object if no attributes can be found for the principal.

    org.apereo.cas.configuration.model.core.authentication.PersonDirectoryPrincipalResolverProperties.
  • cas.authn.spnego.principal.use-existing-principal-id=

    • Uses an existing principal id that may have already been established in order to run person directory queries. This is generally useful in situations where authentication is delegated to an external identity provider and a principal is first established to then query an attribute source.

    org.apereo.cas.configuration.model.core.authentication.PersonDirectoryPrincipalResolverProperties.
  • cas.authn.spnego.webflow.enabled=true

    • Whether webflow auto-configuration should be enabled.

    org.apereo.cas.configuration.model.core.web.flow.WebflowAutoConfigurationProperties.
  • cas.authn.spnego.webflow.order=0

    • The order in which the webflow is configured.

    org.apereo.cas.configuration.model.core.web.flow.WebflowAutoConfigurationProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].case-change.attribute-name-case-change=

    • The Attribute name case change.

    org.apereo.cas.configuration.model.support.ldap.CaseChangeSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].case-change.attribute-names=

    • The Attribute names.

    org.apereo.cas.configuration.model.support.ldap.CaseChangeSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].case-change.attribute-value-case-change=

    • The Attribute value case change.

    org.apereo.cas.configuration.model.support.ldap.CaseChangeSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].case-change.dn-case-change=

    • The Dn case change.

    org.apereo.cas.configuration.model.support.ldap.CaseChangeSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].dn-attribute.add-if-exists=

    • The Add if exists.

    org.apereo.cas.configuration.model.support.ldap.DnAttributeSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].dn-attribute.dn-attribute-name=entryDN

    • The Dn attribute name.

    org.apereo.cas.configuration.model.support.ldap.DnAttributeSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].merge-attribute.attribute-names=

    • The Attribute names.

    org.apereo.cas.configuration.model.support.ldap.MergeAttributesSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].merge-attribute.merge-attribute-name=

    • The Merge attribute name.

    org.apereo.cas.configuration.model.support.ldap.MergeAttributesSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].primary-group-id.base-dn=

    • The Base dn.

    org.apereo.cas.configuration.model.support.ldap.PrimaryGroupIdSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].primary-group-id.group-filter=(&(objectClass=group)(objectSid={0}))

    • The Group filter.

    org.apereo.cas.configuration.model.support.ldap.PrimaryGroupIdSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].recursive.merge-attributes=

    • The Merge attributes.

    org.apereo.cas.configuration.model.support.ldap.RecursiveSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].recursive.search-attribute=

    • The Search attribute.

    org.apereo.cas.configuration.model.support.ldap.RecursiveSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].search-referral.limit=10

    • The default referral limit.

    org.apereo.cas.configuration.model.support.ldap.FollowReferralSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].search-result.limit=10

    • The default referral limit.

    org.apereo.cas.configuration.model.support.ldap.FollowResultSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.search-entry-handlers[0].type=

    • The type of search entry handler to choose. Available values are as follows:

    • FOLLOW_SEARCH_REFERRAL: Provides handling of an ldap referral for search operations.
    • FOLLOW_SEARCH_RESULT_REFERENCE: Provides handling of an ldap continuation reference for search operations.
    • ACTIVE_DIRECTORY: Process the entry results fetched from active directory and check for account status controls for disabled/expired accounts, etc.
    • OBJECT_GUID: Object guid search entry handler. Handles the objectGUID attribute fetching and conversion.
    • OBJECT_SID: Object sid search entry handler. Handles the objectSid attribute fetching and conversion.
    • CASE_CHANGE: Case change search entry handler. Provides the ability to modify the case of search entry DNs, attribute names, and attribute values.
    • DN_ATTRIBUTE_ENTRY: DN attribute entry handler. Adds the entry DN as an attribute to the result set. Provides a client side implementation of RFC 5020.
    • MERGE: Merge search entry handler. Merges the values of one or more attributes into a single attribute.
    • PRIMARY_GROUP: Primary group search handler. Constructs the primary group SID and then searches for that group and puts it's DN in the memberOf attribute of the original search entry.
    • RANGE_ENTRY: Range entry search handler. Rewrites attributes returned from Active Directory to include all values by performing additional searches.
    • RECURSIVE_ENTRY: Recursive entry search handler. This recursively searches based on a supplied attribute and merges those results into the original entry.
    • MERGE_ENTRIES: Merge entries handler. Merges the values of one or more attributes in all entries into a single attribute. The merged attribute may or may not already exist on the entry. If it does exist it's existing values will remain intact.

    org.apereo.cas.configuration.model.support.ldap.LdapSearchEntryHandlersProperties.
  • cas.authn.spnego.ldap.validator.attribute-name=objectClass

    • Attribute name to use for the compare validator.

    org.apereo.cas.configuration.model.support.ldap.LdapValidatorProperties.
  • cas.authn.spnego.ldap.validator.attribute-value=top

    • Attribute values to use for the compare validator.

    org.apereo.cas.configuration.model.support.ldap.LdapValidatorProperties.
  • cas.authn.spnego.ldap.validator.base-dn=

    • Base DN to use for the search request of the search validator.

    org.apereo.cas.configuration.model.support.ldap.LdapValidatorProperties.
  • cas.authn.spnego.ldap.validator.dn=

    • DN to compare to use for the compare validator.

    org.apereo.cas.configuration.model.support.ldap.LdapValidatorProperties.
  • cas.authn.spnego.ldap.validator.scope=OBJECT

    • Search scope to use for the search request of the search validator.

    org.apereo.cas.configuration.model.support.ldap.LdapValidatorProperties.
  • cas.authn.spnego.ldap.validator.search-filter=(objectClass=*)

    • Search filter to use for the search request of the search validator.

    org.apereo.cas.configuration.model.support.ldap.LdapValidatorProperties.
  • cas.authn.spnego.ldap.validator.type=search

    • Determine the LDAP validator type.

    The following LDAP validators can be used to test connection health status:
    • search: Validates a connection is healthy by performing a search operation. Validation is considered successful if the search result size is greater than zero.
    • none: No validation takes place.
    • compare: Validates a connection is healthy by performing a compare operation.

    org.apereo.cas.configuration.model.support.ldap.LdapValidatorProperties.