---
title: 'Tutorial: Authenticate Using SAML with OneLogin'
canonical: https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-onelogin/
product: CloudConnexa Docs
description: Set up OneLogin as a SAML identity provider for CloudConnexa with the SAML Setup Wizard — configure the SAML Custom Connector, map parameters and groups, test the connection, and fix signature and ACS URL errors.
keywords: OneLogin
---

# 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](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/set-saml-single-sign-on-authentication-for-users.md).

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

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

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

   > **Tip**
   >
   > The Single Sign-On URL is the Assertion Consumer Service (ACS) URL. It's the endpoint where OneLogin sends the SAML response.
   >
   > The Issuer Name identifies your WPC. Replace `<cloud-id>` with your Cloud ID prefix, not your OpenVPN account name.
2. Keep the wizard open. You'll return to it after configuring OneLogin.

> **Tip**
>
> You can also select **Download** to save the CloudConnexa service provider metadata as an XML file. For this tutorial, you'll enter the values directly in OneLogin.

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

> **Important**
>
> OneLogin also lists an **OpenVPN Cloud** connector. That connector hasn't been verified with CloudConnexa. Use **SAML Custom Connector (Advanced)** for this procedure.

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

   > **Important**
   >
   > Ensure you set **SAML signature element** to **Assertion**, not the default **Response**. An incorrect signature element can cause CloudConnexa to reject the SAML response.

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

> **Important**
>
> Ensure the parameter names match the names you'll use in the CloudConnexa attribute mapping step.

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

> **Note**
>
> If you don't select **Include in SAML assertion**, OneLogin won't include the parameter in the SAML response, even if you created it.

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

   > **Tip**
   >
   > You can also grant application access through roles under **Users → Roles**.
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**.

> **Note**
>
> OneLogin publishes SAML metadata, so manual configuration isn't normally necessary. Use **Manual** only if your identity provider doesn't publish metadata.

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

> **Note**
>
> The Username mapping determines which SAML claim CloudConnexa uses to identify the user. Configure the corresponding OneLogin parameter to send the intended username value.
>
> A mismatch between parameter names is a common reason a user can authenticate, but their name or email isn't populated in CloudConnexa.
>
> If you aren't configuring user group mapping, the `groups` parameter isn't required.

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

     > **Tip**
     >
     > The **User Principal Name** value corresponds to the Username mapping.
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.

   > **Tip**
   >
   > If you configured group mapping, test with an account belonging to a OneLogin 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 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 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](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 | 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](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/set-saml-single-sign-on-user-group-mapping-rules.md). |
| 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. |

## Related Resources

### CloudConnexa configuration

- [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 Single Sign-On 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)

### Other SAML identity providers

- [SAML configuration tutorials](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml.md)
- [Authenticate using SAML with Okta](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-okta.md)
- [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)
- [Authenticate using SAML with Google Workspace](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-google-workspace.md)
- [Authenticate using SAML with JumpCloud](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-jumpcloud.md)
- [Authenticate using SAML with Keycloak](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-keycloak.md)

---

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