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 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.
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 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:
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.
Install the SAML-tracer browser extension.
Open SAML-tracer and start capturing your requests.
In the same browser, navigate to your CloudConnexa User Portal:
https://<cloud-id>.openvpn.com(replace<cloud-id>with your organization's Cloud ID).Sign in using the test account and complete authentication through your identity provider.
Return to SAML-tracer and locate the SAML authentication request or response associated with the CloudConnexa authentication.
Open the entry and locate the RelayState parameter.
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.
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.
Sign in to your identity provider's administration console.
Open the SAML application configured for CloudConnexa.
Find the field used to configure RelayState for IdP-initiated authentication.
The field name and location vary by identity provider:
Identity provider
RelayState field
Default RelayState
RelayState, under Basic SAML Configuration
Start URL
Default RelayState
IDP Initiated SSO RelayState
RelayState
Paste the complete RelayState value copied in Step 1 into the corresponding setting, subject to your provider's supported format.
Save the application configuration.
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.
In the Keycloak Admin Console, select the realm containing your CloudConnexa SAML client.
Navigate to Clients and select the client.
In the client settings, enter a URL-friendly name, such as
cloudconnexa, in IDP-Initiated SSO URL name.Enter the RelayState value from Step 1 in IDP Initiated SSO RelayState.
Save the configuration.
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
Provide the URL to the users who need to access CloudConnexa.
Step 3: Verify IdP-initiated authentication
Test the configuration from the identity provider's application dashboard, rather than starting from the CloudConnexa User Portal.
Sign out of the CloudConnexa User Portal.
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.
Authenticate using the test account if prompted.
Verify that authentication succeeds and the browser opens the correct CloudConnexa User Portal.
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 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. |
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 |