JBoss.orgCommunity Documentation

Chapter 20. Kerberos brokering

20.1. Setup of Kerberos server
20.2. Setup and configuration of Keycloak server
20.3. Setup and configuration of client machines
20.4. Example setups
20.4.1. Keycloak and FreeIPA docker image
20.4.2. ApacheDS testing Kerberos server
20.5. Credential delegation
20.6. Troubleshooting

Keycloak supports login with Kerberos ticket through SPNEGO. SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is used to authenticate transparently through the web browser after the user has been authenticated when logging-in his session. For non-web cases or when ticket is not available during login, Keycloak also supports login with Kerberos username/password.

A typical use case for web authentication is the following:

  1. User logs into his desktop (Such as a Windows machine in Active Directory domain or Linux machine with Kerberos integration enabled).

  2. User then uses his browser (IE/Firefox/Chrome) to access a web application secured by Keycloak.

  3. Application redirects to Keycloak login.

  4. Keycloak sends HTML login screen together with status 401 and HTTP header WWW-Authenticate: Negotiate

  5. In case that browser has Kerberos ticket from desktop login, it transfers the desktop sign on information to the Keycloak in header Authorization: Negotiate 'spnego-token' . Otherwise it just displays login screen.

  6. Keycloak validates token from browser and authenticate user. It provisions user data from LDAP (in case of LDAPFederationProvider with Kerberos authentication support) or let user to update his profile and prefill data (in case of KerberosFederationProvider).

  7. Keycloak returns back to the application. Communication between Keycloak and application happens through OpenID Connect or SAML messages. The fact that Keycloak was authenticated through Kerberos is hidden from the application. So Keycloak acts as broker to Kerberos/SPNEGO login.

For setup there are 3 main parts:

  1. Setup and configuration of Kerberos server (KDC)

  2. Setup and configuration of Keycloak server

  3. Setup and configuration of client machines

This is platform dependent. Exact steps depend on your OS and the Kerberos vendor you're going to use. Consult Windows Active Directory, MIT Kerberos and your OS documentation for how exactly to setup and configure Kerberos server.

At least you will need to:

  • Add some user principals to your Kerberos database. You can also integrate your Kerberos with LDAP, which means that user accounts will be provisioned from LDAP server.

  • Add service principal for "HTTP" service. For example if your Keycloak server will be running on www.mydomain.org you may need to add principal HTTP/www.mydomain.org@MYDOMAIN.ORG assuming that MYDOMAIN.ORG will be your Kerberos realm.

    For example on MIT Kerberos you can run "kadmin" session. If you are on same machine where is MIT Kerberos, you can simply use command:

    sudo kadmin.local
    

    Then add HTTP principal and export his key to keytab file with the commands like:

    addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG
    ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG
    

    Keytab file /tmp/http.keytab will need to be accessible on the host where keycloak server will be running.

Clients need to install kerberos client and setup krb5.conf as described above. Additionally they need to enable SPNEGO login support in their browser. See for example this for more info about Firefox. URI .mydomain.org must be allowed in network.negotiate-auth.trusted-uris config option.

In windows domain, clients usually don't need to configure anything special as IE is already able to participate in SPNEGO authentication for the windows domain.

For easier testing with Kerberos, we provided some example setups to test.

Once you install docker, you can run docker image with FreeIPA server installed. FreeIPA provides integrated security solution with MIT Kerberos and 389 LDAP server among other things . The image provides also Keycloak server configured with LDAP Federation provider and enabled SPNEGO/Kerberos authentication against the FreeIPA server. See details here .

For quick testing and unit tests, we use very simple ApacheDS Kerberos server. You need to build Keycloak from sources and then run Kerberos server with maven-exec-plugin from our testsuite. See details here .

One scenario supported by Kerberos 5 is credential delegation. In this case when user receives forwardable TGT and authenticates to the web server, then web server might be able to reuse the ticket and forward it to another service secured by Kerberos (for example LDAP server or IMAP server).

The scenario is supported by Keycloak, but there is tricky thing that SPNEGO authentication is done by Keycloak server but GSS credential will need to be used by your application. So you need to enable built-in gss delegation credential protocol mapper in admin console for your application. This will cause that Keycloak will deserialize GSS credential and transmit it to the application in access token. Application will need to deserialize it and use it for further GSS calls against other services.

GSSContext will need to be created with this credential passed to the method GSSManager.createContext for example like this:

GSSContext context = gssManager.createContext(serviceName, krb5Oid,
    deserializedGssCredFromKeycloakAccessToken, GSSContext.DEFAULT_LIFETIME);

Note that you also need to configure forwardable kerberos tickets in krb5.conf file and add support for delegated credentials to your browser. See the kerberos example from Keycloak example set for details.

If you have issues, we recommend to enable more logging by:

  • Enable Debug flag in admin console for Kerberos or LDAP federation providers

  • Enable TRACE logging for category org.keycloak in logging section of $WILDFLY_HOME/standalone/configuration/standalone.xml to receive more info $WILDFLY_HOME/standalone/log/server.log

  • Add system properties -Dsun.security.krb5.debug=true and -Dsun.security.spnego.debug=true