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.

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.

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

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.

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:

    Field	Value
    Name	groups
    Name format	Basic
    Filter	Matches regex
    Filter value	.*

14. Save your changes.

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.

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.

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.

Troubleshooting⁠

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

Related resources⁠

• SAML and SCIM Service Provider Endpoints for CloudConnexa

• Set SAML Single Sign-On Authentication for Users

• Set SAML User Group Mapping Rules

• About Multiple Authentication Methods

• Video: Configure Authentication With SAML and Okta

• SAML authentication with CloudConnexa