Docs for OIDC groups authorization (#2996)

Author: hugobarauna

docs/images/oidc_groups_auth.png

@@ -11,7 +11,7 @@ Besides deployment automation, it also offers the following features:
 	- [Email-domain (Google, Microsoft, etc)](email_domain.md)
 	- [OIDC (Okta, Microsoft Entra, etc)](oidc_sso.md)
 - Authorization
-	- based on groups from an OIDC identity provider
+	- [based on groups from an OIDC identity provider (Okta, Microsoft Entra, etc)](oidc_groups.md)
 - [Shared Livebook secrets](shared_secrets.md)
 - [Shared Livebook file storages](shared_file_storages.md)
 

docs/teams/intro_to_teams.md

@@ -0,0 +1,88 @@
+# OIDC groups authorization
+
+Livebook Teams allows you to control access to your app servers and Livebook apps based on group membership in your OIDC identity provider (IdP).
+
+![](images/oidc_groups_auth.png)
+
+> #### Livebook version requirement {: .info}
+> Requires Livebook v0.16 or newer.
+
+## Overview
+
+OIDC groups authorization enables you to:
+
+- Restrict access to your Livebook apps and app servers based on group membership
+- Control which users can access specific apps using slug prefix filtering
+- Integrate seamlessly with your existing OIDC SSO provider (Okta, Microsoft Entra, etc.)
+
+## Prerequisites
+
+Before configuring OIDC groups authorization, ensure you have:
+
+1. **Configured an OIDC provider** in your Livebook Teams organization. If you haven't done this yet, follow the instructions in our [OIDC SSO documentation](oidc_sso.md).
+
+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/)
+
+## Configuration
+
+### 1. Enable authorization via OIDC SSO groups
+
+To enable authorization via OIDC SSO groups for a deployment group:
+
+1. Log in to Livebook Teams
+2. Navigate to the **Deployments** panel
+3. Click **Edit** on the deployment group where you want to enable authorization
+4. Go to the **IAM** section (requires "admin" role in the organization)
+5. Ensure that **Authenticate via Livebook Teams** is enabled
+6. Enable **Authorize via OIDC SSO groups**
+
+### 2. Add group authorization
+
+Once authorization is enabled, you can add group access rules:
+
+1. Click the **Add group** button
+2. Select one of your configured OIDC identity providers
+3. Enter the name of a group from your identity provider
+4. Choose the **Access type**:
+   - Full access
+   - Slug prefix access
+5. Click the **Add group** button to save the rule
+
+You can add multiple groups with different access types to configure your authorization strategy.
+
+## Access types explained
+
+### Full access
+
+Users who belong to groups with full access can access:
+- The app server admin interface*
+- All Livebook apps deployed to this deployment group
+
+**Notice that [Admin authentication](authentication.md#admin-authentication) configs will also apply if configured.*
+
+### Slug prefix access
+
+Users who belong to groups with slug prefix access can only access Livebook apps whose URL slugs start with the specified prefix.
+
+For example, with the slug prefix "**finance-**", users can access an app whose slug is "**finance-**budget", but not one with the slug "**hr-**budget".
+
+This allows you to create role-based access control based on your organization's existing group structure.
+
+## Testing the Configuration
+
+To verify the configuration is working:
+
+1. Sign out of any current Livebook Teams sessions
+2. Navigate to an app server or Livebook app in the deployment group where you've enabled OIDC groups authorization
+3. You will be prompted to authenticate through your OIDC provider
+4. After authentication, the system will check your group membership
+5. You will only be granted access if you belong to one of the configured groups with appropriate permissions
+
+## Troubleshooting
+
+If users are experiencing access issues:
+
+1. Verify the group name matches exactly as defined in your IdP (group names are case-sensitive)
+2. Check that the user is a member of the specified group in your IdP
+3. Ensure your OIDC provider is properly set up to include group names inside the ID token

docs/teams/oidc_groups.md

@@ -257,10 +257,11 @@ defmodule Livebook.MixProject do
       "docs/deployment/fips.md",
       "docs/deployment/nginx_https.md",
       "docs/teams/intro_to_teams.md",
-      "docs/teams/shared_secrets.md",
-      "docs/teams/shared_file_storages.md",
       {"docs/teams/email_domain.md", title: "Email domain auth"},
       {"docs/teams/oidc_sso.md", title: "OIDC SSO"},
+      "docs/teams/oidc_groups.md",
+      "docs/teams/shared_secrets.md",
+      "docs/teams/shared_file_storages.md",
       "docs/authentication/basic_auth.md",
       "docs/authentication/cloudflare.md",
       "docs/authentication/google_iap.md",