Skip to content

Configuring AD FS as IDP in Keycloak

Configuring the Keycloak Server for TLS

  1. Set the Keycloak HTTPS port to 443.

  2. 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 Configuring the Keycloak Truststore.

Configuring the Identity Provider in Keycloak

Configuring Basic Properties of the Identity Provider

  1. Open the Keycloak Web interface.

  2. Log on as administrator.

  3. 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.

  4. Scroll down to the bottom of the page.

  5. In SAML entity descriptor, enter the AD FS descriptor URL:

    https://<adfs_domainname>/FederationMetadata/2007-06/FederationMetadata.xml

  6. Click Show metadata and enable the following settings, if necessary:

    • Backchannel Logout
    • HTTP-POST Binding Response
    • HTTP-POST Binding for AuthnRequest
    • Validate Signature

  7. 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.

  8. 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.

  9. 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:

  1. For email use the mapper type Attribute Importer.

    Map the user attribute email to https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

  2. For username use the mapper type Username Template Importer.

    Map the user attribute username to ${ATTRIBUTE.https://schemas.microsoft.com/2012/12/certificatecontext/field/subjectname}.

  3. For surname use the mapper type Attribute Importer.

    Map the user attribute lastName to https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname.

  4. For given name use the mapper type Attribute Importer.

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

Obtaining Information for the AD FS Configuration

  1. 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.

  2. The URL is similar to this:

    https://<Keycloak domain name>/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

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

  2. Select Add Relying Party Trust.

    A wizard opens.

  3. Enter the SAML descriptor URL received in the previous step into the Federation metadata address field.

  4. Import the AD FS the settings.

  5. 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

  1. Open the Edit Claim Rules dialog.

  2. In the Add Transform Claim Rule dialog, select Transform an incoming claim.

  3. 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

  4. Click Finish to add the rule.

Rule for Mapping the Attributes of the Standard User

  1. Open the Edit Claim Rules dialog.

  2. In the Add Transform Claim Rule dialog, select Send LDAP attributes as Claims rule.

  3. 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

  4. 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

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

    Applications and Services Logs/AD FS/Admin

  2. For Keycloak, enable the tracing of the SAML processing by connecting to the running Keycloak instance:

    jboss-cli.sh

  3. 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.

Back to top