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

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.

Topic	Description
Class	ch.nevis.esauth.auth.states.kerberos.KerberosLoginAuthState
Logging	Kerberos
Auditing	none
Marker	Kerberos: token
Methods	process

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

  UserIdFormat	UserId	LoginId
  full	username@REALM	username@REALM
  unqualified	username	username@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>