Provide single sign-on services for Kerberos realms like Microsoft Active Directory domain environments.
A Kerberos authentication node for ForgeRock's Identity Platform 6.5.2 and above. The node recognizes and validates Kerberos tokens. The web browser presents a Kerberos token to ForgeRock's Access Management (AM) through the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. The Kerberos node enables desktop single sign on such that a user who has already authenticated with a Kerberos Key Distribution Center can use that existing login and authenticate to AM without having to provide the login information again. Users might need to set up Integrated Windows Authentication in Internet Explorer or Microsoft Edge to benefit from single sign on when logged on to a Windows desktop.
Why would you used this node over the Windows Desktop SSO Node? The current version of the WDSSO node is not thread safe. If you run multiple instances of the node with different configurations across multiple trees, you will see unpredictable behavior and errors. This will worsen the heavier the load is. Additionally, The WDSSO node requires domains to have a trust relationship in order for multi-domain logins to work. The Kerberos node remedies both of those issues.
Download a release build fom the release tab or clone this repository to build your own release. Copy the .jar file from your download location or the ./target directory (if you built it yourself) into the ../web-container/webapps/openam/WEB-INF/lib directory where AM is deployed. Restart the web container to pick up the new node. The node will then appear in the authentication trees components palette.
This node supports any of the following scenarios:
- Single Active Directory Domain / Single Kerberos Realm
- Multiple Active Directory Domains
WithDomain Trusts / Multiple Kerberos Realms
- Multiple Active Directory Domains
WithoutDomain Trusts / Multiple Kerberos Realms
This example flow showcases the Kerberos Node being used as the first node in the flow. If the node can successfully extract and validate a Kerberos token from the browser request, the flow will take the "true" exit. If no Kerberos token is found or an invalid token is found, the flow will take the "false" exit and prompt the user to authenticate the traditional way.
The Kerberos node requires the following pieces of configuration and artifacts to function properly:
- A service principal account in each Kerberos realm (=Active Directory domain) used for token validation. The name of the service principal must be the DNS name of the AM instance/cluster/server hosting the Kerberos node.
- DNS A-record pointing to the AM server host name used for the service principal.
- A keytab file for each service principal account stored on the AM server instance.
- A list of all the Kerberos realms and their KDCs
- A list of domain names and which Kerberos realm they map to
The configuration is split between a global Kerberos Configuration Service in AM and the node configuration. The parameters configured in the global service apply to all the nodes across all the AM realms. The underlying Java Kerberos implementation is applying these settings JVM-wide. The remaining node settings apply only to the particular node instance, thus allowing individual node behavior amid the global settings.
|Kerberos Node Settings|
|Principals & Keytabs||Specify a list of service principals in the key column and their respective keytab file names in the value column. The format of the service principal must be:
|Trusted Kerberos Realms||White list of trusted Kerberos Realms for user Kerberos tickets. If the list is empty, Kerberos tickets from all realms are accepted. In a setup where multiple Active Directory domains are connected through domain trusts, a subset of trusted domains can be explicitly white listed and only users from those domains will be able to login. Note that this setting takes Kerberos realm names, which are usually UPPERCASED DOMAIN NAMES.|
|Return Principal with Domain Name||Return the fully qualified name of the authenticated user rather than just the username.|
|Lookup User In Realm||Validate that the user has a matched user profile configured in the current AM realm's data store.|
|Is Initiator||Set this to true, if initiator. Set this to false, if acceptor only. (Default is true). Note: Do not set this value to false for initiators. The principal name can be set to "*" when
|Kerberos Configuration Service Settings|
|Use External krb5.conf||Enabling this setting instructs the nodes to ignore all the settings below. Settings on this page only apply when this option is disabled (default). If enabled, the service attempts to locate a krb5.conf file on the AM server as follows:
|Kerberos V5 Library Defaults||Settings used by the Kerberos V5 library. This setting corresponds to the
|Realm To KDC Map||Realm-specific contact information and settings. This setting corresponds to the
|Domain To Realm Map||Maps server hostnames and Active Directory domains to Kerberos realms. This setting corresponds to the
|Authentication Paths||Authentication paths for non-hierarchical cross-realm. This setting corresponds to the
Create Service Principal Account And KeyTab File
Create a user in Active Directory to be your service principal.
Choose a regular username for the account, you will need to reference that username later on when generating the keytab file.
Disallow changes to the password and make sure it doesn't get reset. If it does, you will need to re-generate the keytab file.
To generate a valid Kerberos keytab file for the service account, use the following
ktpass -out idp37_2.keytab -princ HTTP/idp37.mytestrun.com@AD.INNERWEB.SCHEUBER.NAME -pass +rndPass -maxPass 256 -mapuser firstname.lastname@example.org -ptype KRB5_NT_PRINCIPAL -kvno 0 Targeting domain controller: WIN-DSB3AJ73MFU.ad.innerweb.scheuber.name Successfully mapped HTTP/idp37.mytestrun.com to am. Password successfully set! Key created. Output keytab to idp37_2.keytab: Keytab version: 0x502 keysize 85 HTTP/idp37.mytestrun.com@AD.INNERWEB.SCHEUBER.NAME ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x17 (RC4-HMAC) ke ylength 16 (0x848b2f5caa674cc0e30ab8ba22efd14f)
ktpass command, your user's account information will have changed:
Now move or copy the generated keytab file to the AM server. You will need to reference it by its full name and path in the node settings.
The following configuration options showcase scenario #3 from above: Multiple Active Directory Domains
Without Domain Trusts / Multiple Kerberos Realms
Without Cross-Realm Secrets.
- Kerberos relies on DNS for entity resolution. All records for servers involved in the flow must be A records, not CNAME records.
- You may see the below errors in the AM log files:
ERROR: Exception thrown trying to authenticate the user GSSException: Failure unspecified at GSS-API level (Mechanism level: Invalid argument (400) - Cannot find key of appropriate type to decrypt AP REP - RC4 with HMAC)
One potential fix to this issue is to regenerate the AM service keytab file without the
-crypto AES256-SHA1. The keytab command would then be:
ktpass -out fileName.keytab -princ HTTP/openam.forgerock.com@AD_DOMAIN.COM -pass +rdnPass -maxPass 256 -mapuser amKerberos@frdpcloud.com -ptype KRB5_NT_PRINCIPAL -kvno 0