--- title: 'Tutorial: Authenticate Using SAML with Google Workspace' canonical: https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-google-workspace/ product: CloudConnexa Docs description: Configure Google Workspace as a SAML identity provider for CloudConnexa using the SAML Setup Wizard — covers downloading IdP metadata, creating a custom SAML app, mapping attributes and groups, testing the connection, and managing Google’s five-year certificate lifecycle. keywords: Google Workspace --- # Tutorial: Authenticate Using SAML with Google Workspace ## Overview Configure Google Workspace as a SAML 2.0 identity provider (IdP) for CloudConnexa using the SAML Setup Wizard. This lets your users authenticate to CloudConnexa with their Google Workspace credentials. You'll create a custom SAML app in the Google Admin console, exchange configuration details between Google Workspace 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. - **Google Workspace:** A super administrator account. - **Access to both administration portals:** Keep both open while you configure SAML because you'll exchange values between them. > **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 Google Workspace 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 **Google Workspace**. - The wizard displays the configuration instructions and default attribute mappings for Google Workspace. > **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 Google Workspace 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 Google Workspace** | **Format** | | --- | --- | --- | | Single Sign-On URL (ACS) | ACS URL | `https://sso-backend.openvpn.com/sso/api/v1/saml/acs` | | Issuer Name | Entity ID | `.openvpn.com` | > **Tip** > > The ACS URL is the same for every CloudConnexa WPC. > > For the Issuer Name, the `` is replaced with your WPC's Cloud ID prefix. 2. Keep the wizard open. You'll return to it after configuring Google Workspace. 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: Create a custom SAML app in Google Workspace Create a custom SAML application in the Google Admin console to connect Google Workspace to CloudConnexa. 1. Sign in to the [Google Admin console](https://admin.google.com/). 2. Navigate to **Apps → Web and mobile apps**. 3. Select **Add app → Add custom SAML app**. > **Note** > > Google's pre-integrated SAML catalog doesn't have a CloudConnexa entry. 4. Enter an App name such as `CloudConnexa`. 5. Select **CONTINUE**. ### Download the Google IdP metadata Google Workspace provides its identity provider metadata before asking you to configure the service provider details. 1. On the **Google Identity Provider details** page, select **DOWNLOAD METADATA**. 2. Save the XML file. 3. Select **CONTINUE**. - You'll import this metadata XML file into CloudConnexa in Step 4. > **Important** > > Keep the Google IdP metadata file separate from the CloudConnexa service provider metadata downloaded in Step 2. They contain different configuration information. > **Tip** > > Google doesn't publish a metadata URL, so when Google's certificate changes, you have to re-import the file. See Step 7. ### Configure the service provider details On the **Service provider details** page, enter the values from CloudConnexa. 1. Configure the following fields: | **Google Workspace field** | **Value** | | --- | --- | | ACS URL | **Single Sign-On URL (ACS)** from Step 2 | | Entity ID | **Issuer Name** from Step 2 | 2. Leave **Signed response**, **Name ID format**, and **Name ID** at their defaults. 3. Select **Continue**. ### Map user attributes Google Workspace requires you to configure the user attributes that CloudConnexa will receive in SAML assertions. On the **Attribute mapping** page: 1. Select **ADD MAPPING**. 2. Configure the following mappings: | **Google Directory attribute** | **App attribute** | | --- | --- | | Basic Information → Primary email | `primaryEmail` | | Basic Information → First name | `firstName` | | Basic Information → Last name | `lastName` | 3. Verify that the **App attribute** values match the table exactly, including capitalization. - CloudConnexa uses these attributes to identify users and display their information. ### Optional: Include group membership in SAML assertions If you want CloudConnexa to assign users to user groups based on their Google Workspace group membership, configure the group claim. 1. On the **Attribute mapping** page, locate **Group membership (optional)**. 2. Select the Google Workspace groups you want to include in SAML assertions. 3. Enter `groups` as the **App attribute**. 4. Verify that the selected groups include the memberships you want CloudConnexa to evaluate. > **Important** > > Google Workspace supports a maximum of 75 selected groups for this group membership configuration. If your organization has more groups, select only those needed for CloudConnexa access. Sending group membership information doesn't automatically assign CloudConnexa user groups. You'll also need to configure [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). ### Finish creating the application 1. Select **FINISH** to create the custom SAML app. 2. Open the application in the Google Admin console. ### Enable the application for users Users need access to the custom SAML app before they can authenticate to CloudConnexa. 1. Open **User access** for the CloudConnexa application. 2. Choose the appropriate access setting: - To enable the application for all users, select **ON for everyone**. - To enable it for specific organizational units, select the organizational unit and turn on the application for that unit. 3. Save your changes. > **Note** > > Changes to application access in Google Workspace can take up to 24 hours to take effect. ## Step 4: Connect Google Workspace to CloudConnexa Now import the Google IdP metadata XML file into CloudConnexa. 1. Return to the SAML Setup Wizard in CloudConnexa. 2. Select **Next Step**. - **Provide Google Workspace Details** is displayed. 3. Select the option to provide **Metadata XML**. 4. Upload the Google IdP metadata XML file downloaded in Step 3. 5. Verify that CloudConnexa reads the metadata and displays the identity provider configuration, including the issuer and signing certificate details. 6. Leave **Advanced Settings** at their defaults. 7. Select **Next Step**. > **Note** > > Google Workspace uses a downloadable metadata XML file for this configuration rather than the metadata URL method used by some other identity providers. If the Google signing certificate changes, you'll need to download updated metadata and import it into CloudConnexa. ## Step 5: Review user attribute mapping CloudConnexa uses SAML attributes to identify users and retrieve their information from Google Workspace. The **Map User Attributes** step displays after you select **Next Step**. The wizard provides default Google Workspace mappings. 1. Enable **Allow user attributes mapping (Optional)**. 2. Review the default mappings for Google Workspace. | **CloudConnexa field** | **Google Directory attribute** | **SAML attribute name** | | --- | --- | --- | | Email Address | Basic Information → Primary email | `primaryEmail` | | Username | Taken from the Primary email | `primaryEmail` | | Group | Group membership (optional) | `groups` | | First Name | Basic Information → First name | `firstName` | | Last Name | Basic Information → Last name | `lastName` | 3. If the default values match what your Google Workspace 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 **App attribute** configured under **Group membership (optional)**. 6. Select **Next Step**. ## Step 6: Test SAML authentication Test the connection before completing the configuration to confirm that CloudConnexa can authenticate users through Google Workspace. 1. In the wizard, the **Test Google Workspace Connection** step displays. 2. Select **Sign in With SAML SSO**. 3. Authenticate using a Google Workspace account that has access to the custom SAML app. 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 Google Workspace: - Email - First Name - Last Name - IdP Group - Username 2. If a field displays `-`, CloudConnexa didn't receive a value under the expected attribute name. Compare the attribute statements in Google Workspace with the mappings from Step 5. > **Tip** > > Test with an account that belongs to one of the Google Workspace groups you selected under **Group membership (optional)**. This lets you verify that the SAML assertion includes the expected group information. > **Note** > > A successful test confirms authentication for the account you used. It doesn't verify every user in your Google Workspace 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. > **Note** > > If you recently enabled the application or changed access for an organizational unit, allow time for the changes to take effect. Google Workspace changes can take up to 24 hours to propagate. ## 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 | The Google IdP metadata XML file | | Attributes Mapped | The number of configured attribute mappings | | Issuer | The issuer value received from Google Workspace | | 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. > **Note** > > Note the certificate expiry. Google's SAML certificate lasts five years. When the certificate changes, authentication fails for every User until you download the new metadata from Google and re-import it into CloudConnexa. Refer to [Manage the Google Workspace signing certificate](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-google-workspace/#manage-the-google-workspace-signing-certificate). 3. When you're satisfied with the configuration, select **Complete**. - Your SAML configuration is now available for users who have access to the custom SAML app in Google Workspace. ### Manage the Google Workspace signing certificate Google Workspace SAML signing certificates are valid for up to five years. You'll need to update the CloudConnexa configuration when the certificate is replaced or expires. To avoid authentication interruptions: 1. Record the signing certificate expiration date shown in CloudConnexa. 2. Schedule a reminder to review the certificate before it expires. 3. When the certificate changes, download updated Google IdP metadata from the Google Admin console. 4. In CloudConnexa, navigate to **Settings → User Authentication → SAML Single Sign-On → Configuration → IdP Configuration**. 5. Import the updated metadata. 6. Test SAML authentication to verify that the updated certificate works. > **Important** > > If CloudConnexa has an outdated signing certificate, SAML signature validation can fail and prevent users from authenticating. ## 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 | Google IdP metadata, SSO endpoint, issuer, and signing certificate | | Attribute Mapping | How Google Workspace 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 it didn't receive a response at the ACS endpoint. | Google Workspace sent the response to a different URL, or didn't use HTTP POST. | Verify that Google's **ACS URL** is exactly the **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 Google Workspace is using. | Re-import Google's metadata (Step 7). This is expected if the certificate changed. | | The test reports an issuer mismatch. | The Issuer configured in CloudConnexa doesn't match the issuer sent by Google Workspace. | Compare the Issuer shown in Step 7 with the value in the Google Admin console. | | The test reports an audience mismatch. | Google Workspace was given the wrong **Issuer Name** as its Entity ID. | Check Step 2 against the value from Step 1. | | The test reports a timestamp failure. | The clocks of Google Workspace and CloudConnexa are out of sync, or the assertion has expired. | Retry the test. If it continues to fail, investigate the assertion timestamps and clock synchronization. | | The user authenticates but has no name or email. | Google sends only the Name ID unless attributes are mapped | Map Primary email, First name, and Last name under **Attribute mapping**, using the names in Step 5. | | The user isn't assigned to the expected CloudConnexa user group. | The group attribute isn't included in the assertion, or no matching user group mapping rule exists. | Confirm the groups selected under **Group membership (optional)**, then check the rules in **SAML User Group Mapping Rules**. | | Authentication worked previously but now fails. | The Google signing certificate expired or was replaced. | Check the expiry shown in Step 7. Download the new metadata and re-import it under **Configuration → IdP Configuration**. | | The User can't reach CloudConnexa at all. | The app isn't turned on for the User's organizational unit. | Check the app's **User access**. | | Google reports that the app isn't enabled for this account. | **Service status** is Off for the User's organizational unit | Navigate to **Apps → Web and mobile apps →** the app **→ User access** and turn it on. If the unit inherits Off, use **Override**. | | Everything looks correct, but authentication still fails. | Google's changes haven't propagated yet. Google states this can take up to 24 hours. | Wait, then retry in a fresh browser session before you change the configuration. | | Group mapping stops working for one group. | Group membership is an explicit list of selected groups, capped at **75**. A renamed group isn't tracked. | Open **Group membership (optional)** again and re-add the renamed group. | | Authentication worked previously but now fails with a signature error. | The certificate was replaced. Google's SAML certificates have a five-year life. | Manage certificates under **Security → Authentication → SSO with SAML applications**, then re-import the metadata into CloudConnexa. | ## Related resources - [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 Authentication for Users](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/set-saml-single-sign-on-authentication-for-users.md) - [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) - [About Multiple Authentication Methods](https://openvpn.net/cloud-docs/owner/settings/settings---user-authentication/about-multiple-authentication-methods.md) - [Video: Configure Authentication With SAML and Okta](https://openvpn.net/cloud-docs/videos/configuration/authentication/video--configure-authentication-with-saml-and-okta.md) - [SAML authentication with CloudConnexa](https://openvpn.net/connect-docs/tutorials/saml-with-cloudconnexa.md) --- Prev: [Tutorial: 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) Next: [Tutorial: Authenticate Using SAML with Keycloak](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/authentication/saml/tutorial--authenticate-using-saml-with-keycloak.md) Index: https://openvpn.net/cloud-docs/llms.txt