March 23 2017 by Hynek Mlnařík
This document guides you through initial setup of Microsoft Active Directory Federation Services 3.0 as a brokered identity provider Keycloak.
Keycloak server has configured for SSL/TLS transport - this is mandatory for AD FS to communicate with it. This comprises two steps:
In the Identity Providers, create a new SAML v2.0 identity provider. In this post, the identity provider will be known under alias adfs-idp-alias.
Now scroll to the bottom and enter the AD FS descriptor URL into Import from URL field. For AD FS 3.0, this URL is https://fs.domain.name/FederationMetadata/2007-06/FederationMetadata.xml. Once you click “Import”, check the settings. Usually, you would at least enable Validate signature option.
If the authentication requests sent to the AD FS instance are expected to be signed, which is also usually the case, you have to enable Want AuthnRequests Signed option. Importantly, then the SAML Signature Key Name field that shows after enabling the Want AuthnRequests Signed option has to be set to CERT_SUBJECT as AD FS expects the signing key name hint to be the subject of the signing certificate.
The AD FS will be set up in the next step to respond with name ID in Windows Domain Qualified Name format, hence set the NameID Policy Format field accordingly.
In the steps setting AD FS below, AD FS will be set up to send email and group information in SAML assertion. To transform these details from SAML document issued by AD FS to Keycloak user store, we’ll need to set up two corresponding mappers in the Mappers tab of Identity Provider:
Now we determine SAML service provider descriptor URI that will be used in AD FS setup from the Redirect URI field in the identity provider detail by adding “/descriptor” to the URI in this field. The URI will be similar to https://kc.domain.name:8443/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor. You can check whether you got the URI right by entering the URI into the browser - you should receive a SAML service provider XML descriptor.
In AD FS Management console, right-click Trust relationships → Relying Party Trusts and select Add Relying Party Trust from the menu:
At the beginning of the wizard, enter the SAML descriptor URL obtained in the previous step into the Federation metadata address field, and let AD FS import the settings. Proceed with the wizard, and adjust the settings where appropriate. Here we use only the default settings. Note that you will need to edit the claim rules so when asked to do so at the last page of the wizard, you can leave the checkbox checked on.
Now the SAML protocol would proceed correctly, AD FS would be able to correctly authenticate the users according to requests from Keycloak, but the requested name ID format is not yet recognized and SAML response would not contain any additional information like e-mail. It is hence necessary to map claims from AD user details into SAML document.
We will set up three rules: one for mapping user ID, second for mapping standard user attributes, and third for a user group. All start by clicking the Add Rule button in the Edit Claim Rules for kc.domain.name window:
The first rule will map user ID in Windows Qualified Domain name to the SAML response. In the Add Transform Claim Rule window, select Transform an incoming claim rule type:
The example above targets windows account name ID format. Other name ID formats are supported but out of scope of this post. See e.g. this blog on how to setup name IDs for persistent and transient formats.
The second rule will map user e-mail to the SAML response. In the Add Transform Claim Rule window, select Send LDAP attributes as Claims rule type. You can add other attributes as needed:
The third rule would send a group name if the user is member of a named group. Start again in the Add Transform Claim Rule window, and select Send Group Membership as a Claim rule type. Then enter the requested values in the field:
This setup would send an attribute named Group in the SAML assertion with value managers if the authenticated user is member of the DOMAIN\Managers group.
As a first-hand tool, you should check SAML messages sent back and forth between Keycloak and AD FS in your browser. The SAML decoders are available as browser extensions (e.g. SAML Tracer for Firefox, SAML Chrome Panel for Chrome). From the captured communication, you might see error status codes as well as the actual attribute names and values in SAML assertion necessary for setting up mappers. For example, if name ID format is not recognized, AD FS would return a SAML response containing urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy status code.
As a second resort, check the logs. For AD FS, the logs are available in the Event viewer under Applications and Services Logs → AD FS → Admin. In Keycloak, you can enable tracing of the SAML processing by connecting to the running Keycloak instance via jboss-cli.sh and entering the following commands:
Then you will be able to find the SAML messages and broker-related SAML processing messages in the Keycloak server log.
If you get stuck, do not hesitate to write a question to Keycloak user forum mailing list.
As there is always room for improvement, if you find any issue or have any suggestion on this text, feel free to leave a comment!