Talk with SupportBook a DemoTry for free

Tutorial: Authenticate Using SAML with OneLogin⁠

Overview⁠

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

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

Before you begin⁠

You need:

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

  • OneLogin: The Super User or Account Owner role.

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

  • A OneLogin test account: Use an account that you can assign to the application. If you're configuring group mapping, use an account with the appropriate role or group membership.

For more information about SAML authentication, refer to Set SAML Single Sign-On Authentication for Users.

Step 1: Start the SAML Setup Wizard⁠

Start by selecting OneLogin 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 OneLogin.

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

Step 2: Get the service provider values for CloudConnexa⁠

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

  1. Under Share CloudConnexa Metadata, copy the following values:

    CloudConnexa value

    Use in OneLogin

    Format

    Single Sign-On URL (ACS)

    Recipient and ACS (Consumer) URL

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

    Issuer Name

    Audience (EntityID)

    <cloud-id>.openvpn.com

  2. Keep the wizard open. You'll return to it after configuring OneLogin.

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

Step 3: Configure the SAML application in OneLogin⁠

Create a custom SAML application in OneLogin and configure it with the CloudConnexa service provider values.

Create the application⁠

  1. Sign in to the OneLogin Admin portal at https://<subdomain>.onelogin.com.

  2. Open Administration.

  3. Navigate to Applications → Applications.

  4. Select Add App.

  5. Search for SAML Custom Connector (Advanced) and select it.

  6. Enter a display name, such as CloudConnexa.

  7. Select Save.

Configure the SAML settings⁠

  1. Open the application's Configuration tab.

  2. Enter the following values:

    OneLogin field

    Value

    Audience (EntityID)

    Issuer Name from Step 2

    Recipient

    Single Sign-On URL (ACS) from Step 2

    ACS (Consumer) URL

    Single Sign-On URL (ACS) from Step 2

    ACS (Consumer) URL Validator

    Regular expression matching the Single Sign-On URL (ACS)

  3. For ACS (Consumer) URL Validator, enter a regular expression that matches the CloudConnexa ACS URL. For example:

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

    OneLogin uses this expression to validate the destination for SAML responses. The ^ and $ characters anchor the beginning and end of the URL, and the backslashes escape special characters.

  4. Set SAML signature element to Assertion.

  5. Select Save.

Configure user attributes⁠

OneLogin sends a NameID value by default. Add SAML parameters so CloudConnexa can also receive user details and group membership.

  1. Open the application's Parameters tab.

  2. Select Add (+) to create a parameter.

  3. Enter the parameter name from the table below.

  4. Select Include in SAML assertion.

  5. Save the parameter.

  6. Select the corresponding OneLogin user attribute as its value.

  7. Save the configuration.

  8. Repeat for each parameter you want to send.

    SAML parameter name

    OneLogin attribute to send

    email

    User's email address

    username

    User's username

    firstname

    User's first name

    lastname

    User's last name

    groups

    Roles or Groups, if configuring group mapping

Configure group attributes (optional)⁠

If you want CloudConnexa to assign user groups based on OneLogin roles or groups, configure the groups parameter to send multiple values.

  1. On the Parameters tab, add or edit the groups parameter.

  2. Select Include in SAML assertion.

  3. Set the parameter value to Roles or Groups, depending on the memberships you want to send.

  4. For the output format, select Semicolon Delimited input (Multi-value output).

  5. Save the configuration.

    • This format sends multiple role or group values as separate SAML attribute values, allowing CloudConnexa to evaluate them against user group mapping rules.

Assign users to the application⁠

Only users assigned to the OneLogin application can authenticate to CloudConnexa through OneLogin.

  1. Open the application's Users tab.

  2. Assign the users who need access.

  3. Verify that your test account has access to the application.

Copy the OneLogin Issuer URL⁠

The OneLogin Issuer URL serves as the metadata URL.

  1. Open the application's SSO tab.

  2. Locate Issuer URL.

  3. Copy the Issuer URL.

    • You'll provide this value to CloudConnexa in the next step.

Step 4: Connect OneLogin to CloudConnexa⁠

Provide the OneLogin identity provider metadata to CloudConnexa. The metadata contains the SSO endpoint, issuer, and signing certificate needed for authentication.

Option 1: Use the Issuer URL⁠

Use this method to retrieve OneLogin metadata directly.

  1. Return to the CloudConnexa SAML Setup Wizard.

  2. Select Next Step to open Provide OneLogin Details.

  3. Select Metadata URL.

  4. In IdP Federation Metadata URL, paste the Issuer URL copied from the OneLogin SSO tab.

  5. Wait for Metadata retrieved to display.

    • CloudConnexa automatically retrieves the OneLogin 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.

Option 2: Use the metadata XML⁠

Use this method if you prefer to import the OneLogin metadata document.

  1. In OneLogin, open the application's More Actions menu and select SAML Metadata.

  2. Save the metadata XML file.

  3. Return to the CloudConnexa SAML Setup Wizard.

  4. Select Next Step to open Provide OneLogin Details.

  5. Select Metadata XML.

  6. Provide the downloaded metadata XML file.

  7. Verify the issuer and signing certificate details.

  8. Leave Advanced Settings at their defaults.

  9. Select Next Step.

Step 5: Map user attributes⁠

CloudConnexa uses SAML parameters to identify users and retrieve their information from OneLogin.

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

  1. Enable Allow user attributes mapping (Optional).

  2. Review the default mappings for OneLogin.

    CloudConnexa field

    OneLogin SAML parameter

    Email Address

    email

    Username

    username

    Group

    groups

    First Name

    firstname

    Last Name

    lastname

  3. Verify that the names match the SAML parameters configured in OneLogin, 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 OneLogin.

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

  2. Select Sign in With SAML SSO.

  3. Authenticate using a OneLogin 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 OneLogin:

    • Email

    • First Name

    • Last Name

    • IdP Group

    • User Principal Name

  2. If a field displays -, CloudConnexa didn't receive the attribute under the configured claim name. Check the parameter in OneLogin and the mapping in 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 you supplied the OneLogin metadata

    Attributes Mapped

    The number of configured attribute mappings

    Issuer

    The OneLogin issuer value

    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 certificate expiry. When OneLogin rotates its signing certificate, authentication fails until CloudConnexa has the new one. If you connected with the Issuer URL, supplying it again is enough. Otherwise, re-import the metadata.

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

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

Update the OneLogin signing certificate⁠

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

The Configuration Details step displays the number of days remaining before the certificate expires. Check the expiration date and plan to update the metadata when the certificate changes.

To update the signing certificate in CloudConnexa:

  • Metadata URL: Provide the OneLogin Issuer URL again to retrieve the updated metadata.

  • Metadata XML: Download the updated metadata document from OneLogin and import it again.

After updating the metadata, test SAML authentication to verify that CloudConnexa accepts the new certificate.

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

OneLogin metadata, SSO endpoint, issuer, and signing certificate

Attribute Mapping

How OneLogin 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

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

OneLogin sent the response to the wrong URL or didn't use the expected HTTP-POST binding.

Verify that Recipient and ACS (Consumer) URL exactly match the CloudConnexa Single Sign-On URL (ACS) from Step 2.

The test reports a signature failure.

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

Refresh the current OneLogin metadata in IdP Configuration. Check whether OneLogin recently rotated its certificate.

The test reports an issuer mismatch.

The configured issuer doesn't match the issuer in the OneLogin SAML response.

Compare the issuer in CloudConnexa with the metadata returned by the OneLogin Issuer URL.

The test reports an audience mismatch.

Audience (EntityID) in OneLogin doesn't match the CloudConnexa Issuer Name.

Compare Audience (EntityID) with the Issuer Name from Step 2. Use the correct Cloud ID.

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.

The parameters are missing, named differently, or not included in the assertion.

Check the Parameters tab in OneLogin and verify Include in SAML assertion. Confirm that Allow user attributes mapping (Optional) is enabled and that the names in Step 5 match exactly.

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

The groups attribute is missing, contains unexpected values, or has no matching mapping rule.

Verify the OneLogin groups parameter and its values. Review the SAML user group mapping rules.

Authentication worked previously but stopped.

The OneLogin signing certificate expired or was rotated.

Check the certificate expiration date in IdP Configuration. Retrieve the updated OneLogin metadata and test authentication again.

App not assigned to user.

The user hasn't been assigned the CloudConnexa application in OneLogin.

Assign the user on the application's Users tab or grant access through a OneLogin role.

CloudConnexa rejects the response with a signature error.

SAML signature element is set to Response instead of Assertion.

In OneLogin, open the application's Configuration tab and set SAML signature element to Assertion. Save and test again.

A redirect loop occurs, or OneLogin refuses the ACS URL.

ACS (Consumer) URL Validator doesn't match the actual ACS URL.

Verify the ACS URL in Step 2. Enter an exact-match regular expression in ACS (Consumer) URL Validator, including the ^ and $ anchors and escaped special characters.

User group mapping rules never apply.

Include in SAML assertion isn't selected for groups, or the parameter sends a single value instead of multiple attribute values.

Enable Include in SAML assertion and set the group parameter to Semicolon Delimited input (Multi-value output). Then verify the CloudConnexa group mapping rules.

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

Service StatusPrivacy PolicyLegal