Talk with SupportBook a DemoTry for free

Tutorial: Authenticate Using SAML with Keycloak⁠

Overview⁠

Configure Keycloak as a SAML 2.0 identity provider (IdP) for CloudConnexa using the SAML Setup Wizard. This lets your users authenticate to CloudConnexa with their Keycloak credentials.

You'll create a custom SAML client in Keycloak, configure user attribute and group mappers, connect Keycloak to CloudConnexa, and test authentication before completing the setup.

Before you begin⁠

You need:

  • CloudConnexa: The Owner or Administrator role for the WPC you're configuring.

  • Keycloak: An account with realm administrator permissions in the realm containing your users.

  • Keycloak 19 or later: The steps use the newer Keycloak Admin Console.

  • Access to both administration portals: Keep both open while you configure SAML because you'll exchange values between them.

Step 1: Start the SAML Setup Wizard⁠

Start by selecting Keycloak as your IdP in CloudConnexa.

  1. Sign in to your WPC's Administration Portal at your Cloud ID address (for example, yourcompany.openvpn.com).

  2. Navigate to Settings → User Authentication.

  3. Select Edit.

  4. On the SAML Single Sign-On card, select Setup.

  5. Under Select Your Identity Provider, select Keycloak.

    • The wizard displays the configuration instructions and default attribute mappings for Keycloak.

Step 2: Get the service provider values for CloudConnexa⁠

Keycloak needs service provider (SP) values from CloudConnexa to send SAML authentication responses to the correct WPC.

  1. Under Share CloudConnexa Metadata, select Download.

    • The metadata file (.xml) downloads to your machine.

  2. Or, you can copy the following values:

    CloudConnexa value

    Use in Keycloak

    Format

    Single Sign-On URL (ACS)

    Valid redirect URIs and Master SAML Processing URL

    https://sso-backend.openvpn.com/sso/api/v1/saml/acs

    Issuer Name

    Client ID

    <cloud-id>.openvpn.com

  3. Keep the wizard open. You'll return to it after configuring Keycloak.

For more information, refer to SAML and SCIM Service Provider Endpoints for CloudConnexa.

Step 3: Create a SAML client in Keycloak⁠

Create the SAML client in the Keycloak realm containing the users who need access to CloudConnexa.

  1. Sign in to the Keycloak Admin Console at https://<your-keycloak-host>/admin/.

  2. Use the realm selector to select the realm containing your users.

  3. Navigate to Clients.

Create or import the SAML client⁠

You can import the CloudConnexa SP metadata or create the client manually.

Option 1: Import the metadata⁠

  1. Select Import client.

  2. Upload the CloudConnexa metadata XML file downloaded in Step 2.

  3. Review the imported settings.

  4. Select Save.

Option 2: Create the client manually⁠

  1. Select Create client.

  2. Set Client type to SAML.

  3. For Client ID, enter the CloudConnexa Issuer Name from Step 2.

  4. Enter the CloudConnexa Single Sign-On URL (ACS) in both:

    • Valid redirect URIs

    • Master SAML Processing URL

  5. Select Save.

Configure the SAML client settings⁠

  1. Review these settings for the CloudConnexa client:

    Keycloak setting

    Location

    Value

    Name ID format

    Settings → SAML capabilities

    email

    Force POST binding

    Settings → SAML capabilities

    Off

    Sign assertions

    Settings → Signature and Encryption

    On

    Client signature required

    Keys → Signing keys config

    Off

Configure user attribute mappers⁠

CloudConnexa needs user attributes from Keycloak to identify users. Add mappers for the user attributes. Keycloak sends only the Name ID until you do.

  1. Select the Client scopes tab for your SAML client.

  2. Open the dedicated client scope for your CloudConnexa client, named <clientID>-dedicated.

  3. Select Configure a new mapper.

  4. Select the User Property mapping option from the table that displays.

  5. Create the user property mappers listed below, giving each a mapper name that works best for your configuration.

    Property

    SAML Attribute Name

    email

    email

    username

    username

    firstName

    firstName

    lastName

    lastName

  6. Save each mapper.

    • Ensure that the SAML attribute names match the values you'll use in the CloudConnexa wizard.

Optional: Configure the group mapper⁠

If you want to assign CloudConnexa user groups based on Keycloak group membership, add a Group list mapper.

  1. In the same dedicated client scope, select Add mapper → By configuration.

  2. Select the Group List mapping option from the table that displays.

  3. Configure these settings:

    Setting

    Value

    Group attribute name

    groups

    Full group path

    Off

  4. Save the mapper.

Review access to the SAML client⁠

By default, users in the configured Keycloak realm may be able to authenticate through the client. If you need to restrict access:

  1. Use client roles with a role mapper.

  2. Use Authorization policies.

  3. Or, put CloudConnexa Users in a separate realm.

Get the Keycloak identity provider metadata⁠

CloudConnexa needs the Keycloak SAML metadata to configure authentication. You can provide either the metadata URL or the XML document.

  1. In the Keycloak Admin Console, navigate to Realm settings → General.

  2. Under Endpoints, locate SAML 2.0 Identity Provider Metadata.

  3. Choose one of the following methods:

    • Metadata URL: Copy the link address for SAML 2.0 Identity Provider Metadata. You'll paste this URL into CloudConnexa.

    • Metadata XML: Select SAML 2.0 Identity Provider Metadata to open the XML document in your browser. Seve the XML content to paste in Step 4.

Step 4: Connect Keycloak to CloudConnexa⁠

Provide the Keycloak identity provider metadata to CloudConnexa. Choose one of the following methods.

Option 1: Use the metadata XML⁠

Use this method if CloudConnexa can access your Keycloak metadata URL.

  1. Return to the SAML Setup Wizard in CloudConnexa.

  2. Select Next Step.

    • Provide Keycloak Details is displayed.

  3. Select Metadata XML.

  4. Paste the content you copied from the Keycloak SAML 2.0 Endpoint.

  5. Leave Advanced Settings at their defaults.

  6. Select Next Step.

Option 2: Use the metadata URL⁠

Use this method if CloudConnexa can't access your Keycloak metadata URL, such as when Keycloak is hosted on a private network.

  1. Return to the SAML Setup Wizard in CloudConnexa.

  2. Select Next Step.

    • Provide Keycloak Details is displayed.

  3. Select Metadata URL.

  4. In IdP Federation Metadata URL, paste the Keycloak SAML 2.0 Identity Provider Metadata URL copied in Step 3.

  5. Wait for Metadata retrieved to display. CloudConnexa automatically retrieves the SSO endpoint, issuer, and signing certificate.

  6. Verify the issuer and signing certificate expiration date.

  7. Leave Advanced Settings at their defaults.

  8. Select Next Step.

Update the Keycloak signing certificate⁠

Keycloak uses a signing certificate to sign SAML assertions. If the certificate expires or rotates, SAML authentication can fail until CloudConnexa receives the new certificate.

The CloudConnexa SAML configuration displays the number of days remaining before the signing certificate expires. Check this value periodically to plan certificate updates.

After rotating the certificate in Keycloak, update the metadata in CloudConnexa by providing the URL or XML again, then run the SAML authentication test to verify that CloudConnexa accepts assertions signed with the new certificate.

Step 5: Map user attributes⁠

CloudConnexa uses SAML attributes to identify users and retrieve their information from Keycloak.

The Map User Attributes step displays after you select Next Step. The wizard provides default Keycloak mappings.

  1. Enable Allow user attributes mapping (Optional).

  2. Review the default mappings for Keycloak.

    CloudConnexa field

    Keycloak SAML attribute name

    Email Address

    email

    Username

    username

    Group

    groups

    First Name

    firstName

    Last Name

    lastName

  3. Verify that the names match the SAML attributes configured in Keycloak, including capitalization.

  4. If the default values match, leave them unchanged.

  5. If your application sends different attributes, update the corresponding fields. Ensure each mapping matches, including capitalization.

  6. Select Next Step.

Step 6: Test SAML authentication⁠

Test the connection before completing the configuration to confirm that CloudConnexa can authenticate users through Keycloak.

  1. In the wizard, the Test Keycloak Connection step displays.

  2. Select Sign in With SAML SSO.

  3. Authenticate using a Keycloak account from the realm configured in Step 3.

  4. Review the test results. CloudConnexa checks the SAML response for:

    • A response received at the ACS endpoint.

    • A valid signature.

    • An issuer that matches the configuration.

    • An audience that matches the SP Entity ID.

    • An assertion timestamp within the allowed clock skew.

  5. The wizard shows whether each check passed or failed.

Verify the user attributes⁠

  1. The test also displays the user information received from Keycloak:

    • Email

    • First Name

    • Last Name

    • IdP Group

    • Username

  2. If a field displays -, CloudConnexa didn't receive a value under the expected attribute name. Compare the attribute names configured in Keycloak with the mappings from Step 5.

If the test fails⁠

  1. Review the check.

  2. Correct the configuration.

  3. Select Run Test Again.

    • Although the wizard allows you to continue after a failed test, we recommend resolving the errors before completing setup. Otherwise, users may be unable to authenticate.

Step 7: Review and complete the configuration⁠

The Configuration Details step summarizes the SAML settings you've configured.

  1. Review the following information:

    Setting

    What to verify

    Metadata Source

    How CloudConnexa retrieves the Keycloak configuration

    Attributes Mapped

    The number of configured attribute mappings

    Issuer

    The issuer value received from Keycloak

    Signing Certificate

    Certificate validity and expiration date

  2. You can also review the advanced settings, including Data Binding, Authentication Lifetime, Reconnecting, Authentication Context, and Logout URL.

    • The wizard may display additional setup options for user group mapping and SCIM provisioning.

  3. Note the signing certificate expiration date.

  4. When you're satisfied with the configuration, select Complete.

    • Your SAML configuration is now available for users who have access to the SAML client in Keycloak.

Optional: Configure user group mapping⁠

If you want CloudConnexa to assign users to user groups based on their IdP group membership, configure SAML user group mapping.

  1. In the CloudConnexa Administration portal, navigate to Settings → User Authentication → SAML Single Sign-On → Configuration → User Group Mapping.

  2. Configure mapping rules for the group information the IdP sends.

For detailed instructions, refer to Set SAML User Group Mapping Rules.

Group mapping is evaluated when users authenticate. If you change a user's group membership in the IdP, the updated mapping takes effect the next time they authenticate to CloudConnexa.

Optional: Configure SCIM provisioning⁠

SAML authenticates users when they access CloudConnexa. You can also configure System for Cross-domain Identity Management (SCIM) 2.0 to automate user provisioning.

With SCIM provisioning, the IdP can create, update, and deactivate users in CloudConnexa without waiting for authentication.

  1. To configure SCIM, navigate to Settings → User Authentication → SAML Single Sign-On → Configuration → SCIM 2.0.

Manage your SAML configuration⁠

After completing the wizard, you can review or change your configuration under Settings → User Authentication → SAML Single Sign-On → Configuration.

Configuration

What you can manage

IdP Configuration

Keycloak metadata, SSO endpoint, issuer, and signing certificate

Attribute Mapping

How Keycloak SAML attributes map to CloudConnexa user fields

User Group Mapping

Rules for assigning CloudConnexa user groups

SCIM 2.0

Automatic user provisioning

Troubleshooting⁠

Use these checks if authentication fails or CloudConnexa doesn't receive the expected user information.

Issue

Likely cause

What to check

Keycloak displays invalid requester.

The Client ID doesn't match the CloudConnexa Issuer Name, or the SAML client is in the wrong realm.

Compare the Client ID with the Issuer Name from Step 2. They need to match exactly. Verify that the client exists in the correct Keycloak realm.

The test reports that the response wasn't received at the ACS endpoint.

Keycloak sent the response to a different URL or didn't use HTTP POST.

Verify that Valid redirect URIs and Master SAML Processing URL match the CloudConnexa Single Sign-On URL (ACS).

The test reports a signature failure.

The signing certificate configured in CloudConnexa doesn't match the certificate Keycloak is using.

Refresh the Keycloak metadata in IdP Configuration, particularly if realm keys were rotated.

The test reports an issuer mismatch.

The Issuer received from Keycloak differs from the configured Issuer.

Compare the Issuer shown in Step 7 with the Keycloak realm metadata.

The test reports an audience mismatch.

The Keycloak Client ID doesn't match the CloudConnexa Issuer Name.

Verify the exact Client ID and Issuer Name values from Steps 2 and 3.

The test reports a timestamp failure.

The assertion has expired or its validity period doesn't match the allowed clock skew.

Retry the test. If it continues to fail, investigate the assertion timestamps and clock synchronization.

The user authenticates but has no name or email.

User attribute mappers are missing, or the SAML attribute names don't match the CloudConnexa mappings.

Add the User Property mappers and compare their SAML attribute names with Step 5. Verify that Allow user attributes mapping (Optional) is enabled.

The user isn't assigned to the expected CloudConnexa user group.

The group claim isn't sent or no matching mapping rule exists.

Verify the Group list mapper, confirm the attribute name is groups, and review the CloudConnexa user group mapping rules.

Group mapping rules never match.

The mapper still uses the default attribute name member or sends full paths such as /parent/child.

Set the Group list mapper attribute names to groups and Full group path to Off.

Authentication worked previously but now fails.

Keycloak realm signing keys were rotated or the signing certificate expired.

Check the certificate expiration date, refresh the metadata, and repeat the authentication test.

A user can't authenticate through the configured client.

The user belongs to a different realm or is excluded by a client role or authorization policy.

Verify the user realm and review the client access restrictions.

Keycloak rejects the SAML authentication request.

Client signature required is enabled, but Keycloak doesn't have the service provider certificate needed to verify the request signature.

On the Keys tab, verify Client signature required is Off, as specified in Step 3.

CloudConnexa can't retrieve the Keycloak metadata URL.

The Keycloak host isn't reachable from CloudConnexa, or the metadata endpoint is unavailable.

Verify the metadata URL. If Keycloak is accessible only internally, export the SAML 2.0 Identity Provider Metadata document and use Metadata XML instead.

Users can't reach the Keycloak authentication page.

The Keycloak authentication endpoint isn't accessible from their network.

Verify the Keycloak hostname, DNS resolution, TLS certificate, and network access from the user devices.

© 2026 OpenVPN Inc. | OpenVPN is a registered trademark of OpenVPN, Inc. | CloudConnexa is a registered trademark of OpenVPN, Inc.

Service StatusPrivacy PolicyLegal