Configuring AD FS as IDP in Keycloak¶

Configuring the Keycloak Server for TLS¶

Set the Keycloak HTTPS port to 443.
In order to enable outgoing HTTPS connections, export the AD FS certificate to a Java truststore:
1. In the AD FS management console, go to Service/Certificates node and export the service communications certificate.
2. Import the certificate into a Java truststore (JKS format) using the Java keytool utility.
3. Setup the truststore in Keycloak as described in Keycloak Server Installation.

Configuring the Identity Provider in Keycloak¶

Configuring Basic Properties of the Identity Provider¶

Open the Keycloak Web interface.
Log on as administrator.
Click Identity Providers and add a new SAML v.2.0 provider.

Hint - memorize the alias

Memorize the provider alias you entered, as you will need it later.
Scroll down to the bottom of the page.
In Import from URL, enter the AD FS descriptor URL:

https://<adfs_domainname>/FederationMetadata/2007-06/FederationMetadata.xml
Click Import and enable the following settings, if necessary:
- Backchannel Logout
- HTTP-POST Binding Response
- HTTP-POST Binding for AuthnRequest
- Validate Signature
If the authentication requests sent to the AD FS instance are expected to be signed, enable the Want AuthnRequests Signed option.

Then the SAML Signature Key Name field is displayed.
Set the SAML Signature Key Name field option to CERT_SUBJECT.

AD FS expects the signing key name hint to be the subject of the signing certificate.
If the AD FS is set up to respond with name ID in the Windows Domain Qualified Name format, set the NameID Policy Format field accordingly.

Configuring Mappers¶

AD FS sends e-mail data in SAML assertion.

Set up mappers in the Mappers tab of the identity provider to transform these and other details from a SAML document issued to the Keycloak user store by AD FS:

For email use the mapper type Attribute Importer.

Map the user attribute email to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
For username use the mapper type Username Template Importer.

Map the user attribute username to ${ATTRIBUTE.http://schemas.microsoft.com/2012/12/certificatecontext/field/subjectname}.
For surname use the mapper type Attribute Importer.

Map the user attribute lastName to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname.
For given name use the mapper type Attribute Importer.

Map the user attribute firstName to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname.

Obtaining Information for the AD FS Configuration¶

Specify the SAML service provider descriptor URL that is used in the AD FS setup in the Redirect URI field in the identity provider by adding /descriptor to the URL in this field.
The URL is similar to this:

https://<Keycloak domain name>/auth/realms/master/broker/<identity provider alias>/endpoint/descriptor

Hint - URL check
Check the naming of the URL by entering it in the browser. As a result, you should receive a SAML service provider XML descriptor.

Configuring the Relying Party Trust in AD FS¶

Configuring the Relying Party¶

In the AD FS management console, click Trust relationships/Relying Party Trusts.
Select Add Relying Party Trust.

A wizard opens.
Enter the SAML descriptor URL received in the previous step into the Federation metadata address field.
Import the AD FS the settings.
Proceed with the wizard and adjust the settings according to your needs.

Hint - further settings

Use only the default settings. You have to edit the claim rules. Leave the checkbox of the last page of the wizard marked.

Configuring the Claim Mapping¶

After the previous steps The SAML protocol is ready to work correctly and AD FS is 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.

Therefore you have to map claims from the AD user details into the SAML document.

You need to set up two rules:

for mapping the user ID and
for mapping the standard user attributes.

Start by clicking the Add Rule button in the Edit Claim Rules dialog and proceed als described below.

Rule for Mapping the `user ID`¶

Open the Edit Claim Rules dialog.
In the Add Transform Claim Rule dialog, select Transform an incoming claim.
Map the following attributes:
- Name ID as rule name
- Windows account name for the property Incoming claim type
- Name ID for the property Outgoing claim type
- Windows qualified Domain Name for the property Outgoing name ID format
Click Finish to add the rule.

Rule for Mapping the Attributes of the Standard User¶

Open the Edit Claim Rules dialog.
In the Add Transform Claim Rule dialog, select Send LDAP attributes as Claims rule.
Map the following attributes:
- E-Mail-Addresses to E-Mail Address
- SAM-Account-Name to Subject Name
- Your LDAP attributes for surname and given name
Add further attributes, if needed.

Trouble-Shooting¶

Checking the Communication between Keycloak and AD FS¶

In your Web browser, check, whether SAML messages are sent bidirectionally between Keycloak and AD FS and capture the communication messages.

In the captured communication, you will see the error status codes and the actual attribute names and values which are necessary to set up mappers in SAML assertion.

Hint - SAML decoders

The SAML decoders are available as browser extensions (e. g. SAML Tracer for Firefox, SAML Chrome Panel for Google Chrome).

Example - unrecognized name ID format

If the name ID format is not yet registered, AD FS returns a SAML response containing the urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy status code.

Checking the Log Files¶

The AD FS log files are available in the event viewer:

Applications and Services Logs/AD FS/Admin
For Keycloak, enable the tracing of the SAML processing by connecting to the running Keycloak instance:

jboss-cli.sh

Enter the following commands:

 /subsystem=logging/logger=org.keycloak.saml:add(level=DEBUG)
 /subsystem=logging/logger=org.keycloak.broker.saml:add(level=DEBUG)

SAML messages and broker-related SAML processing messages are displayed in the Keycloak server log.

Literature - SEAL Print Client Knowledge Base

For further information and trouble-shooting, refer to SEAL Print Client Knowledge Base.