Docs for app folders and authorization based on app folders (#3101)

docs/teams/app_folders.md

@@ -0,0 +1,49 @@
+# Organize Livebook Apps with folders
+
+App folders help you organize how apps are displayed on the `/apps` page of your [app server](/docs/teams/teams_concepts.md#app-server). Use them to group deployed apps so everyone can quickly find what matters.
+
+![Apps page with apps grouped by folders](images/apps_page_with_folders.png)
+
+This guide walks you through creating folders and assigning apps to them.
+
+## 1. Create an app folder
+
+Inside Livebook Teams:
+
+1. Navigate to the Apps page of your Teams organization dashboard at `https://teams.livebook.dev`
+  ![Apps page of an organization](images/empty_apps_page.png)
+2. Click **New folder**
+3. Give your folder a name and save it
+
+## 2. Assign apps to folders during deployment
+
+Inside Livebook:
+
+1. Open the notebook you plan to assign to a folder
+2. Click **App settings** in the sidebar
+3. In the **Folder** dropdown, choose a folder
+![App settings button](images/folder-in-app-settings.png)
+4. Save the app settings
+5. Click **Deploy with Livebook Teams** to apply the new folder settings
+
+The app will be placed in the selected folder once deployment completes. Until then, the folder assignment is only saved in the notebook's app settings.
+
+## 3. Browse and filter apps by folder
+
+Once you create folders, the `/apps` page of your Livebook app server shows apps grouped by folder.
+
+![Apps page with apps grouped by folders](images/apps_page_with_folders.png)
+
+## FAQ
+
+**I don't see the Folder dropdown in App settings, why?**
+
+Folders are only available for notebooks associated with a Teams workspace. Make sure your notebook is associated with a Teams workspace. To change this, open the notebook and update the workspace setting located directly below the notebook name.
+
+**Can I create folders from Livebook?**
+
+No. Folders are created in the Teams dashboard. Inside Livebook, you can pick from existing folders created inside your organization in Livebook Teams.
+
+**How to move an app to a different folder?**
+
+Open the notebook, change the folder, and redeploy the app.

docs/teams/intro_to_teams.md

@@ -9,6 +9,7 @@ Livebook Teams integrates with Livebook, offering the following feautures on top
 - Deploy notebooks as internal apps to your infrastructure
   - [Deploy Livebook apps from Livebook](deploy_app.md)
   - [Deploy Livebook apps from the CLI](deploy_via_cli.md)
+  - [Organize Livebook apps with folders](app_folders.md)
 - Deployment authorization
   - [Authorize who can deploy Livebook apps to your servers](deploy_permissions.md)
 - Authenticate who can can access your Livebook app servers and Livebook apps via multiple identity providers:

docs/teams/oidc_groups.md

@@ -1,18 +1,19 @@
 # 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).
+Livebook Teams allows you to control access to your Livebook [app servers](/docs/teams/teams_concepts.md#app-server) and Livebook apps based on group membership in your OIDC identity provider (IdP). This enables you to implement a Role-Based Access Control (RBAC) model for your Livebook deployment.
 
 ![](images/oidc_groups_auth.png)
 
 > #### Livebook version requirement {: .info}
-> Requires Livebook v0.16 or newer.
+> Requires Livebook v0.18 or newer.
 
 ## Overview
 
 OIDC groups authorization enables you to:
 
 - Restrict access to your Livebook apps and app servers based on group membership
-- Integrate seamlessly with your existing OIDC SSO provider (Okta, Microsoft Entra, etc.)
+- Limit access to apps that belong to specific [app folders](app_folders.md) so groups of users only have access to what they're authorized to see
+- Integrate seamlessly with your existing OIDC SSO provider (Okta, Microsoft Entra, Google etc.)
 
 ## Prerequisites
 
@@ -22,6 +23,8 @@ 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
+   - **Others**: Search your identity provider's documentation for how to add a groups claim to the ID token
 
 ## Configuration
 
@@ -43,19 +46,27 @@ 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. Click the **Add group** button to save the rule
+4. Choose the Access type for this group:
+   - Full access
+   - App folder 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.
+You can create multiple group authorizations with different access types to set up 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.*
+**Note that [Admin authentication](authentication.md#admin-authentication) configuration will also apply if configured.*
+
+### App folder access
+Users who belong to groups with app folder access can only see and open apps from the selected app folders.
+
+This allows you to implement role-based access control using groups from your identity provider.
 
 ## Testing the Configuration
 

mix.exs

@@ -265,6 +265,7 @@ defmodule Livebook.MixProject do
       {"docs/teams/deploy_app.md", title: "Deploy Livebook apps"},
       {"docs/teams/deploy_via_cli.md", title: "Deploy Livebook apps via CLI"},
       "docs/teams/deploy_permissions.md",
+      {"docs/teams/app_folders.md", title: "Organize apps with folders"},
       {"docs/teams/email_domain.md", title: "Email domain auth"},
       {"docs/teams/oidc_sso.md", title: "OIDC SSO"},
       "docs/teams/oidc_groups.md",