How to configure SAML with Keycloak

Upgrade to Latest Version

Introduction

OpenVPN 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 how to enable SAML authentication for users and groups from Keycloak to Access Server.

Before you begin

You need the following to get started:

Note: We recommend using all lowercase usernames when logging in with SAML.

Step 1: Create the Keycloak Client

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

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

  1. Sign in to your Access Server Admin Web UI.
  2. Click Authentication > SAML.
  3. You’ll need the following information:
    • SP Identity.
    • 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.
  3. Enter your SP information as follows:
    • Client ID: Enter the SP Identity from Access Server.
    • Client Protocol: Choose saml.
    • Client SAML Endpoint: Enter the SP ACS from Access Server.
  4. Click Save.
  5. After saving, make the following changes in the Settings:
    • Set Client Signature Required to OFF.
    • Select the Name ID Format that matches your Access Server usernames.
    • Enter your Access Server address, with an * appended, as the Valid Redirect URIs and click the + sign. (For example, enter https://164.234.23.23/*.)
  6. Click Save.
  7. Click the Client Scopes tab.
  8. Click role_list under Assigned Default Client Scopes and click Remove selected.

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 by providing metadata to Access Server. You can copy a metadata URL or download an XML file.

To copy the Keycloak metadata URL (option 1):

  1. Sign in to your Keycloak administration console.
  2. Under Real Settings and General, click SAML 2.0 Identity Provider Metadata under Endpoints.
  3. Copy the URL for the newly opened tab.

To download the Keycloak metadata XML (option 2):

  1. Sign in to your Keycloak administration console.
  2. Click Clients and select your SAML client.
  3. Click Installation.
  4. Select Mod Auth Mellon files from the Format Option dropdown.
  5. Click Download.

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.

To paste the Keycloak metadata URL in the Admin Web UI (option 1):

  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 and click Get and Update Running Server.
  5. The IdP fields are now populated under Configure Identity Provider (IdP) Manually.

To upload the Keycloak metadata XML in the Admin Web UI (option 2):

  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.
  5. The IdP fields are now populated under Configure Identity Provider (IdP) Manually.

After saving, you should see the following data populated automatically by either the URL or the XML file:

  • IdP EntityId.
  • Sign On Endpoint.
  • Certificate (PEM format).

Step 4: Assign SAML as user authentication

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

  1. Sign in to the Admin Web UI.
  2. Click Authentication > SAML.
  3. Click the toggle to turn on Enable SAML authentication, then click Save Settings and Update Running Server.
  4. You can now enable SAML as the global default authentication or for specific groups and users.

How to set up IdP-initiated flow (optional)

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 and select your SAML client.
  3. For the IDP Initiated SSO URL Name enter the Access Server SP Identity.
  4. Enter one of the following into IDP initiated SSO Relay State:
    • cws: This directs your users to the Client Web UI after sign-in.
    • profile: This directs your users to a profile download after sign-in.
  5. Click Save.
  6. Copy the Target IDP Initiated SSO URL (this displays below the IDP Initiated SSO URL Name after you populate the field) and provide it to users for signing in.