OIDC SSO docs (#2919)

Co-authored-by: José Valim <jose.valim@dashbit.co>

docs/authentication.md

@@ -2,11 +2,23 @@
 
 Livebook has three levels of authentication:
 
-  * Instance authentication: this authenticates the user on all routes of your Livebook instance, including deployed notebooks and the admin section. If you are deploying your Livebook instances with [Livebook Teams](https://livebook.dev/teams), all instances include Livebook Teams authentication by default. You can also manually configure your Livebook instance to have their own authentication, see the "Airgapped Authentication" section.
+  * **Instance authentication**: this authenticates the user on all routes of your Livebook instance, including deployed notebooks and the admin section. We provide a variety of authentication options here, including Single Sign On (SSO) and domain-based authentication via [Livebook Teams](https://livebook.dev/teams), as well as Zero Trust Authentication for airgapped environments. See the "Instance authentication" section for more information.
 
-  * Admin authentication: this authenticates access to Livebook admin interface, where users can create, write, and manage notebooks. Both password and token authentication are available. See the next section for more information.
+  * **Admin authentication**: this authenticates access to Livebook admin interface within an instance, where users can create, write, and manage notebooks. Both password and token authentication are available. See the ["Admin authentication"](#admin-authentication) section for more information.
 
-  * Deployed notebook passwords: additionally, when deploying notebooks as applications, each application may be password protected with a unique password. Only users authenticated as admin or with the password will be able to access them.
+  * **Deployed notebook passwords**: additionally, when deploying notebooks as applications, each application may be password protected with a unique password. Only users authenticated as admin or with the password will be able to access them.
+
+## Instance authentication
+
+When using [Livebook Teams](https://livebook.dev/teams), you can easily deploy instances of Livebook to run as application servers or as development servers. Those instances will, by default, use Livebook Teams to authenticate. The following authentication methods are supported by Livebook Teams:
+
+* **Livebook Teams account**: allow members of your Livebook Teams organization to authenticate using their Livebook Teams accounts.
+
+* **Email domain**: allow users to authenticate using email accounts from specific domains, such as your company’s Google Workspace domain.
+
+* **[OpenID Connect Single Sign-On (SSO)](/oidc_sso.html)**: Allow users to authenticate via an OpenID Connect Single Sign-On provider, such as Okta, Microsoft Entra or Keycloak.
+
+If your application servers must run in an airgapped environments and cannot reach out to Livebook Teams servers, we also provide a variety of options that can be configured directly in your Dockerfiles. See the "Airgapped Authentication" section in the sidebar.
 
 ## Admin authentication
 
@@ -14,4 +26,4 @@ Livebook's default admin authentication method is token authentication. A token
 
 You may optionally enable password-based authentication by setting the environment variable `LIVEBOOK_PASSWORD` on startup or deployment. It must be at least 12 characters.
 
-To disable authentication altogether, you may set the environment variable `LIVEBOOK_TOKEN_ENABLED` to `false`.
+To disable admin authentication, you may set the environment variable `LIVEBOOK_TOKEN_ENABLED` to `false`.

docs/teams/oidc_sso.md

@@ -0,0 +1,66 @@
+# OIDC SSO (OpenID Connect Single Sign-On)
+
+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)
+
+## 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
+
+To integrate Livebook Teams with your OIDC SSO provider, follow these steps.
+
+### 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`
+- **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
+
+<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
+3. Click **Add OIDC SSO** and provide the following details:
+	- **Name**: A display name for your OIDC provider (e.g., Okta, Microsoft Entra, Keycloak).
+	- **Discovery URL**: Use the discovery URL retrieved from your IdP.
+	- **Client ID**: Use the Client ID retrieved from your IdP.
+	- **Client Secret**: Use the Client Secret retrieved from your IdP.
+	- **Enable this SSO provider**: Make sure this option is enabled.
+4. Save
+
+### 3. 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:
+
+1. Log in to Livebook Teams.
+2. Navigate to the **Deployments** panel.
+3. Click **Edit** on the deployment group where you want to enable authentication.
+4. Ensure that **Authenticate via Livebook Teams** is enabled.
+5. Save your changes.
+
+### Test the integration with your OIDC IdP
+
+To verify the integration is working, follow these steps:
+
+1. Navigate to an application deployed in a deployment group configured for OIDC authentication.
+2. The app server will redirect you to Livebook Teams for authentication.
+3. On the authentication page, you will see an option to sign in using your configured OIDC provider.
+4. Click the name of your OIDC SSO configuration and follow the authentication steps provided by your IdP.
+5. Once authentication is complete, the IdP will redirect you back to your app server, and you will be successfully signed in.

mix.exs

@@ -256,6 +256,7 @@ defmodule Livebook.MixProject do
       "docs/teams/intro_to_teams.md",
       "docs/teams/shared_secrets.md",
       "docs/teams/shared_file_storages.md",
+      {"docs/teams/oidc_sso.md", title: "OIDC SSO"},
       "docs/authentication/basic_auth.md",
       "docs/authentication/cloudflare.md",
       "docs/authentication/google_iap.md",

mix.lock

@@ -23,13 +23,13 @@
   "jsx": {:hex, :jsx, "3.1.0", "d12516baa0bb23a59bb35dccaf02a1bd08243fcbb9efe24f2d9d056ccff71268", [:rebar3], [], "hexpm", "0c5cc8fdc11b53cc25cf65ac6705ad39e54ecc56d1c22e4adb8f5a53fb9427f3"},
   "kubereq": {:hex, :kubereq, "0.3.2", "e425dd94bd74b6510dc45a9557d9378d3fd6ca0ea3ebe0dad2a9c85a08c2e20a", [:mix], [{:fresh, "~> 0.4.4", [hex: :fresh, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}, {:mint, "~> 1.0", [hex: :mint, repo: "hexpm", optional: false]}, {:mint_web_socket, "~> 1.0", [hex: :mint_web_socket, repo: "hexpm", optional: false]}, {:pluggable, "~> 1.0", [hex: :pluggable, repo: "hexpm", optional: false]}, {:req, "~> 0.5.0", [hex: :req, repo: "hexpm", optional: false]}, {:yaml_elixir, "~> 2.0", [hex: :yaml_elixir, repo: "hexpm", optional: false]}], "hexpm", "d13293ac66bbfe7ac238881ac0404662af5a01f96f9325dd556594fd858f2a3e"},
   "makeup": {:hex, :makeup, "1.2.1", "e90ac1c65589ef354378def3ba19d401e739ee7ee06fb47f94c687016e3713d1", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d36484867b0bae0fea568d10131197a4c2e47056a6fbe84922bf6ba71c8d17ce"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
-  "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
+  "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},
+  "makeup_erlang": {:hex, :makeup_erlang, "1.0.2", "03e1804074b3aa64d5fad7aa64601ed0fb395337b982d9bcf04029d68d51b6a7", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "af33ff7ef368d5893e4a267933e7744e46ce3cf1f61e2dccf53a111ed3aa3727"},
   "mime": {:hex, :mime, "2.0.6", "8f18486773d9b15f95f4f4f1e39b710045fa1de891fada4516559967276e4dc2", [:mix], [], "hexpm", "c9945363a6b26d747389aac3643f8e0e09d30499a138ad64fe8fd1d13d9b153e"},
   "mint": {:hex, :mint, "1.6.2", "af6d97a4051eee4f05b5500671d47c3a67dac7386045d87a904126fd4bbcea2e", [:mix], [{:castore, "~> 0.1.0 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:hpax, "~> 0.1.1 or ~> 0.2.0 or ~> 1.0", [hex: :hpax, repo: "hexpm", optional: false]}], "hexpm", "5ee441dffc1892f1ae59127f74afe8fd82fda6587794278d924e4d90ea3d63f9"},
   "mint_web_socket": {:hex, :mint_web_socket, "1.0.4", "0b539116dbb3d3f861cdf5e15e269a933cb501c113a14db7001a3157d96ffafd", [:mix], [{:mint, ">= 1.4.1 and < 2.0.0-0", [hex: :mint, repo: "hexpm", optional: false]}], "hexpm", "027d4c5529c45a4ba0ce27a01c0f35f284a5468519c045ca15f43decb360a991"},
   "nimble_options": {:hex, :nimble_options, "1.1.1", "e3a492d54d85fc3fd7c5baf411d9d2852922f66e69476317787a7b2bb000a61b", [:mix], [], "hexpm", "821b2470ca9442c4b6984882fe9bb0389371b8ddec4d45a9504f00a66f650b44"},
-  "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.4.2", "8efba0122db06df95bfaa78f791344a89352ba04baedd3849593bfce4d0dc1c6", [:mix], [], "hexpm", "4b21398942dda052b403bbe1da991ccd03a053668d147d53fb8c4e0efe09c973"},
   "nimble_pool": {:hex, :nimble_pool, "1.1.0", "bf9c29fbdcba3564a8b800d1eeb5a3c58f36e1e11d7b7fb2e084a643f645f06b", [:mix], [], "hexpm", "af2e4e6b34197db81f7aad230c1118eac993acc0dae6bc83bac0126d4ae0813a"},
   "phoenix": {:hex, :phoenix, "1.7.18", "5310c21443514be44ed93c422e15870aef254cf1b3619e4f91538e7529d2b2e4", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 2.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", optional: false]}, {:phoenix_view, "~> 2.0", [hex: :phoenix_view, repo: "hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.7", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:plug_crypto, "~> 1.2 or ~> 2.0", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:websock_adapter, "~> 0.5.3", [hex: :websock_adapter, repo: "hexpm", optional: false]}], "hexpm", "1797fcc82108442a66f2c77a643a62980f342bfeb63d6c9a515ab8294870004e"},
   "phoenix_ecto": {:hex, :phoenix_ecto, "4.6.3", "f686701b0499a07f2e3b122d84d52ff8a31f5def386e03706c916f6feddf69ef", [:mix], [{:ecto, "~> 3.5", [hex: :ecto, repo: "hexpm", optional: false]}, {:phoenix_html, "~> 2.14.2 or ~> 3.0 or ~> 4.1", [hex: :phoenix_html, repo: "hexpm", optional: true]}, {:plug, "~> 1.9", [hex: :plug, repo: "hexpm", optional: false]}, {:postgrex, "~> 0.16 or ~> 1.0", [hex: :postgrex, repo: "hexpm", optional: true]}], "hexpm", "909502956916a657a197f94cc1206d9a65247538de8a5e186f7537c895d95764"},