Docs for Google Workspace OIDC (#3102)

Author: hugobarauna

docs/images/auth_via_teams_oidc.png

@@ -23,7 +23,7 @@ Before configuring OIDC groups authorization, ensure you have:
 
 2. **Configured your OIDC identity provider** to include group information in the ID tokens:
    - **Okta**: [Customize tokens with a groups claim](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/)
-   - **Google Workspace**: Group-membersghip data is included by a mechanism that's specific to Google Workspace
+   - **Google Workspace**: No additional configuration is required; just ensure you've already followed [these instructions](oidc_sso.html#1-oidc-configurations)
    - **Others**: Search your identity provider's documentation for how to add a groups claim to the ID token
 
 ## Configuration

docs/teams/oidc_groups.md

@@ -2,36 +2,42 @@
 
 Livebook Teams supports OpenID Connect (OIDC) Single Sign-On, allowing you to authenticate users through your existing Identity Provider (IdP) when they access your app servers and Livebook apps.
 
-![](images/auth_via_teams.png)
+![](images/auth_via_teams_oidc.png)
 
 > #### Livebook version requirement {: .info}
-> Requires Livebook v0.15 or newer.
+> Requires Livebook v0.18 or newer.
 
 ## Demo
 
 Here's a quick demo of the feature working.
 
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/rG6OKethdJg?si=qofGf8M10F21IWd5" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-## Configuration
+## 1. OIDC configurations
 
 To integrate Livebook Teams with your OIDC SSO provider, follow these steps.
 
-### 1. Register with your OIDC Provider
+<!-- tabs-open -->
+
+### OIDC IdPs
+
+Follow these instructions if you're using Okta, Microsoft Entra, Keycloak or any other OIDC-compliant Identity Provider.
+
+#### 1.1 Register with your OIDC provider
 
 Go to your IdP admin, and register Livebook Teams as a Relying Party (client/app). This is the info you’ll need from Livebook Teams:
 
 - **Redirect URI**: The Livebook Teams sign-in callback URL that must be registered with your IdP: ` https://teams.livebook.dev/identity/callbacks/oidc`
 - **Post Logout Redirect URI**: The Livebook Teams URL that must be registered with your IdP to redirect users after logout: `https://teams.livebook.dev/identity/logout`
-- **Required OIDC scopes**: the OIDC scopes Livebook Teams requires: `openid`, `profile`, `email`, `offline_access`
+- **Required OIDC scopes**: The OIDC scopes Livebook Teams requires: `openid`, `profile`, `email`, `offline_access`
 
 Once that’s done, you should retrieve the following information from the registration process:
 
 - **Client ID**: A unique identifier assigned to Livebook Teams by your IdP
 - **Client Secret**: A confidential key assigned to Livebook Teams by your IdP
 - **Discovery URL**: This is the OIDC metadata URL provided by your IdP. Usual format: `https://YOUR_IDP/.well-known/openid-configuration`
 
-### 2. Configure OIDC in Livebook Teams
+#### 1.2 Configure OIDC in Livebook Teams
 
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/dNUcRD0A6kU?si=eNQ55-Aeg4I8PPgy" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
@@ -45,13 +51,79 @@ Once that’s done, you should retrieve the following information from the regis
 	- **Enable this SSO provider**: Make sure this option is enabled
 4. Save
 
-### 3. Configure your deployment group to authenticate via Livebook Teams
+### Google Workspace
+
+To configure OIDC SSO with Google Workspace, follow the steps below. You'll need a Google Workspace account with the super admin role.
+
+#### 1.1 Enable Cloud Identity API
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Select your project or create a new one if needed
+3. Navigate to **APIs & Services** > **Library**
+4. Search for **Cloud Identity**
+5. Select **Cloud Identity** from the results
+5. Click **Enable**
+
+#### 1.2 Create service account
+
+1. Navigate to **IAM & Admin** > **Service Accounts**
+2. Click **Create Service Account**
+3. Configure the service account:
+    - **Service account name**: `livebook-teams` (or your preferred name)
+    - **Service account description**: Service account for Livebook Teams to access Google Workspace groups
+4. Click **Create and Continue**
+5. Skip the optional steps by clicking **Continue** and then **Done**
+
+#### 1.3 Get the unique ID of the service account
+
+1. In the **Service Accounts** list, click on the service account you just created
+2. In the **Details** tab, locate the **Unique ID** under the service account details
+3. Copy this **Unique ID** (you'll need it in the next step)
+
+#### 1.4 Create a JSON key for the service account
+
+1. While still on your service account page, go to the **Keys** tab
+2. Click **Add Key** > **Create new key**
+3. Select **JSON** as the key type
+4. Click **Create**
+5. The JSON key file will be downloaded automatically (save it securely)
+
+#### 1.5 Enable domain-wide delegation
+
+1. Go to your [Google Workspace Admin Console](https://admin.google.com/) (requires super administrator access)
+2. Navigate to **Main menu** > **Security** > **Access and data control** > **API controls**
+3. In the **Domain wide delegation** section, click **Manage Domain Wide Delegation**
+4. Click **Add new**
+5. Configure the delegation:
+    - **Client ID**: Paste the unique ID from step 1.3
+    - **OAuth scopes**: Enter the following scope (this grants read-only access to group information): `https://www.googleapis.com/auth/cloud-identity.groups.readonly`
+6. Click **Authorize**
+
+#### 1.6 Configure Google Workspace OIDC in Livebook Teams
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/dNUcRD0A6kU?si=eNQ55-Aeg4I8PPgy" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+1. Log in to Livebook Teams
+2. Go to the **Authentication** panel (requires "admin" role in the organization)
+3. Click **Add OIDC SSO** and provide the following details:
+    - **Name**: A display name for your OIDC provider (e.g., Google Workspace)
+    - **Discovery URL**: `https://accounts.google.com/.well-known/openid-configuration`
+    - **Admin E-mail**: Email address of a Super Admin user of your Google Workspace (e.g., `[email protected]`). This user will be impersonated by the
+  service account to read group memberships, but access is limited to the scopes authorized in step 1.5.
+    - **Allowed domains**: Your Google Workspace domain(s), one per line if multiple (e.g., `yourcompany.com`)
+    - **Service Account JSON Key**: Paste the entire contents of the JSON key file from step 1.4
+    - **Enable this SSO provider**: Make sure this option is enabled
+4. Save
+
+<!-- tabs-close -->
+
+### 2. Configure your deployment group to authenticate via Livebook Teams
 
 To enable OIDC authentication, your deployment group must be configured to use authentication via Livebook Teams.
 
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/27GImleM3MQ?si=jlsa7cGvIgnM4xmN" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-In order to do so, follow these steps:
+To do so, follow these steps:
 
 1. Log in to Livebook Teams
 2. Navigate to the **Deployments** panel