Skip to main content
Version: 8.2411.x.x RR

Kerberos authentication AuthStates

Introduction and overview​

The Kerberos AuthStates integrate Kerberos authentication based on the simple and protected GSS-API negotiation mechanism (SPNEGO) into nevisAuth. The Kerberos protocol is supported by all major client operating systems and web browsers.

The Kerberos authentication AuthState requires a key distribution center (KDC) in your network (for example, a Windows domain controller with Active Directory) as well as Kerberos-capable clients.

KerberosLoginAuthState​

Experimental

The KerberosLoginAuthState is in experimental state.

The KerberosLoginAuthState supports passwordless authentication in internal environments. A sample case is where a user logs in to the workstation and opens a browser, which then loads an application on the intranet without the user having to log in additionally.

The KerberosLoginAuthState AuthState uses the SPNEGO protocol to receive a SPNEGO init token containing the Kerberos token and ticket from the client (browser). The AuthState then verifies the token based on the configuration provided in the AuthState's properties.

The AuthState does not support the NTLM (Windows New Technology LAN Manager) protocol as a fallback of SPNEGO/Kerberos (SPNEGO with Kerberos Authentication).

The AuthState also supports multi-realm Kerberos setups with cross-realm trust.

The authentication flow goes as follows:

  1. The browser, which is integrated with Kerberos, sends a request to nevisAuth.
  2. Usually no authentication data is sent in the initial request so nevisAuth initiates the "Negotiate" auth-scheme by returning HTTP status code 401 (Unauthorized) and "WWW-Authenticate: Negotiate" in the response header in line with RFC4559 Section 4.
  3. Receiving the response header a compatible client initiates the SPNEGO protocol on the client side. See also RFC4178.
  4. The browser obtains the necessary Kerberos credentials. This action is out of scope of nevisAuth but might cover user authentication at the Authentication Server (AS) of KDC, exchanging Kerberos ticket granting ticket (TGT) to service ticket (ST) or fetching a valid Kerberos credential from the credential cache of the client machine.
  5. The browser sends the credential as a token (SPNEGO GSSAPI token using the Kerberos mechanism) to nevisAuth. The token is included in the request header: "Authorization: Negotiate <base64encoded token>". See also RFC4559 Section 5.
  6. nevisAuth verifies the token based on the configuration properties of KerberosLoginAuthState. Since the AuthState uses long-term Kerberos keys as service credentials no active network communication with KDC is needed.
  7. Upon successful verification the user is authenticated and nevisAuth grants access to the protected resource. As the outcome of the successful authentication nevisAuth also generates a response GSS token and sends it back to the caller.
  8. Before accessing the protected resource the client browser also has the possibility to mutually authenticate the service using the received response GSS token (final leg).

Description​

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.kerberos.KerberosLoginAuthState
LoggingKerberos
Auditingnone
MarkerKerberos: token
Methodsprocess

Properties​

  • servicePrincipal (string or "auto", -)

    The Service Principal Name (SPN) reflects the fully-qualified virtual host name of the access proxy (i.e., the host name in the URL, accessed by the browser client). It has the format HTTP/<hostname>@<REALM>.

    The Kerberos realm (i.e., the Active Directory domain) needs to be configured in UPPERCASE. It is mandatory to specify the realm.

    If the special value "auto" is configured, the AuthState will extract the SPN from incoming SPNEGO/Kerberos tokens and will look for a related Kerberos credential. Use this feature in scenarios where nevisAuth has to impersonate many SPNs and configuring many AuthStates is not acceptable, or where deciding on the ServicePrincipal to impersonate for a particular request is difficult.

  • kerberosCredentials (path, "conf/kerberos-credentials.properties")

    Path to a properties file containing service principal name and keytab file path pairs. A keytab file stores the long-term Kerberos key of one or more principals. If servicePrincipal defines a specific service principal name then a related entry with the defined SPN has to be present. If servicePrincipal is configured to "auto" then after extracting the SPN from incoming SPNEGO/Kerberos token the AuthState will look for a suitable keytab file using this property file.

    Example kerberos-credentials.properties file content:
    HTTP/service1.hostname@REALM=conf/kerberos.keytab
    HTTP/service2.hostname@REALM=conf/kerberos.keytab
    HTTP/[email protected]=conf/other.keytab

  • permittedRealms (whitespace-separated list of realms or *, defaults to realm of service principal)

    A whitelist of trusted realms, only users from listed realms are allowed. In a multi-realm setup with cross-realm trust this parameter could be used to limit and exclude some realms from the auth flow which are otherwise trusted by the Key Distribution Center (KDC).

    The default behavior allows users only from the realm of the configured service principal. If servicePrincipal is configured to "auto" then default can not be used. Using an asterisk completely disables this check and allows authentication of users irrespective of their realm.

    The permittedRealms property supports variable expressions.

  • userIdFormat (string {full | unqualified}, "full")

    The format of the user ID set upon successful authentication.

    Example assuming a Kerberos user: username@REALM
    UserIdFormatUserIdLoginId
    fullusername@REALMusername@REALM
    unqualifiedusernameusername@REALM

    The userIdFormat property supports variable expressions.

  • limitSessionLifetime (boolean, "false")

    If configured to "true" then the lifetime of the underlying Kerberos service ticket used by the client during the SPNEGO negotiation will be considered when determining the lifetime of Nevis session. In this case the expiration time of Nevis session can not be longer than the expiration time of the Kerberos service ticket.

Input​

  • HTTP/Negotiate authentication header

    If not sent by the client, the AuthState will request the header via nevisProxy. See RFC4559 for details on SPNEGO-based Kerberos authentication.

Transitions​

  • ok

    The SPNEGO based Kerberos authentication was successful and the realm of the user is permitted.

  • failed

    The SPNEGO based Kerberos authentication failed or the realm of the user is not permitted.

  • default

    In any other case.

  • forced-response

    This is a technical transition to initiate SPNEGO based Kerberos authentication if no negotiate token was received from the client.

Output​

  • kerberos.username

    OutArg containing the unqualified Kerberos username of the authenticated user.

  • kerberos.realm

    OutArg with the name of the Kerberos realm of the authenticated user.

Errors​

  • NEGOTIATION_FAILED: Negotiation failed since no SPNEGO token was found in 'Authorization' HTTP header.

  • RETRIEVE_SERVICE_PRINCIPAL_FROM_TOKEN: Cannot retrieve service principal name from SPNEGO token.

  • NO_SHARED_SECRET: No shared secret known for service principal.

    Possible cause:

    • servicePrincipal is configured to "auto" but there is no related entry in kerberosCredentials for the service principal name (SPN) extracted from the incoming SPNEGO token.

  • INIT_SPNEGO_CLIENT: Can not initialize SPNEGO client on server side.

  • CREATE_SPNEGO_CONTEXT: Can not create SPNEGO context.

  • EXTRACT_CLIENT_PRINCIPAL: Can not extract client principal from SPNEGO context.

  • CLIENT_PRINCIPAL_NAME_FORMAT: Expecting client principal name in 'name@REALM' format.

  • ACCEPT_SECURITY_CONTEXT: Can not accept security context (GSS).

  • REALM_CHECK_FAILED: Client is not in a permitted realm.

    Possible cause:

    • Client sent a valid SPNEGO token but its realm is not permitted by the permittedRealms config value.

  • UNEXPECTED_EXCEPTION: An unexpected error occurred.

GUIs​

  • www-authenticate

    This GUI is shown during the automatic login process before the browser sends a Negotiate-Token. Normally, this GUI is only visible for a very short time. In the case of a misconfiguration, however, this GUI may be displayed by the browser and can be used to show the reason of the failure.

  • error

    This GUI is shown in case the browser sent a Negotiate-Token that was not accepted.

Notes​

none

Example​

KerberosLoginAuthState configuration
<AuthState name="KerberosLogin" class="ch.nevis.esauth.auth.states.kerberos.KerberosLoginAuthState" final="false">
  <ResultCond name="ok" next="AuthDone"/>
  <Response value="AUTH_ERROR"/>
  <property name="servicePrincipal" value="HTTP/hostname@REALM"/>
  <property name="kerberosCredentials" value="conf/kerberos-credentials.properties"/>
  <property name="permittedRealms" value="REALM1 REALM2 LOCAL"/>
  <property name="userIdFormat" value="full"/>
  <property name="limitSessionLifetime" value="false"/>
</AuthState>

FrontendKerberosAuthState​

Deprecated

The FrontendKerberosAuthState is deprecated, use KerberosLoginAuthState instead.

Limitations

The following limitations apply when integrating with Microsoft Active Directory:

  • Only DES (type 3) and RC4 (type 23) are supported in combination with the Kerberos ticket extension Privileged Attribute Certificate (PAC). AES128 and AES256 are not supported in combination with the PAC extension.
  • Clients must be integrated with the AD Kerberos realm. NTLM (the fallback default of, for example, MSIE6) is not supported.

You typically use the FrontentKerberosAuthState AuthState for password-less logins in internal environments. A sample case is where a user logs in to the workstation and opens a browser, which then loads an application on the intranet without the user having to log in additionally.

The FrontendKerberosAuthState AuthState uses the SPNEGO protocol to receive a SPNEGO init token containing the Kerberos token and ticket from the client (browser). The AuthState then verifies the token based on the Kerberos configuration provided in the AuthState's properties.

The authentication flow goes as follows:

  1. The browser, which is integrated with Kerberos, sends a request to nevisAuth.
  2. nevisAuth returns the HTTP status code 401 and the response header "WWW-Authenticate: Negotiate", in line with `http://tools.ietf.org/html/rfc4559#section-4.
  3. The response header in the return initiates the SPNEGO protocol on the browser side. See also `http://tools.ietf.org/html/rfc4178.
  4. The browser authenticates the user using Kerberos. This action is out of scope of nevisAuth.
  5. The browser sends the Kerberos token to nevisAuth. The token is included in the request header: "Authorization: Negotiate <base64encoded token>". See also `http://tools.ietf.org/html/rfc4559#section-5.
  6. nevisAuth verifies the client and the token based on the Kerberos configurations in the FrontendKerberosAuthStateAuthState.
  7. Upon successful verification, nevisAuth grants access to the protected resource.

The AuthState supports multi-realm setups with cross-realm trust and chains of different FrontentKerberosAuthStates.

Description​

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.kerberos.FrontendKerberosAuthState
LoggingKerberos
Auditingnone
MarkerKerberos: token
Methodsprocess

Properties​

  • ServicePrincipal (string or "auto", -)

    The principal name reflects the fully qualified virtual host name of the access proxy (i.e., the host name in the URL, accessed by the browser client). It has the format HTTP/<hostname>@<REALM>.

    The Kerberos realm (i.e., the Active Directory domain) needs to be configured in UPPERCASE. It is mandatory to specify the realm.

    If the special value "auto" is configured, the AuthState will extract the SPN from incoming Kerberos tokens and will look for a suitable credential. Use this feature in scenarios where nevisAuth has to impersonate many SPNs and configuring many AuthStates is not acceptable, or where deciding on the ServicePrincipal to impersonate for a particular request is difficult.

  • UserIdFormat (string {full,unqualified}, "full")

    The format of the user ID set upon successful authentication.

    Example
    //Assuming a Kerberos user username@REALM:

    full: UserId="username@REALM", LoginId="username@REALM"
    unqualified: UserId="username", LoginId="username@REALM"

  • PermittedRealms (whitespace-separated list of realms or "*", defaults to realm of principal)

    Only users from realms listed are allowed. The default allows only users from the realm of the principal (HTTP/hostname@REALM). An asterisk disables this check and allows authentication of users irrespective of their realm.

  • BackendServices (whitespace-separated list of service principals, -)

    Each service principal must be of the format HTTP/<hostname-of-backend>@<REALM-OF-BACKEND>.

Special use only​

  • KerberosJaasModule (qualified class name, "com.sun.security.auth.module.Krb5LoginModule")

    Java class that implements javax.security.auth.spi.LoginModule.

  • LoginModule-<option>

    Options for KerberosJaasModule. In most situations, this property should not be set as the AuthState injects all necessary options automatically. For a list of supported options, see the official documentation

  • LongTermSharedSecretProvider (qualified class name, "ch.nevis.esauth.auth.states.kerberos.PropertiesFileBasedLongTermSharedSecretProvider")

    Java class that provides the key material for this AuthState. The key material is security-sensitive and should be protected accordingly.

  • LongTermSharedSecretProvider-<option>

    Options for the LongTermSharedSecretProvider. The property provider PropertiesFileBasedLongTermSharedSecretProvider supports the following options:

    • LongTermSharedSecretProvider-Path: Path to the properties file configuring the provider. Default: "/var/opt/nevisauth/$instance$/conf/kerberos-credentials.properties".

PAC Processing​

  • processPAC (boolean, "false")

    This property switches on the processing of PAC, a Microsoft extension structure embedded into Kerberos tokens by the Microsoft ActiveDirectory. See the topic "Notes" in this table for a list of propagated data.

  • pacMapping (whitespace-separated list of colon-separated key/value pairs, "")

    When PAC processing is enabled, use this property to define role names for group SIDs. Mapped values will be added to the list of the user's roles.

    Example
    <property name="paxMapping" value="S-1-5-21-1180699209-877415012-3182924384-1004:aRole S-3-43-74284-203:bRole" />

  • includeExtraSids (boolean, "false")

    In addition to the group SIDs, the extra SIDs will also be processed according to the pacMapping configured.

Input​

  • HTTP/Negotiate authentication header

    If not sent by the client, the AuthState will request the header via nevisProxy. See RFC4559 for details on SPNEGO-based Kerberos authentication.

Transitions​

  • ok

    SPNEGO token was successfully checked and the user's identity extracted from it. The user's realm is permitted.

  • ntlm

    An NTLM token was found. The FrontEndKerberosAuthstate does not support NTLM and will not do anything except setting the result.

  • failed

    In case the token could not be recognized as either SPNEGO or NTLM.

  • default

    In any other case. May be used to concatenate multiple KerberosFrontends AuthStates with differing configuration.

Output​

none

Errors​

  • lasterror=1

    lasterrorinfo=NO_STATUS: internal error – status not set

  • lasterror=1

    lasterrorinfo=SUCCESS_GSS: authenticated successfully at GSS level, further checks needed

  • lasterror=1

    lasterrorinfo=SUCCESS_OVERALL: authenticated successfully

  • lasterror=1

    lasterrorinfo=REALM_CHECK_FAILED: The client was authenticated successfully using Kerberos, but it is not in the list of permitted realms.

  • lasterror=1

    lasterrorinfo=NEGOTIATE_INVALID: The HTTP header Authorization from the client is not a valid negotiate header.

  • lasterror=1

    lasterrorinfo=NTLMSSP: unsupported protocol – NTLMSSP

  • lasterror=1

    lasterrorinfo=CHECKSUM_FAILED: could not verify the checksum in the authenticator.

    Possible causes include:

    • The configured key for the ServicePrincipal is wrong.
    • A setup with multiple keys for this ServicePrincipal is used and only one of the keys will match.
    • A setup with chained FrontendKerberosAuthStates is used. Only one of them will match.
    • The client has an old service ticket in his credentials cache.
    • An attacker is trying an online brute force attack on the service key.

  • lasterror=1

    lasterrorinfo=OTHER_GSS_ERROR: unknown GSS error

  • lasterror=1

    lasterrorinfo=ANONYMOUS: Anonymous Kerberos is not allowed.

GUIs​

  • www-authenticate

    This GUI is shown during the automatic login process before the browser sends a Negotiate-Token. Normally, this GUI is only visible for a very short time. In the case of a misconfiguration, however, this GUI may be displayed by the browser and can be used to show the reason of the failure.

  • error

    This GUI is shown in case the browser sent a Negotiate-Token that was not accepted.

Notes​

None by default

If processPAC is enabled, the following notes will be set:

  • kerberos.pac.UserAccountControl

    A comma-separated list of flags active in the UserAccountControl field, such as USER_DONT_EXPIRE_PASSWORD, USER_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION, etc.

  • kerberos.pac.groupSids

    A comma-separated list of the group SIDs of the user. SIDs may be mapped to human-readable values with the property pacMapping. If an SID is mapped by this property, the result will be interpreted as a role and added to the user's list of roles.

The following notes are set to the corresponding fields of the PAC:

  • kerberos.pac.badPasswordCount
  • kerberos.pac.resourceGroupSids
  • kerberos.pac.logonCount
  • kerberos.pac.domainName
  • kerberos.pac.groupSid
  • kerberos.pac.homeDirectory
  • kerberos.pac.homeDrive
  • kerberos.pac.kickOffTime
  • kerberos.pac.logoffTime
  • kerberos.pac.lognScript
  • kerberos.pac.logonTime
  • kerberos.pac.profilePath
  • kerberos.pac.pwdLastChangeTime
  • kerberos.pac.pwdMustChangeTime
  • kerberos.pac.serverName
  • kerberos.pac.userDisplayName
  • kerberos.pac.userName
  • kerberos.pac.userSid
  • kerberos.pac.extraSids
info

For more information on the above fields and PAC in general, see MS-PAC, Privilege Attribute Certificate Data Structure. The flags of the UserAccountControl are described in MS-SAMR, Security Account Manager (SAM) Remote Protocol (Client-to-Server), chapter 2.2.1.12.

Example​

A sample configuration is shown and explained in the chapter Integrating with a Kerberos environment - AD.

BackendKerberosAuthState​

Deprecated

The BackendKerberosAuthState is deprecated.

This AuthState authenticates the user towards a KDC and expects a ticket-granting ticket (TGT) upon success. With this TGT, the AuthState recontacts the KDC and requests service tickets for each configured backend. The service tickets are then forwarded to nevisProxy for injection by the DelegationFilter as SPNEGO tokens. Kerberos-capable backends receive the tokens in the HTTP header Authorization: Negotiate <token>, which enables them to verify the identity of the user.

info
  • Multi-realm setups are not supported.
  • Tickets have a limited lifetime (per default 10 hours). After this time, the user has to re-authenticate himself again with his username and password

Description​

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.kerberos.BackendKerberosAuthState
LoggingKerberos
Auditingnone
Markernone
Methodsprocess

Properties​

  • UserNameSource (string, -)

    This property must evaluate to a user name without realm or protocol. nevisAuth variable expressions may be used.

  • RealmSource (string, -)

    This property must evaluate to the realm without principal or protocol. nevisAuth variable expressions may be used. By convention, realms are written in UPPERCASE.

  • PasswordSource (string,-)

    This property must evaluate to a password or a password source. See the chapter Passwords in the configuration for supported encoding mechanisms. The source may also start with keytab://... and specify the path to a keytab file containing the key. Passwords should never be specified in the configuration in plaintext.

  • TicketFormat (string, "fcc")

    Possible values are: fcc, java and apreq. Defines the format of the propagated service ticket. fcc is the service ticket format for c. It must be used if nevisProxy delegates the Kerberos ticket.

  • UserIdFormat, PermittedRealms, BackendServices, KerberosJaasModule, LoginModule-<option>

    See FrontendKerberosAuthState

Input​

Only values provided by variable substitution

Transitions​

  • ok

    Successful authentication

  • default

    In any other case

Output​

none

Errors​

  • lasterror=1

    lasterrorinfo=username and/or realm not specified

  • lasterror=1

    lasterrorinfo=This realm is not in the list of permitted realms.

  • lasterror=1

    lasterrorinfo=Login failed

Notes​

none

Example​

A sample configuration is shown and explained in the chapter Integrating with a Kerberos environment - AD.