Documentation
Start typing to search…

How to Set Up Google as an IDP for use with CLOWD9

This document outlines the configuration steps required to set up Single Sign-On (SSO) between Google Cloud (Google Workspace) and the CLOWD9 system

What You’ll Need

Before starting, make sure you have:

Why Use Google as an IDP?

Google Workspace is widely used for enterprise user management. Combining this with our authentication allows your application to use Google’s secure user database while leveraging our authentication component (Keycloak) for SSO and role management.

This setup is especially useful for businesses that want a unified login experience across multiple platforms.

Step 1: Understand the SSO Flow

Here’s how the SSO process works in simple terms:

  1. A user tries to access CLOWD9 Vista Portal.
  2. The app redirects them to Keycloak.
  3. Keycloak checks if the user is logged in. If not, it sends them to Google’s login page.
  4. The user enters their Google credentials (like email and password).
  5. Google verifies the user and sends authentication details back to Keycloak.
  6. Keycloak issues a token to the application, allowing the user to access it without logging in again.
  7. User roles from Google groups can be used to control what the user can do in the app.
  8. This flow ensures secure and smooth access while keeping user data managed in Google Workspace.

Step 2: Google Cloud Configuration

To enable KeyCloak to authenticate Google users, you must register an OAuth application in the Google Cloud Platform.

  1. Login to Google Cloud Console (https://console.cloud.google.com)

  2. Click + CREATE CREDENTIALS and select OAuth client ID

    1. For Application type, select Web application

    2. In the Authorised redirect URIs section, add the following URLs: https://keycloak.prod.clowd9.io/realms/vista/broker/google/endpoint https://keycloak.prod.clowd9.io/realms/master/broker/google/endpoint https://keycloak.prod.clowd9.io/realms/clowd9-vista/broker/google/endpoint

  3. Additional Metadata (SAML) If your setup requires SAML integration alongside or instead of OIDC, please also provide the IdP metadata from your Google Workspace:

    • Navigate to Security > SSO with Google as SAML IdP in the Google Admin Console (https://admin.google.com).
    • Download the IdP Metadata file.
    • Transmit this file securely along with the credentials.

Step 3: Sharing Information with CLOWD9

  1. Add IdP in KeyCloak by contacting CLOWD9
    ⚠️This is sensitive data do not share in plain text or over email⚠️
    Please use a secure one-time password sharing tool (e.g., Snappass) to transmit the Client ID and Client Secret.
  2. CLOWD9 will need this data from you:
    1. SAML XML Metadata (if applicable) metadata from Google Admin Console
    2. OAuth Application ID, this is used as the Client ID from Google Cloud Console
    3. OAuth Secret Value , this is used as the Client Secret from Google Cloud Console

Step 4: Test Your Keycloak and Entra ID SSO Setup

To make sure authentication works correctly via Entra ID Single Sign-On (SSO) integration, follow these steps to test the login process. This will confirm that users can log in smoothly using their Entra ID credentials.

  1. Open your browser and go to your CLOWD9 Vista Portal (logout if you are already logged in). You should see a login page like the one below. Select the SSO option

  2. Enter your email address

  3. Follow the login steps for your company services

  4. That should complete your login and setup

Seeing this page means the SSO integration is working correctly.

Step 5: User Group Synchronisation

If the system needs to synchronize user groups from Google Workspace (e.g., to map Google Groups to Keycloak Roles), you must configure a Service Account with Domain-Wide Delegation.

  1. Enable Admin SDK API
    1. In the Google Cloud Console, navigate to APIs & Services > Library.
    2. Search for Admin SDK API and enable it.
  2. Create a Service Account
    1. Navigate to IAM & Admin > Service Accounts.
    2. Click + CREATE SERVICE ACCOUNT.
    3. Name it (e.g., group-reader-sa) and click Create and Continue.
    4. Grant the role Viewer to the service account, then click Done.
    5. Click on the newly created service account, go to the Keys tab, and click Add Key > Create new key.
    6. Select JSON and create. Save this file securely – it contains the private key.
  3. Enable Domain-Wide Delegation
    1. In the Service Account details, go to the Details tab.
    2. Click Show Domain-Wide Delegation settings.
    3. Check Enable Google Workspace Domain-wide Delegation.
    4. Click Save.
    5. Copy the Client ID (Unique ID) of the Service Account.
  4. Authorize in Google Admin Console
    1. Log in to the Google Admin Console (admin.google.com).
    2. Navigate to Security > Access and data control > API controls.
    3. Under Domain-wide delegation, click Manage Domain Wide Delegation.
    4. Click Add new and enter:
      1. Client ID: Paste the Service Account Client ID copied earlier.
      2. OAuth Scopes: Add the following scopes (comma-separated): Plaintext
        https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly
  5. Click Authorize.

Updated about 8 hours ago