Connect Keycloak

Learn how to configure a connection to Keycloak via SAML

Introduction

Each SSO Identity Provider requires specific information to create and configure a new Connection. And often, the information required to create a Connection will differ by Identity Provider.

To create an Keycloak SAML Connection, you'll need three pieces of information: an ACS URL, an Identity Provider Issuer (also known as an Entity ID), and a Metadata URL.

WorkOS Provides

WorkOS provides the ACS URL and IdP URI (Entity ID). It's readily available in your Connection's Settings in the WorkOS Dashboard.

The ACS URL is the location an Identity Provider redirects its authentication response to. In Keycloak's case, it needs to be set by the Enterprise when configuring your application in their Keycloak instance.

Specifically, the ACS URL will need to be set as the "Client SAML Endpoint" in the SAML client setup in Keycloak.

The Entity ID is a URI used to identify the issuer of a SAML request, response, or assertion. In this case, the entity ID is used to communicate that WorkOS will be the party performing SAML requests to the Enterprise's Keycloak instance.

Specifically, the Entity ID will need to be set as the "Client ID" when creating a SAML client in Keycloak.

Overview

And then, you provide the Keycloak Metadata URL. Normally, the this will come from your Enterprise customer's IT Management team when they set up your application's SAML client in their Keycloak instance. But, should that not be the case during your setup, here's how to obtain it.

1

Log in

Log in to your Keycloak Admin Console, and navigate to the Realm you want to set up the SAML client in. Select "Clients" from the side menu. If your client is already created, select it from the list of and move to Step 5. If you haven't created a SAML client in Keycloak, select "Create".

2

Initial SAML Application Setup

On the Add Client setup step, input the IdP URI (Entity ID) from your WorkOS Dashboard as the "Client ID". Select saml as the "Client Protocol". Input the ACS URL from your WorkOS Dashboard as the "Client SAML Endpoint". Click "Save".

3

Configure SAML Application

On the Settings page, scroll down and make sure "Sign Assertions" is turned ON, and "Client Signature Required" is turned OFF.

Scroll down further on the Settings page, and input the ACS URL from your WorkOS Dashboard in the "Valid Redirect URIs" box. Click "Save".

4

Configure User Attributes and Claims

Click the "Mappers" top menu option. Select "Create".

You'll need to create a "User Property" mapper for the following four attributes:

  • id
  • email
  • firstName
  • lastName

This is an example of how to fill out the fields for id:

Also do this for the email, firstName, and lastName attributes:

5

Obtain Identity Provider Details

Select "Realm Settings" in the left sidebar navigation menu, and copy the "SAML 2.0 Identity Provider Metadata" link on the General page.

Next, within your connection settings, edit the Metadata Configuration and provide the Metadata URL you obtained from Keycloak. Your Connection will then be verified and good to go!