Tutorial: How to Configure SAML with Keycloak⁠

You need the following to get started:

• A deployed Keycloak server.

• A deployed  Access Server.

With Keycloak, you need to create a client application to serve as your SAML resource server.

First, gather information about your Access Server as the service provider (SP).

1. Sign in to your Access Server Admin Web UI.

2. Select Authentication → SAML.

3. You'll need the following information:

   1. SP Identity.

   2. SP ACS.

Now that you have your SP information, you can create a new Keycloak client and enter that information during client creation:

1. Sign in to your Keycloak administration console.

2. Click Clients > Create client.

3. Start the configuration of your Client:

   1. Client type: Select SAML.

   2. Client ID: Enter the SP Identity from Access Server.

   3. Name: Enter a client name (for example, "openvpnas-saml"). We recommend all lowercase for the client name.

4. Click Next, and make the following changes:

   1. Valid redirect URIs: Enter your Access Server address, with an * appended (for example, https://203.0.113.5/*).

   2. Master SAML Processing URL: Enter the SP ACS from Access Server.

   3. Leave the remaining fields empty (default).

5. Click Save.

6. Navigate to Settings > SAML capabilities > Name ID format.

7. Select a format that matches your Access Server usernames (for example, username or email).

8. Click Save.

9. Navigate to Keys > Signing keys config.

10. Set Client signature required to Off.

11. Navigate to the Client Scopes tab.

12. Select role_list, click the 3 dots, click Remove, and click Delete.

    • You’ve added the SAML client for your Keycloak server.

The simplest way to set up Keycloak SAML for Access Server is to provide metadata. You can copy a metadata URL or download an XML file.

Now that you have the metadata, you can provide that to your Access Server through the Admin Web UI to automatically configure SAML.

If you copied the URL, follow the steps below to paste it into the SAML page for Access Server. If you downloaded the XML file, follow the steps below to upload it to the SAML page for Access Server.

Once you’ve provided the SAML configuration for your IdP, you can enable it for users.

1. Sign in to the Admin Web UI.

2. Select Authentication → SAML.

3. Select the toggle to turn on Enable SAML authentication.

4. Select Save Settings and Update Running Server.

You can now enable SAML as the global default authentication or for specific groups and users.

You can configure an IdP-initiated flow for signing into Access Server from Keycloak with the following steps:

1. Sign in to your Keycloak administration console.

2. Click Clients, then select your SAML client.

3. In the IDP-Initiated SSO URL name field, enter a name. This will be part of the URL used for the IdP-initiated flow. We recommend using an all lowercase name here. In this example, we use the client name, openvpnas-saml.

   • This value becomes part of the IdP-initiated SSO URL.

   • We recommend using a lowercase name.

   • Example: openvpnas-saml

4. In IDP-initiated SSO Relay State, enter one of the following:

   • cws: This directs your users to the Client Web UI after sign-in.

   • profile: This directs your users to download a connection profile.

5. Click Save.

   • After saving, Keycloak generates the IdP-initiated SSO URL.

   • The URL follows this format:

     https://<keycloak-server-domain>/realms/<realm>/protocol/saml/clients/<idp-initiated-sso-url-name>

     Where:

     • <keycloak-server-domain> — the IP address or domain of your Keycloak server.

     • <realm> — the Keycloak realm name.

     • <idp-initiated-sso-url-name> — the value set in IDP-initiated SSO URL Name.

     Example:

     https://keycloak-example.com/realms/master/protocol/saml/clients/openvpnas-saml

6. Provide this URL to users so they can sign in using the IdP-initiated flow.

Instead of sharing the URL manually, you can configure Keycloak so users can launch the application directly from the Keycloak UI.

1. Sign in to your Keycloak administration console.

2. Click Clients, then select your SAML client.

3. In the Home URL field, paste the IDP-Initiated SSO URL.

4. Click Save.

Users will now see the application in the Keycloak user portal and can click it to sign in using the IdP-initiated flow.

You can automate group assignments for access control rules using a post-authentication Python script.

Refer to the steps in this tutorial:

• Tutorial: How to Set Up SAML Group Mapping with a Post-Auth Script