SAML setup with Keycloak

This document provides you with the steps for configuring an OpenVPN Cloud instance to use Keycloak as the SAML identity provider (IdP).

Steps: Retrieve certificate value and IdP endpoint from Keycloak

  1. Navigate to Keycloak and sign in with your administrator account.
  2. Access Realm Settings > Endpoints and click SAML 2.0 Identity Provider Metadata.
  1. Copy the IdP X.509 Public Certificate and the IdP Authentication Endpoint URL, which are used later in the OpenVPN Cloud setup process.

Steps: Configure and enable SAML in OpenVPN Cloud

  1. Sign in to the OpenVPN Cloud administration portal at https://cloud.openvpn.com/.
  2. Access Settings > User Authentication and click Edit.
  1. Click on Configure in the Authenticate Users Using > SAML section.
  • The SAML Configuration window opens. Click Next.
  1. Add your IdP Name (optional), and then select Manual Configuration.
  2. Paste the previously copied IdP Authentication Endpoint URL and the IdP X.509 Public Certificate.
  1. Click Next, review the displayed information, then click Finish.
  • You now have the option to use SAML to authenticate users.

Steps: Create a new Keycloak client

  1. Navigate to Keycloak and sign in as an administrator.
  2. Access Clients and click Create.
  1. Set the Client ID to be the same as the Issuer Name that was displayed in the SAML configuration on the OpenVPN Cloud portal:
  1. Select SAML as the Client Protocol.
  2. Enter the SSO URL for the Client SAML Endpoint:

6. Click Save.

  • The settings tab displays the default values.

7. Enable Sign Assertions.

8. Disable Client Signature Required and Force POST Binding.

9.Set Name ID format to email.

10. Enter this value in Valid Redirect URIs, which allows redirects to the ACS URL:

  • All other values are left as default.

Steps: Create a Keycloak user account

  1. Navigate to Keycloak, access Users, and click Add User.
  2. Fill out the form with your data.
    • Note that you can select Email Verified if you use a test email that doesn’t allow verification.
  1. Open the Credentials tab and assign a password for the user account, and click Set Password.

Steps: Sign in to your CloudVPN domain with Keycloak

  1. Navigate to the OpenVPN account page at: https://myaccount.openvpn.com/login
  2. Click Not an Owner? Sign In Here.
    • OpenVPN Cloud recognizes that your domain uses SAML and displays the Single Sign On prompt.
  1. Click Sign In.
    • The Keycloak Log In page opens.
  2. Enter the Keycloak test account email and password and click Log In.
    • The OpenVPN Cloud Get Connected page opens with app download and installation instructions.

Steps: Configure attributes and group mapping in Keycloak

  1. Navigate to Keycloak, access Clients, and click on your Client ID.
  2. Click on the Mappers tab, which allows you to create SAML attributes.
    • Note: At the time of publication, OpenVPN Cloud only supports First Name, Last Name, Email, and Groups for mapping attributes.
  3. Click Create, and in Mapper Type select User Property.
  4. Add a separate attribute entry for each of First Name, Last Name, and Email.

Note: You must use these defined Property name values in the Property field.

AttributePropertyPurpose
EmailemailTo pass the email value to the service provider.
First NamefirstNameTo pass the first name value to the service provider.
Last NamelastNameTo pass the last name value to the service provider.
  1. Set the SAML Attribute Name value to be the same as each corresponding Property name value.
  2. Click Create, and in Mapper Type select Group List to create a Group Mapper.

Note: You must use groups as the defined Group attribute name.

AttributeGroup attribute namePurpose
GroupgroupsTo pass the groups value to the service provider.

Steps: Configure attribute mapping in OpenVPN Cloud

To finalize your attribute mapping setup, you must ensure that the Property values and SAML Attribute values match the Attribute Mapping values in your SAML Configuration on OpenVPN Cloud.

  1. Access OpenVPN Cloud > Settings > User Authentication > SAML > View Attribute Mapping to check that those values match:

Steps: Set up group mapping in OpenVPN Cloud

  1. Access OpenVPN Cloud Settings > User Authentication > SAML > View Group Mapping and click Add Rule.
  2. Enter the name of the group(s) from your identity provider under SAML IdP User Group(s) and then select a group from the OpenVPN Cloud User Groups that you want to map to your IdP group(s).

Steps: Set up identity provider initiated flow

There are two ways to enable SAML authentication to an application: service provider initiated flow (SP-initiated) and identity provider initiated flow (IdP-initiated). The SP-initiated flow is considered more secure.

For the SP-initiated flow, a user navigates to a tenant URL that leads them to a SAML login page. During the IdP-initiated flow, a user opens their account on the IdP portal and they sign in to any of their assigned apps from that portal. Open VPN doesn’t support the classic IdP-initiated flow out of the box because of the lack of security. However, we do provide a workaround for those administrators who use IdP-initiated SAML authentication.

In brief, we need to retrieve the RelayState value from the SAML request/response and paste this value into the corresponding field on the IdP.

  1. Sign in to the app using SP-initiated flow through the direct Open VPN ID URL e.g. https://keycloak-saml.openvpn-qa.com with opened SAML extension (extension that can be downloaded from Chrome Web Store https://chrome.google.com/webstore/detail/saml-devtools-extension/jndllhgbinhiiddokbeoeepbppdnhhio?hl=en-US).
  2. Find the SAML response or request (that is highlighted with green color in the extension) it doesn`t matter response or request cause needed RelayState value we can extract from both operations.
  3. Click on the response/request and on the Request tab find and copy value called RelayState (see the screenshot below).
  1. Paste this value into https://www.urldecoder.org/ and decode.
  2. Copy the decoded value and paste it in the IdP Initiated SSO RelayState field on the IdP side(see the screenshot below). Save configuration.
  1. After some time the changes will take effect on IdP side and users can sign in using the IdP-initiated flow.