diff --git a/docs/images/auth_via_teams_oidc.png b/docs/images/auth_via_teams_oidc.png new file mode 100644 index 000000000..c405d386c Binary files /dev/null and b/docs/images/auth_via_teams_oidc.png differ diff --git a/docs/teams/oidc_groups.md b/docs/teams/oidc_groups.md index e4da4fa17..aa09dc2d5 100644 --- a/docs/teams/oidc_groups.md +++ b/docs/teams/oidc_groups.md @@ -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 diff --git a/docs/teams/oidc_sso.md b/docs/teams/oidc_sso.md index a08edbac7..8f26ae9f7 100644 --- a/docs/teams/oidc_sso.md +++ b/docs/teams/oidc_sso.md @@ -2,10 +2,10 @@ 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 @@ -13,17 +13,23 @@ Here's a quick demo of the feature working. -## Configuration +## 1. OIDC configurations To integrate Livebook Teams with your OIDC SSO provider, follow these steps. -### 1. Register with your OIDC Provider + + +### 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: @@ -31,7 +37,7 @@ Once that’s done, you should retrieve the following information from the regis - **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 @@ -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 + + + +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., `admin@yourcompany.com`). 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 + + + +### 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. -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