Connect Keycloak
Learn how to configure a connection to Keycloak via SAML
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 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.
Click the "Mappers" top menu option. Select "Create".
You'll need to create a "User Property" mapper for the following four attributes:
- id
- 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:
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!