---
title: 'Tutorial: Authenticate Using SAML with Okta'
canonical: https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-okta/
product: CloudConnexa Docs
description: Configure Okta as a SAML identity provider for CloudConnexa using the SAML Setup Wizard — covers sharing SP metadata, creating the Okta app integration, mapping user attributes, testing the connection, and setting up optional User Group Mapping and SCIM provisioning.
keywords: Okta
---

# Tutorial: Authenticate Using SAML with Okta

## Overview

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

You'll create a SAML application in Okta, exchange configuration details between Okta and CloudConnexa, map user attributes, and test authentication before completing the setup.

## Before you begin

You need:

- **CloudConnexa:** The Owner or Administrator role for the WPC you're configuring.
- **Okta:** The Super Administrator or Application Administrator role.
- **Access to both administration portals:** Keep both open while you configure SAML because you'll exchange values between them.

> **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 Okta 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 **Okta**.
   - The wizard displays the configuration instructions and default attribute mappings for Okta.

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

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

1. Under **Share CloudConnea Metadata**, copy the following values:

   | **CloudConnexa value** | **Use in Okta** | **Format** |
   | --- | --- | --- |
   | Single Sign-On URL (ACS) | Single sign-on URL, also called the Assertion Consumer Service (ACS) URL | `https://sso-backend.openvpn.com/sso/api/v1/saml/acs` |
   | Issuer Name | Audience URI (SP Entity 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.
2. Keep the wizard open. You'll return to it after configuring Okta.

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 application in Okta

Create an application in Okta that uses service provider values from CloudConnexa.

1. Sign in to the **Okta Admin Console**.
2. Navigate to **Applications and Resources → Applications**.
3. Select **Create App Integration**.
4. Select **SAML 2.0**, then select **Next**.
5. Enter an **App name** and define any desired general settings.
6. Select **Next**.
7. Configure the **SAML Settings** with the following values:

   | **Okta field** | **Value** |
   | --- | --- |
   | Single sign-on URL | **Single Sign-On URL (ACS)** from CloudConnexa from Step 2 |
   | Audience URI (SP Entity ID) | **Issuer Name** from CloudConnexa from Step 2 |
   | Name ID format | `EmailAddress` |
8. After you've created the app, select its **Sign On** tab.
9. Scroll to **Attribute statements** and select **Add expression**.
10. Add the following so Okta sends the user information CloudConnexa expects:

    | **Name** | **Expression** |
    | --- | --- |
    | `email` | `user.profile.email` |
    | `username` | `user.profile.login` |
    | `firstName` | `user.profile.firstName` |
    | `lastName` | `user.profile.lastName` |
11. If you plan to assign CloudConnexa user groups based on Okta group membership, expand **Show legacy configuration**.
12. Select **Edit**.
13. Under **Group attribute statements**, enter these values:

    > **Tip**
    >
    > The expression `.*` matches all groups assigned to a user. To send only certain groups, replace it with a regular expression that matches the group names you want to include.
    >
    > Sending group membership information doesn't automatically assign CloudConnexa user groups. You'll also need to configure [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).

    | **Field** | **Value** |
    | --- | --- |
    | Name | `groups` |
    | Name format | **Basic** |
    | Filter | **Matches regex** |
    | Filter value | `.*` |
14. Save your changes.

> **Note**
>
> When you test SAML authentication in CloudConnexa, use an Okta account that belongs to one of the included groups. Verify that the expected group appears in the **IdP Group** test result.

### Assign users or groups to the application

Users need access to the Okta application before they can authenticate to CloudConnexa.

1. Open the application's **Assignments** tab.
2. Assign the users or groups who need access to CloudConnexa.

### Retrieve Okta's metadata

1. Select your CloudConnexa application's **Sign On** tab.
2. Copy the application's **Metadata URL**.
3. Save this to use in the CloudConnexa **SAML Setup Wizard**.

## Step 4: Connect Okta to CloudConnexa

Now provide Okta's SAML configuration to CloudConnexa.

1. Return to the SAML Setup Wizard in CloudConnexa.
2. Select **Next Step**.
   - **Provide Okta Details** is displayed.
3. Paste the Okta **Metadata URL**.
4. Wait for CloudConnexa to retrieve the metadata.
5. Verify that the wizard displays **Metadata retrieved**, along with the issuer and certificate expiration date.
6. Leave **Advanced Settings** at their defaults.
7. Select **Next Step**.

Using a Metadata URL lets CloudConnexa retrieve Okta's published configuration without manually entering the endpoint and certificate.

## Step 5: Review user attribute mapping

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

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

1. Enable **Allow user attributes mapping (Optional)**.
2. Review the default mappings for Okta. If your application sends the attribute names configured in Step 3, you don't need to change them.

   | **CloudConnexa field** | **Okta attribute name** |
   | --- | --- |
   | Email Address | `email` |
   | Username | `username` |
   | Group | `groups` |
   | First Name | `firstName` |
   | Last Name | `lastName` |
3. If the default values match what your Okta application sends, leave them unchanged.
4. If your application sends different attributes, update the corresponding fields. Ensure each mapping matches, including capitalization.
5. For group mapping, the `groups` attribute must match the name of the **Group Attribute Statement** you configured in Okta.
6. Select **Next Step**.

## Step 6: Test SAML authentication

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

1. In the wizard, the **Test Okta Connection** step displays.
2. Select **Sign in With SAML SSO**.
3. Authenticate using an Okta account assigned to the application.
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 Okta:
   - 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 statements in Okta with the mappings from Step 5.

   > **Tip**
   >
   > Test with an account that belongs to an Okta group you plan to map. This lets you verify that Okta sends the expected group information.

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

### 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 Okta's configuration |
   | Attributes Mapped | The number of configured attribute mappings |
   | Issuer | The issuer value received from Okta |
   | 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. When you're satisfied with the configuration, select **Complete**.
   - Your SAML configuration is now available for users assigned to the CloudConnexa application in Okta.

## 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 | Okta metadata, SSO endpoint, issuer, and signing certificate |
| Attribute Mapping | How Okta's 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** | **What to check** |
| --- | --- |
| CloudConnexa doesn't receive the SAML response | Verify that Okta's **Single sign-on URL** matches the ACS URL from CloudConnexa. |
| Signature validation fails | Check Okta's signing certificate. Refresh the IdP metadata if the certificate has changed. |
| Issuer mismatch | Compare the issuer received from Okta with the issuer configured in CloudConnexa. |
| Audience mismatch | Verify that Okta's **Audience URI (SP Entity ID)** matches the **Issuer Name** from CloudConnexa |
| Assertion timestamp validation fails | Retry the test. If the issue continues, investigate assertion validity and clock synchronization. |
| User information is missing | Compare Okta's Attribute Statement names with the CloudConnexa attribute mappings. |
| User isn't assigned to the expected group | Verify the **Group Attribute Statement**, its filter, and your user group mapping rules. |
| Authentication previously worked but now fails | Check whether Okta's signing certificate expired or changed. Refresh the metadata if necessary. |
| User can't authenticate through Okta | Verify that the user is assigned to the CloudConnexa application in Okta. |
| Username doesn't match the expected value | Check the **Application username** and **Name ID** settings in Okta. |

## Related resources

- [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 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)
- [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 Multiple Authentication Methods](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/about-multiple-authentication-methods.md)
- [Video: Configure Authentication With SAML and Okta](https://openvpn.net/cloud-docs/videos/configuration/authentication/video--configure-authentication-with-saml-and-okta.md)
- [SAML authentication with CloudConnexa](https://openvpn.net/connect-docs/tutorials/saml-with-cloudconnexa.md)

---

Prev: [Tutorial: Authenticate Using SAML with Keycloak](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-keycloak.md)
Next: [Tutorial: Authenticate Using SAML with OneLogin](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-onelogin.md)
Index: https://openvpn.net/cloud-docs/llms.txt