---
title: 'Tutorial: Set Up IdP-Initiated SAML SSO to the User Portal'
canonical: https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--set-up-idp-initiated-saml-sso-to-the-user-portal/
product: CloudConnexa Docs
description: Set the RelayState so users can sign in to the CloudConnexa User Portal from their identity provider's app dashboard (IdP-initiated SSO). No WPC connection starts.
keywords: IdP-initiated SSO, SAML RelayState
---

# Tutorial: Set Up IdP-Initiated SAML SSO to the User Portal

## Overview

Configure identity provider-initiated (IdP-initiated) SAML single sign-on (SSO) so users can access the [CloudConnexa User Portal](https://openvpn.net/cloud-docs/user/cloudconnexa-user-portal.md) directly from their identity provider's application dashboard.

Most identity providers let users launch CloudConnexa from an application dashboard, such as **My Apps** or an app launcher. Keycloak uses a dedicated authentication URL instead.

> **Important**
>
> IdP-initiated SSO opens the User Portal but doesn't establish a Wide-Area Private Cloud (WPC) connection. Users still need the OpenVPN Connect app and a connection profile to [connect to CloudConnexa](https://openvpn.net/cloud-docs/user/get-connected/connect-to-cloudconnexa.md).

### SP-initiated vs. IdP-initiated SSO

With **service provider-initiated (SP-initiated) SSO**, users start authentication from CloudConnexa, which redirects them to their identity provider.

With **IdP-initiated SSO**, users start authentication from their identity provider, either through an application dashboard or a dedicated authentication URL.

To configure IdP-initiated SAML authentication, you'll capture the **RelayState** value used during a successful CloudConnexa SAML authentication and configure your identity provider to send it when users launch the application. RelayState is a SAML parameter that carries information used to complete the authentication flow and direct users to the appropriate destination.

## Before you begin

Ensure you have:

- **SAML SSO configured in CloudConnexa:** 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) if you haven't completed the initial configuration.
- **CloudConnexa permissions:** The Owner or Administrator role to manage the SAML configuration, if changes are needed.
- **Identity provider permissions:** Administrative access to the SAML application configured for CloudConnexa.
- **A test user:** An account authorized to authenticate to CloudConnexa through your identity provider.
- **A SAML tracing tool:** A browser extension that can capture SAML authentication requests and responses.

For this procedure, you can use **SAML-tracer**:

- [SAML-tracer for Google Chrome](https://chromewebstore.google.com/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch)
- [SAML-tracer for Firefox](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/)

## Step 1: Capture the RelayState value

First, authenticate to CloudConnexa from the User Portal to capture the RelayState value sent during the SAML exchange.

The RelayState value is the same for every user in your WPC, so you only need to capture it once. Any user who can sign in to the User Portal through your identity provider can be used to capture it.

1. Install the **SAML-tracer** browser extension.
2. Open SAML-tracer and start capturing your requests.
3. In the same browser, navigate to your CloudConnexa User Portal: `https://<cloud-id>.openvpn.com` (replace `<cloud-id>` with your organization's Cloud ID).
4. Sign in using the test account and complete authentication through your identity provider.

   > **Tip**
   >
   > If the browser automatically signs you in using an existing session, sign out and repeat the test so SAML-tracer can capture a new authentication exchange.
5. Return to SAML-tracer and locate the SAML authentication request or response associated with the CloudConnexa authentication.
6. Open the entry and locate the **RelayState** parameter.
7. Copy its value.
   - The value may resemble the following shortened example:

     ```
     zDf+iLRAkLCD...[redacted]...RcPUU4A==
     ```

     This example illustrates the format only. Use the complete value from your own SAML authentication exchange.

> **Important**
>
> Copy the complete RelayState value without modifying it. Don't URL-decode or Base64-decode the value displayed in SAML-tracer.

> **Tip**
>
> If SAML-tracer doesn't capture an authentication request, sign out of the User Portal and repeat the process. An existing session might allow access without starting a new SAML exchange.

> **Note**
>
> SAML traces can contain sensitive authentication information. Copy the RelayState value you need, and avoid sharing or exporting the complete SAML response unless necessary for authorized troubleshooting.

## Step 2: Configure RelayState in your identity provider

Configure the SAML application to send the captured RelayState value when users start authentication from your identity provider.

1. Sign in to your identity provider's administration console.
2. Open the SAML application configured for CloudConnexa.
3. Find the field used to configure RelayState for IdP-initiated authentication.

   The field name and location vary by identity provider:

   | **Identity provider** | **RelayState field** |
   | --- | --- |
   | [Okta](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-okta.md) | **Default RelayState** |
   | [Microsoft Entra ID](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-microsoft-entra-id.md) | **RelayState**, under **Basic SAML Configuration** |
   | [Google Workspace](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-google-workspace.md) | **Start URL** |
   | [JumpCloud](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-jumpcloud.md) | **Default RelayState** |
   | [Keycloak](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-keycloak.md) | **IDP Initiated SSO RelayState** |
   | [OneLogin](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-onelogin.md) | **RelayState** |
4. Paste the complete RelayState value copied in Step 1 into the corresponding setting, subject to your provider's supported format.
5. Save the application configuration.

   > **Note**
   >
   > Some changes may take time to propagate, up to 24 hours for Google Workspace.
6. Verify that the CloudConnexa application is available to the intended users in the identity provider's application dashboard.

If your identity provider isn't listed, refer to its documentation for the setting used to pass RelayState during IdP-initiated SAML authentication.

### Additional configuration for Keycloak

Keycloak uses a client-specific URL for IdP-initiated SAML authentication rather than an application dashboard.

1. In the Keycloak Admin Console, select the realm containing your CloudConnexa SAML client.
2. Navigate to **Clients** and select the client.
3. In the client settings, enter a URL-friendly name, such as `cloudconnexa`, in **IDP-Initiated SSO URL name**.
4. Enter the RelayState value from Step 1 in **IDP Initiated SSO RelayState**.
5. Save the configuration.
6. Users start authentication by opening the following URL:

   ```
   https://<keycloak-host>/realms/<realm>/protocol/saml/clients/<url-name>
   ```

   - Example:

     ```
     https://keycloak.example.com/realms/employees/protocol/saml/clients/cloudconnexa
     ```
7. Provide the URL to the users who need to access CloudConnexa.

> **Note**
>
> Users need network access to the Keycloak authentication endpoint. If Keycloak is hosted on a private network, the endpoint must be reachable from their devices.

## Step 3: Verify IdP-initiated authentication

Test the configuration from the identity provider's application dashboard, rather than starting from the CloudConnexa User Portal.

1. Sign out of the CloudConnexa User Portal.
2. Start authentication using the method configured for your identity provider:
   - **Most identity providers:** Sign in to the application dashboard and select the CloudConnexa application.
   - **Microsoft Entra ID:** Open My Apps and select the CloudConnexa application.
   - **Keycloak:** Open the client-specific IdP-initiated authentication URL configured previously.
3. Authenticate using the test account if prompted.
4. Verify that authentication succeeds and the browser opens the correct CloudConnexa User Portal.
5. Confirm that you can access the portal features available to the test account.

The configuration is complete when the test user can start authentication from the identity provider and access the CloudConnexa User Portal successfully.

**Remember:** This verifies access to the User Portal, not a WPC connection. Users need to establish a separate connection using OpenVPN Connect.

## Troubleshooting

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| No RelayState value appears in SAML-tracer. | Authentication wasn't captured, or an existing browser session bypassed the SAML exchange. | Open SAML-tracer before starting authentication. Sign out of the User Portal and repeat the process. |
| The application doesn't appear in the identity provider dashboard. | The application isn't assigned to the user or isn't configured for dashboard access. | Verify application assignments, visibility settings, and any provider-specific requirements for IdP-initiated SSO. |
| Authentication succeeds, but the User Portal doesn't open. | RelayState is missing, incorrect, improperly decoded, or not accepted by CloudConnexa. | Verify the RelayState configuration in your identity provider. Compare the value with the captured SAML exchange and repeat the test. |
| Authentication works from CloudConnexa but fails from the identity provider dashboard. | The RelayState isn't set in the application, the SAML app doesn't support IdP-initiated SSO, or the **IDP-Initiated SSO URL name** isn't set for Keycloak. | Verify that your identity provider supports IdP-initiated SAML authentication and that the application includes the required RelayState. |
| The identity provider reports a SAML response or configuration error. | The application has an incorrect ACS URL, issuer, certificate, or other SAML setting. | Review the configuration in your [SAML identity provider tutorial](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml.md) and test SP-initiated authentication before testing IdP-initiated authentication again. |
| The User Portal opens, but the device isn't connected to the WPC. | IdP-initiated SSO doesn't establish a VPN connection. | Open OpenVPN Connect and establish a WPC connection. Refer to [Connect to CloudConnexa](https://openvpn.net/cloud-docs/user/get-connected/connect-to-cloudconnexa.md). |
| A Microsoft Entra ID guest user can't access the correct My Apps portal. | Microsoft doesn't automatically identify the Entra tenant associated with the guest account. | Open `https://myapps.microsoft.com/?tenantid=<your-tenant-id>`, replacing `<your-tenant-id>` with the Tenant ID from **Microsoft Entra ID → Overview**. Authenticate using the guest account's configured method, such as an email verification code, then select the CloudConnexa application. |

## Related resources

- [CloudConnexa User Portal](https://openvpn.net/cloud-docs/user/cloudconnexa-user-portal.md)
- [Manage Devices Using the CloudConnexa User Portal](https://openvpn.net/cloud-docs/user/cloudconnexa-user-portal/manage-devices-using-cloudconnexa-user-portal.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)
- [SAML Configuration Tutorials](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml.md)
- [SAML authentication with CloudConnexa](https://openvpn.net/connect-docs/tutorials/saml-with-cloudconnexa.md)
- [About User Authentication](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/about-user-authentication.md)

---

Prev: [Tutorial: Authenticate Using SAML with Any SAML 2.0 Identity Provider](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-any-saml-2-0-identity-provider.md)
Next: [Connectors](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/connectors.md)
Index: https://openvpn.net/cloud-docs/llms.txt