--- title: 'Tutorial: How to Configure SAML with Keycloak' canonical: https://openvpn.net/as-docs/tutorials/saml-keycloak/ product: Access Server Docs description: This is a step-by-step guide for configuring SAML on Access Server with Keycloak. --- # Tutorial: How to Configure SAML with Keycloak ## Overview Access Server 2.11 and newer supports authentication using SAML with Keycloak as the identity provider. You can configure this in Keycloak with Access Server as your service provider. The following steps walk you through enabling SAML authentication for users and groups from Keycloak to Access Server. ## Prerequisites You need the following to get started: - A deployed [Keycloak server](https://www.keycloak.org/downloads.html). > **Note** > > At the time of writing this tutorial, the KeyCloak version used and tested was 26.5.x. - A deployed  [Access Server](https://openvpn.net/quick-start-guide/). > **Important** > > We recommend using all lowercase usernames when signing in with SAML. > **Note** > > In our documentation, we use example IPv4 addresses and subnets [reserved for documentation](https://en.wikipedia.org/wiki/Reserved_IP_addresses#IPv4), such as `192.0.2.0/24`, `198.51.100.0/24`, and `203.0.113.0/24`. > > Ensure you replace them with valid IPv4 addresses and subnets for your network(s). ## Step 1: Create the Keycloak Client 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. ## Step 2: Copy or download the Keycloak metadata 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. ### Option 1: Copy the Keycloak metadata URL 1. Sign in to your Keycloak administration console. 2. Under **Realm Settings \> General \> Endpoints:** Click **SAML 2.0 Identity Provider Metadata**. (This opens a new tab.) 3. Copy the URL for the newly opened tab. ### Option 2: Download the Keycloak metadata XML 1. Sign in to your Keycloak administration console. 2. Click **Clients** and select your SAML client. 3. Click **Action \> Download adapter config**. 4. Select **mod-auth-mellon** from the **Format Option** dropdown. - The zip file `keycloak-mod-auth-mellon-sp-config.zip` downloads. 5. Extract the ZIP file and you'll see a directory called `https___203.0.113.5_saml_metadata` (where `203.0.113.5` is your Access Server address). 6. Inside that directory are two files: - idp-metadata.xml - sp-metadata.xml 7. Use the `idp-metadata.xml` if you're uploading Keycloak metadata XML in the Admin Web UI. ## Step 3: Provide metadata to Access Server 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. ### Option 1: Paste the Keycloak metadata URL in the Admin Web UI 1. Sign in to your Access Server Admin Web UI. 2. Click **Authentication \> SAML**. 3. Click **Configure Identity Provider (IdP) Automatically via Metadata** to expand the section. 4. Paste the metadata URL from Keycloak into the **IdP Metadata URL** field, click **Get**, and click **Update Running Server**. - The IdP fields are now populated under **Configure Identity Provider (IdP) Manually**. ### Option 2: Upload the Keycloak metadata XML in the Admin Web UI 1. Sign in to your Access Server Admin Web UI. 2. Click **Authentication \> SAML**. 3. Click **Configure Identity Provider (IdP) Automatically via Metadata** to expand the section. 4. In the field **Select IdP Metadata**, click **Choose File** to upload the XML file you downloaded from Keycloak, then click **Upload** and **Update Running Server**. - The IdP fields are now populated under **Configure Identity Provider (IdP) Manually**. The IdP fields are now populated under Configure Identity Provider (IdP) Manually. - IdP EntityId. - Sign On Endpoint. - Certificate (PEM format). ## Step 4: Assign SAML as user authentication 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](https://openvpn.net/as-docs/tutorials/saml-default-auth.md) or for [specific groups and users](https://openvpn.net/as-docs/tutorials/saml-users-groups.md). ## Optional: How to set up IdP-initiated flow 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:///realms//protocol/saml/clients/ ``` Where: - `` — the IP address or domain of your Keycloak server. - `` — the Keycloak realm 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. ## Optional: Map group access control 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](https://openvpn.net/as-docs/tutorials/tutorial--post-auth-saml-group-mapping.md) --- Prev: [Tutorial: How to Configure SAML with OneLogin](https://openvpn.net/as-docs/tutorials/saml-onelogin.md) Next: [Tutorial: How to Configure SAML with Okta](https://openvpn.net/as-docs/tutorials/saml-okta.md) Index: https://openvpn.net/as-docs/llms.txt