Deploying Keycloak IdP with AD FS

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

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.

Enable the Keycloak Identity Provider role

Configure Keycloak as an Identity Provider within AD FS

Configure the AD FS Client (Service Provider) within Keycloak

Enabling the Keycloak Identity Provider Role

1. Open the administrative console for your Keycloak environment.
2. It is important to 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.
3. Once you have accessed the Keycloak Realm, make note of the Realm Name. In the example, it is Example. This is a case-sensitive value.
4. Click on the Identity Providers section of the left navigation bar.

5. You will see a drop-down menu to select an Identity Provider type. Select SAML v2.0.

📘

Each realm can only act using one type of Identity Provider. To also configure service provider applications with Open ID Connect (OIDC), this would require another Realm.

6. When you have selected SAML v2.0, a configuration menu will open. Make the changes depicted in the table below.

7. Select Save at the bottom of the page.

Keycloak is now configured as a SAML 2.0 Identity Provider.

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

From this metadata you must extract the IdP signing certificate. Copy the dsig:X509Certificate certificate value to a text editor of your choice. The document will need to consist of the following lines:

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

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

Configure Keycloak As an Identity Provider for AD FS

Ensure 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.
2. Select Add Claim Provider Trust. The Add Claim Provider Trust Wizard will open.

2. Select Start.

3. Select the option to Enter claim provider trust data manually and click Next.

4. You must 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. Click Next.

5. Select the AD FS profile option. Click Next.

6. Check the check box to Enable support for the SAML 2.0 WebSSO protocol.
   You must input the SSO Service URL for your Keycloak Realm. It will follow the following format:

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

Click Next.

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

https://{KeycloakURL}/auth/realms/{RealmName}

Click Next.

8. Click Add and navigate to the path of the certificate. Click Next.

9. No configuration is required on this screen. Click Next to continue.

10. Keep the Open the Edit Claim Rules... checkbox checked. Click Close.

11. A new window will open to Edit Claim Rules for... the new Claim Provider Trust. This example adds a simple rule which is broadly applicable. Advanced configuration of these rules may be required based on the relying parties connected to AD FS. Click Add Rule.

12. In the drop-down, choose Pass Through or Filter an Incoming Claim. Click Next.

13. Input the following settings for this new rule:

14. The new claim rule will appear in the main pane. Click OK to finish the process.

Configure the AD FS Client (SP) within Keycloak

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 Clients on the left navigation menu.

2. Click Create at the top right.

3. Choose the option to Import the client metadata; navigate to and choose the AD FS metadata that was previously downloaded. Once this has been uploaded the Client ID will auto-populate. Click Save.

4. Make the following changes to the Client settings:

The client configuration is now completed. Test the configuration at the following URL on your AD FS server:

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

Sign in to this site; additional configuration may be required for each relying party. You will see the Claim Provider Trust configured for your Keycloak.

🚧

REQUIRED

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

📘

Certificates and Workforce Access Client for macOS

The Test of User Presence (TUP) is disabled when using certificate-based authentication on macOS devices.

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. Open Claim Provider Trust Properties, and navigate to the Certificate tab.
2. Choose the signing certificate for Keycloak and select View.

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

The new certificate appears in the Certification Path tab main pane.

4. Select Local Machine. Click Next.

5. Choose the location to install this certificate and select Trusted Root Certification Authorities. Click OK, then Next.

6. 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. Run the following command with the proper name for your Claim Provider Trust:

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