diff --git a/docs/images/oidc_groups_auth.png b/docs/images/oidc_groups_auth.png new file mode 100644 index 000000000..c6bb478f2 Binary files /dev/null and b/docs/images/oidc_groups_auth.png differ diff --git a/docs/teams/intro_to_teams.md b/docs/teams/intro_to_teams.md index 865d071d2..4f3b4f80c 100644 --- a/docs/teams/intro_to_teams.md +++ b/docs/teams/intro_to_teams.md @@ -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) diff --git a/docs/teams/oidc_groups.md b/docs/teams/oidc_groups.md new file mode 100644 index 000000000..060b55f91 --- /dev/null +++ b/docs/teams/oidc_groups.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 diff --git a/mix.exs b/mix.exs index fb8e22c06..fb5ee6ea6 100644 --- a/mix.exs +++ b/mix.exs @@ -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",