---
title: 'Tutorial: Authenticate Using SAML with Keycloak'
canonical: https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-keycloak/
product: CloudConnexa Docs
description: This tutorial shows the steps to authenticate your Users using SAML. You can configure CloudConnexa SAML authentication to use Keycloak as the Identity Provider.
keywords: Keycloak
---

# 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.

> **Important**
>
> If you use a Keycloak metadata URL, CloudConnexa must be able to retrieve it. For a self-hosted Keycloak instance that isn't reachable from the public internet, use the **Metadata XML** method instead. Users must still be able to reach the Keycloak authentication endpoint to sign in.

> **Note**
>
> If you manage multiple WPCs, ensure you're configuring the correct Cloud ID. Each WPC has its own SAML authentication configuration.

## 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.

   > **Tip**
   >
   > If you selected the wrong provider, select **Change** next to **Your Identity Provider** on the next screen.

## 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` |

   > **Tip**
   >
   > The ACS URL is the same for every CloudConnexa WPC.
   >
   > For the Issuer Name, the `<cloud-id>` is replaced with your WPC's Cloud ID prefix.
3. Keep the wizard open. You'll return to it after configuring Keycloak.

> **Important**
>
> The Keycloak **Client ID** must match the CloudConnexa **Issuer Name** exactly. For example, if your Cloud ID is `yourcompany`, use `yourcompany.openvpn.com`.
>
> A mismatched Client ID or a SAML client created in the wrong Keycloak realm can cause an **invalid requester** error during authentication.

For more information, refer to [SAML and SCIM Service Provider Endpoints for CloudConnexa](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/saml-and-scim-service-provider-endpoints-for-cloudconnexa.md).

## 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.

   > **Important**
   >
   > Keycloak clients belong to individual realms. If you create the CloudConnexa SAML client in a different realm, authentication can fail with an **invalid requester** error.
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` |

> **Note**
>
> **Sign assertions** controls whether Keycloak signs the SAML assertions sent to CloudConnexa. **Client signature required** controls whether Keycloak requires signed requests from the service provider. These are separate settings.

### 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.

   > **Important**
   >
   > The default **Group list** mapper uses the attribute name `member` and has **Full group path** enabled. Change both settings to send group names through the groups attribute rather than full paths such as `/parent/child`.

### 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.

     > **Tip**
     >
     > The metadata URL follows this pattern:
     >
     > ```
     > https://<keycloak-host>/realms/<realm>/protocol/saml/descriptor
     > ```
   - **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.

> **Note**
>
> CloudConnexa must be able to retrieve the metadata URL. If your Keycloak metadata endpoint isn't publicly accessible, use **Metadata XML** instead. Users must still be able to reach the Keycloak authentication endpoint to sign in.

## 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**.

> **Note**
>
> Using the metadata XML avoids the need for CloudConnexa to retrieve the Keycloak metadata URL. Users must still be able to reach the Keycloak authentication endpoint to complete SAML authentication.

### 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.

   > **Note**
   >
   > Check the signing certificate expiration date and the number of days remaining. CloudConnexa must have the current Keycloak signing certificate to validate SAML assertions.
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**.

> **Note**
>
> The `groups` mapping is needed only if you configured a Group list mapper in Keycloak.

## 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.

   > **Tip**
   >
   > If you configured group mapping, test with an account belonging to a Keycloak group you plan to map to CloudConnexa.

   > **Note**
   >
   > A successful test confirms authentication for the account you used. It doesn't verify every user in the realm.

### 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.

   > **Important**
   >
   > If Keycloak realm keys are rotated, CloudConnexa must receive the updated signing certificate. Refresh or reimport the Keycloak metadata after key rotation and verify authentication again.
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](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/set-saml-single-sign-on-user-group-mapping-rules.md).

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**.

   > **Note**
   >
   > SCIM provisions users, not user groups. Group membership still comes from SAML group claims and your user group mapping rules.

## 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. |

## Related resources

- [Set SAML Single Sign-On Authentication for Users](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/set-saml-single-sign-on-authentication-for-users.md)
- [SAML and SCIM Service Provider Endpoints for CloudConnexa](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/saml-and-scim-service-provider-endpoints-for-cloudconnexa.md)
- [Set SAML User Group Mapping Rules](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/set-saml-single-sign-on-user-group-mapping-rules.md)
- [About User Authentication](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/about-user-authentication.md)
- [About Multiple Authentication Methods](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/about-multiple-authentication-methods.md)
- [SAML authentication with CloudConnexa](https://openvpn.net/connect-docs/tutorials/saml-with-cloudconnexa.md)
- [Tutorial: Authenticate Using SAML with Okta](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-okta.md)
- [Tutorial: Authenticate Using SAML with Microsoft Entra ID](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-microsoft-entra-id.md)
- [Tutorial: Authenticate Using SAML with Google Workspace](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-google-workspace.md)

---

Prev: [Tutorial: Authenticate Using SAML with Google Workspace](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-google-workspace.md)
Next: [Tutorial: Authenticate Using SAML with Okta](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-okta.md)
Index: https://openvpn.net/cloud-docs/llms.txt