Deploying Keycloak IdP with AD FS

Introduction

This guide shows how to configure Keycloak as an Identity Provider (IdP) with AD FS.

To begin, please ensure you have administrative access to both your Keycloak and AD FS environments. The following high-level milestones will be reached through the course of our deployment.

Overall Objectives:

1. Enable Keycloak Identity Provider Role

2. Configure Keycloak as an Identity Provider (IdP) within AD FS

3. Configure the AD FS Client (SP) within Keycloak

Enabling the Keycloak Identity Provider Role:

Start by accessing the administrative console for your Keycloak environment. Note that within your Keycloak deployment there are ‘realms’. Each realm will have a unique Federation / SAML configuration. Select the realm of your choice for this integration.

1. Once you have accessed the Keycloak Realm of your choice, you will need to do two things. First take note of the realm name as listed in the Name setting, in the example it is Example. This is a case-sensitive value. Click on the Identity Providers section of the navigation bar.

🚧

It is critical you keep in mind that the Realm Name is case-sensitive and must be taken from the Name setting as shown in the screenshot above. This value will be used in multiple URLs and is case-sensitive in these URLs too.

2. You will see a drop-down menu to select an IdP type. In this configuration, you will want to select SAML v2.0.

📘

You will notice that each realm can only be for a single Identity Provider. As an example, should you want to also configure SP applications with OpenID Connect (OIDC), this would require another realm.

3. When you have selected SAML v2.0, a configuration menu will open. There are three changes you will need to make at this point, as depicted in the image below.

After making these setting changes, select Save at the bottom of the page.

4. Keycloak is now configured as a SAML 2.0 Identity Provider. You’ll now need to download the Identity Provider Metadata for the next configuration steps.

This metadata can be found at the following URL:

https://{KeycloakURL}/auth/realms/{RealmName}/protocol/saml/descriptor

Within this metadata you will need to extract the IdP signing certificate. Copy the dsig:X509Certificate certificate value to any text editor. The document will need to consist of three lines as follows:

-----BEGIN CERTIFICATE-----
{Certificate Value}
-----END CERTIFICATE-----

Save this value as a .crt file, for example: example_idp.crt

Configure Keycloak as an IdP for AD FS:

Start by ensuring you have an RDP session with the Windows Server that has AD FS installed. We will be using the AD FS administration console to make the changes required.

1. From the AD FS administration console, navigate to the Claim Provider Trusts. Select the option from this window to Add Claim Provider Trust.

2. A configuration wizard for adding a Claim Provider Trust will open. Select Start to continue the process.

3. Select the option to Enter claim provider trust manually and select next.

4. You will need to input a Display Name for the new Claim Provider Trust. This is a friendly name that will be displayed to administrators in the AD FS console and to end users if IdP Selection is utilized. Select Next to Continue.

5. Select the AD FS profile option and Select Next to Continue.

6. Select the check box to Enable support for the SAML 2.0 WebSSO protocol.

You will need to input the SSO Service URL for your Keycloak realm. It will follow the following format:

https://{KeycloakURL}/auth/realms/{RealmName}/protocol/saml
Select Next to Continue.

7. Next you will need to provide the Claim provider trust identifier. This is your SAML Issuer value for the Keycloak IdP. It will follow this format:

https://{KeycloakURL}/auth/realms/{RealmName}
Select Next to Continue.

8. You will next need to upload your IdP Certificate, which was extracted in the Keycloak IdP setup. Select the Add button and navigate to the path of the certificate.

Select Next to Continue.

9. No configuration is required on this screen. Select Next to Continue.

10. Keep the Open the Edit Claim Rules checkbox checked. Select Close to continue.

11. A new window will open to add a claim rule for the new Claim Provider Trust. In this guide, we will add a simple rule which is broadly applicable. Advanced configuration of these rules may be required based on the relying parties connected to AD FS.

Select Add Rule to continue.

12. With the drop-down selection, choose Pass Through or Filter an Incoming Claim.

Select Next to continue.

13. You will need to input the following settings for this new rule.

14. The new claim rule will appear in the windows. Select OK to finish this process.

Configure the AD FS Client (SP) within Keycloak

To start the client configuration, you will want to download the metadata for your AD FS environment. This metadata is published on your AD FS server at the following URL:

https://{ADFS_URL}/FederationMetadata/2007-06/FederationMetadata.xml
Once you have this metadata downloaded, navigate to the administrative console for your Keycloak realm.

1. Select the Clients settings from the lefthand navigation menu. From this menu select the Create option at the top right.

2. Choose the option to Import the client metadata. Navigate to the AD FS metadata that was previously downloaded. Once this has been uploaded, the Client ID will populate. Select Save to continue.

3. Once these settings are saved the client settings will appear. You will need to make the following changes to complete the configuration.

5. The client configuration is now complete. You can test the configuration at the following URL on your AD FS server:

https://{ADFS_URL}/adfs/ls/IdpInitiatedSignOn.aspx

Select the option to Sign in to this site, as additional configuration is required for each relying party. You will see the Claim Provider Trust configured for your Keycloak.

🚧

Claim Rules are required for each Relying Party to utilize the new Claim Provider Trust. Please work with a HYPR engineer to get configuration for each of these.

Troubleshooting AD FS

All of the logs for AD FS can be found within Event Viewer. The logs reside at the following path:

Applications and Services Logs/AD FS/Admin

Error 303 - ID4037

This error indicates there are trust issues with the Signing Certificate utilized by the Keycloak IdP. There are two processes you can follow to establish trust for the signing certificate.

Establish Trust for the Signing Certificate -

1. In the settings for your Claim Provider Trust, navigate to the Certificate settings. Choose the signing certificate for Keycloak and select view.

2. If you are using the default, self-signed certificate from Keycloak, this will be an untrusted certificate. You can install this certificate to the local machine of the Windows Server to establish trust. Select Install Certificate.

3. Select the option for Local Machine.

4. Choose the location to install this certificate and select the Trusted Root Certification Authorities. Select OK and Next to continue.

5. Select Finish. The certificate is now trusted by the AD FS server.

Disable the Revocation Check Specifically for a Signing Certificate -

You can also disable the revocation check for the signing certificate. This requires you to launch Powershell as an administrator. Within Powershell run the following command with the proper name for your Claim Provider Trust.

Set-AdfsClaimsProviderTrust –TargetName “{Claim Provider Trust Name}” –SigningCertificateRevocationCheck “None”