Hey everyone, In this blog we will see how you can configure Keycloak with SAML. Before we start, ensure you have deployed Keycloak, we will be self-hosting it on Elestio. Single Sign-On (SSO) is a feature for user experience and security by allowing users to authenticate once and gain access to multiple systems. SAML (Security Assertion Markup Language) is a widely used standard for implementing SSO.

Prerequisites

Before we start, make sure you have:

1. A deployed Keycloak service on Elestio.
2. A service provider (SP) ready for SAML integration

Create a Keycloak Client

First, we need to create a client in Keycloak that will act as the SAML resource server.

Gather SP Information:

To properly configure Keycloak as your Identity Provider (IdP), you need some critical information from your Service Provider (SP), such as the SP Entity ID and the Assertion Consumer Service (ACS) URL. These details identify your application within the SAML ecosystem, ensuring that authentication requests and responses are correctly routed.

Create the Keycloak Client:

1. Sign in to Keycloak: Open your web browser and navigate to the Keycloak administration console URL. Log in with your admin credentials.
2. Navigate to Clients: In the left-hand sidebar, click on "Clients" to view and manage Keycloak clients.
3. Create a New Client:
   • Click the "Create" button to start setting up a new client.
   • Client ID: Enter the SP Entity ID. This is a unique identifier for your application within the Keycloak realm.
   • Client Protocol: Choose "SAML" from the dropdown menu.
   • Client SAML Endpoint: Enter the ACS URL provided by your SP.
   • Click Save.

Configure Client Settings:

1. Client Signature Required: Set this to OFF. By disabling this, you are not requiring that SAML assertions be signed. This is useful for initial setups but can be changed later for added security.
2. Name ID Format: Choose a format that matches the expected format for usernames in your SP. Common formats include email or username.
3. Valid Redirect URIs: Enter your SP address with an asterisk appended (e.g., https://your-sp-domain/*). This wildcard allows for redirection to any sub-URL under the specified domain.
4. Click Save.
5. Client Scopes: Go to the "Client Scopes" tab, find role_list under Assigned Default Client Scopes, and click "Remove selected". This removes unnecessary role information from the SAML assertion, simplifying the setup.

Obtain Keycloak Metadata

The next step is to obtain the metadata from Keycloak to configure the SP. Metadata provides necessary configuration details like public keys, endpoints, and protocols, facilitating automatic setup and reducing manual errors.

Copy Metadata URL:

1. Sign in to Keycloak: Open your web browser and navigate to the Keycloak administration console URL. Log in with your admin credentials.
2. Navigate to Realm Settings: In the left-hand sidebar, click on "Realm Settings."
3. Access Metadata: Under the "General" tab, find and click on "SAML 2.0 Identity Provider Metadata" under Endpoints.
4. Copy URL: A new tab will open displaying the metadata. Copy the URL from this tab.

Download Metadata XML:

1. Sign in to Keycloak: Open your web browser and navigate to the Keycloak administration console URL. Log in with your admin credentials.
2. Select Your SAML Client: Click on "Clients" in the left-hand sidebar and select the SAML client you created.
3. Installation: Click on the "Installation" tab.
4. Select Format: Choose "Mod Auth Mellon files" from the Format Option dropdown. This format is commonly used for configuring SAML in various SPs.
5. Download XML: Click the "Download" button to save the XML file to your local machine.

Configure the Service Provider

Now, configure your SP with the metadata obtained from Keycloak. Metadata contains the necessary configuration details like public keys, endpoints, and protocols, facilitating automatic setup and reducing manual errors.

Using Metadata URL:

1. Sign in to SP Admin Interface: Open your web browser and navigate to your SP’s admin interface URL. Log in with your admin credentials.
2. Navigate to SAML Configuration: Go to the section where you configure SAML settings.
3. Enter Metadata URL: Look for an option to provide a metadata URL. Paste the Keycloak metadata URL into this field.
4. Fetch Details: Save the settings or click the appropriate button to fetch and populate the necessary SAML configuration details from Keycloak.

Using Metadata XML:

1. Sign in to SP Admin Interface: Open your web browser and navigate to your SP’s admin interface URL. Log in with your admin credentials.
2. Navigate to SAML Configuration: Go to the section where you configure SAML settings.
3. Upload XML File: Look for an option to upload a metadata file. Click "Choose File" or the equivalent button to select the XML file you downloaded from Keycloak.
4. Upload and Save: After selecting the file, upload it and save the settings. The SP should automatically configure the necessary SAML settings from the XML.

Enable SAML Authentication

Once the IdP (Keycloak) is configured in your SP, enable SAML authentication to allow users to log in using SAML.

Enable SAML:

1. Sign in to SP Admin Interface: Open your web browser and navigate to your SP’s admin interface URL. Log in with your admin credentials.
2. Navigate to Authentication Settings: Go to the section where you configure authentication methods (e.g., Authentication > SAML).
3. Enable SAML Authentication: Toggle on the setting for SAML authentication.
4. Save and Update: Save the settings and update the server or application to apply the changes.

Optional: Set Up IdP-Initiated Flow

To allow users to start their login process from Keycloak, you can set up an IdP-initiated flow. This allows users to begin the SSO process from the Keycloak login page.

1. Sign in to Keycloak: Open your web browser and navigate to the Keycloak administration console URL. Log in with your admin credentials.
2. Select Your SAML Client: Click on "Clients" in the left-hand sidebar and select the SAML client you created.
3. Configure IDP Initiated SSO URL Name:
   • Enter the SP Entity ID for the "IDP Initiated SSO URL Name." This allows Keycloak to initiate the login process for your SP.
4. Set IDP Initiated SSO Relay State:
   • For IDP Initiated SSO Relay State , you can direct users to specific pages after they sign in. Common options are:
   • cws to direct users to the Client Web UI.
   • profile to direct users to a profile download page.
5. Save Settings: Click Save to apply the changes.
6. Provide URL to Users: After setting up, Keycloak will display a Target IDP Initiated SSO URL. Copy this URL and provide it to your users for direct login access.

Conclusion

Setting up SAML with Keycloak involves configuring Keycloak as the Identity Provider and your application as the Service Provider. By following these steps, you can leverage Keycloak’s SAML capabilities for authentication across your applications, enhancing both security and user experience. This integration ensures that users have a login experience while maintaining security standards. Additionally, by enabling optional like IdP-initiated flow, you provide greater flexibility and convenience for your users.

Thanks for reading ❤️

Thank you so much for reading and do check out the Elestio resources and Official Keycloak documentation to learn more about Keycloak. Click the button below to create your service on Elestio. See you in the next one👋