[v17] Add documentation for nested Access Lists (#48185)

* docs: Add initial docs for Nested Access Lists

docs: Use "real" access list names for scenario in guide

docs: Add detail on nested Access Lists with Okta/SICM sync

* Update docs/pages/admin-guides/access-controls/access-lists/nested-access-lists.mdx

Co-authored-by: Paul Gottschling <[email protected]>

* docs: Add warning to avoid `deny` rules in Access Lists

---------

Co-authored-by: Paul Gottschling <[email protected]>

docs/pages/admin-guides/access-controls/access-lists/access-lists.mdx

@@ -11,4 +11,6 @@ traits, which then tie easily back into Teleport's existing RBAC system.
 
 [Getting Started with Access Lists](guide.mdx)
 
+[Nested Access Lists](nested-access-lists.mdx)
+
 [Access List Reference](../../../reference/access-controls/access-lists.mdx)

docs/pages/admin-guides/access-controls/access-lists/guide.mdx

@@ -13,7 +13,6 @@ This guide will help you:
 (!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
 - (!docs/pages/includes/tctl.mdx!)
-- A running Teleport cluster.
 - A user with the preset `editor` role, which will have permissions to create Access Lists.
 
 ## Step 1/4. Setting up the Application Service on the cluster for testing
@@ -68,7 +67,7 @@ not be able to manage the list, though they will still be reflected as an owner.
 
 Under "Members" select `requester` as a required role, then add your test user to the access list. Similar to
 the owner requirements, this will ensure that any member of the list must have the `requester` role in order to
-be granted the access described in this list. If the user loses this role later, they will no be granted the
+be granted the access described in this list. If the user loses this role later, they will not be granted the
 roles or traits described in the access list.
 
 ![Add a member](../../../../img/access-controls/access-lists/add-member.png)
@@ -82,4 +81,5 @@ the cluster, and should be able to interact with it as expected.
 
 ## Next Steps
 
-- Familiarize yourself with the CLI tooling available for managing access lists in the [reference](../../../reference/access-controls/access-lists.mdx).
+- Familiarize yourself with the CLI tooling available for managing Access Lists in the [reference](../../../reference/access-controls/access-lists.mdx).
+- Learn how to work with nested Access Lists in the [nested Access Lists guide](./nested-access-lists.mdx).

docs/pages/admin-guides/access-controls/access-lists/nested-access-lists.mdx

@@ -0,0 +1,83 @@
+---
+title: Nested Access Lists
+description: Learn how to use nested Access Lists to manage complex permissions and grant inheritance in Teleport.
+---
+
+Nested Access Lists allow inclusion of an Access List as a member or owner of another Access List.
+This enables hierarchical permission structures where permissions can be inherited from multiple levels of
+parent Access Lists.
+
+This guide will help you:
+
+- Understand how nesting and inheritance work in Access Lists
+- Create a nested Access List
+- Verify inherited permissions granted through the nested Access List
+
+## How it works
+
+Let's break down inheritance in Access Lists. Imagine two Access Lists you might have in an organization:
+"Engineering Team" and "Production Access". "Engineering Team" represents a group of engineers, while
+"Production Access" is a higher-level Access List that grants access to production resources.
+
+- **Membership Inheritance**: If "Engineering Team" is added as a member of "Production Access",
+all users who are members of "Engineering Team" inherit member grants (roles and traits) from "Production Access".
+- **Ownership Inheritance**: If "Engineering Team" is added as an owner of "Production Access",
+all users who are members of "Engineering Team" inherit owner grants (roles and traits) from "Production Access", and
+can perform owner actions, such as modifying it or managing its members.
+
+Inheritance is recursive – members of "Engineering Team" can themselves be Access Lists
+with their own members, and so on. However, circular nesting is not allowed, and nesting is limited
+to a maximum depth of 10 levels.
+
+For more information, see the [Access Lists reference](../../../reference/access-controls/access-lists.mdx).
+
+## Prerequisites
+
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
+
+- (!docs/pages/includes/tctl.mdx!)
+- A user with the default `editor` role or equivalent permissions (ability to read, create, and manage Access Lists).
+- Familiarity with basic Access List concepts (see the [Getting Started with Access Lists guide](./guide.mdx)).
+- At least one user with only the `requester` role to add to the Access List.
+- At least one application or resource to grant access to.
+
+Let's walk through creating a nested Access List and establishing inheritance. In this example, we'll
+create a child Access List, "Engineering Team", which inherits permissions from a parent, "Production Access".
+
+## Step 1/3. Create child Access List
+
+In the Teleport Web UI, go to the "Identity" tab and select "Access Lists" from the sidebar.
+Click on "Create New Access List", and fill in the details:
+
+- **Title**: Engineering Team
+- **Deadline for First Review**: Select a future date.
+- **Member Grants**: Leave this empty, as the list will inherit the parent's member grants.
+- **Owners**: Add yourself or any appropriate users as owners.
+- **Members**: Add users who should be part of this Access List, such as `test-user`.
+
+Click "Create Access List" to save the Access List.
+
+## Step 2/3. Create parent Access List
+
+From the "Access Lists" page, click on "Create New Access List" and fill in the details for our parent list:
+
+- **Title**: Production Access
+- **Deadline for First Review**: Select a future date.
+- **Member Grants**: Add the `access` role.
+- **Owners**: Add yourself or any appropriate users as owners.
+- **Members**: Select our child Access List, 'Engineering Team', from the dropdown.
+
+Click "Create Access List" to save the Access List.
+
+## Step 3/3. Verifying inherited permissions
+
+To confirm that members of "Engineering Team" have inherited member grants from "Production Access", log in as a user
+who is a member of the child Access List (e.g., `test-user`). Verify that the user now has access to resources
+granted by both "Engineering Team" and "Production Access". For example, if a Teleport Application Service
+instance with the debugging application enabled is set up, and the `access` role is granted through "Production Access",
+the "dumper" app should be visible to the user.
+
+## Next Steps
+
+- Review the [Access Lists reference](../../../reference/access-controls/access-lists.mdx) for more detailed information on Access Lists' nesting and inheritance.
+- Learn how nested Access Lists work with Okta/SCIM synchronization in [Synchronization with Okta and SCIM](../../../enroll-resources/application-access/okta/sync-scim.mdx).

docs/pages/enroll-resources/application-access/okta/sync-scim.mdx

@@ -26,14 +26,14 @@ Teleport.
 
 ### Importing users
 
-During synchronization, the Okta integration will create Teleport user accounts 
+During synchronization, the Okta integration will create Teleport user accounts
 for all eligible Okta users, and clean up the Teleport accounts of any Okta users
 that have been deactivated. The list of "eligible Okta users" depends on the
-integration configuration. 
+integration configuration.
 
 If the Okta integration is configured to use a specific Okta application, then
-the Okta integration will consider any Okta user assigned to that Okta 
-application - either directly, or via group membership - as an "eligible user". 
+the Okta integration will consider any Okta user assigned to that Okta
+application - either directly, or via group membership - as an "eligible user".
 
 If no Okta application is to use is supplied, all enabled Okta organization
 users are considered "eligible".
@@ -54,7 +54,7 @@ administer and secure.
 
 The Teleport users created by the synchronization process or SCIM provisioning
 all inherit their username from the upstream Okta organization, and are given a
-default role of `okta-requester`. 
+default role of `okta-requester`.
 
 This Role allows the user to log into Teleport, but grants no default access to
 Teleport resources. The Teleport admin can use Access Requests and Access Lists
@@ -93,13 +93,13 @@ resources.
 
 ### Deleting Users
 
-In the case where
+Given a case where
  1. the synchronization process detects that an Okta user has been deactivated
-    or suspended, or 
- 1. the Okta organization explicitly disables the account via SCIM, 
- 
+    or suspended, or
+ 1. the Okta organization explicitly disables the account via SCIM,
+
 The Okta integration will immediately delete the corresponding Teleport
-account and create a temporary Teleport user lock. The user lock will 
+account and create a temporary Teleport user lock. The user lock will
  - terminate any active Teleport sessions, and
  - prevent the disabled user from accessing any Teleport resources with
    credentials issued before their Teleport account was deleted.
@@ -147,6 +147,53 @@ The synchronizer will create the following resources for each matched group or a
 It should be noted that the Access List sync waits until the Okta groups and Okta applications
 has finished syncing as Teleport resources, so it may not start synchronizing immediately on startup.
 
+### Handling nested Access Lists
+
+#### Synchronization from Teleport to Okta
+
+Teleport supports nested Access Lists, where an Access List can include other Access Lists as members,
+creating a hierarchical structure. However, Okta does not support nested groups.
+To accommodate this limitation, the synchronizer flattens nested Access Lists when synchronizing from Teleport to Okta.
+
+Members in Access Lists, from all levels of nesting, are aggregated into a single, flat list of members when
+synchronized to Okta. This ensures that all users who should have access according to the Teleport hierarchy
+are included in the corresponding Okta group or application.
+
+**Example**:
+  - **Teleport Structure**:
+    - **Access List A**:
+      - Members: User1
+      - Nested Members: Access List B
+    - **Access List B**:
+      - Members: User2, User3
+  - **Okta Representation**:
+    - Group/Application for Access List A:
+      - Members: User1, User2, User3
+
+By flattening the Teleport hierarchy, all users receive the permissions associated with the root-level Access List in Okta.
+
+#### Synchronization from Okta to Teleport
+
+When synchronizing from Okta to Teleport, the synchronizer handles the flattened structure from Okta
+by attempting to map it back to the Teleport hierarchy:
+
+- **Comparing with Teleport Hierarchy**: The flattened list of members from Okta is compared against the existing
+Access List hierarchy in Teleport.
+- **Adding New Members**:
+  - **New Users**: If there are new users added in Okta that are not present in the Teleport Access List hierarchy,
+  these users are added as members at the root-level Access List in Teleport.
+  - **Maintaining Hierarchy**: This approach maintains the hierarchical structure within Teleport while ensuring
+  that access changes made in Okta are reflected appropriately.
+- **Example**:
+  - **Okta Group/Application for Access List A**:
+    - Members: User1, User2, User3, User4 (User4 is a new member added in Okta)
+  - **Teleport Update**:
+    - **Access List A**:
+      - Members: User1, User4
+      - Nested Members: Access List B
+    - **Access List B**:
+      - Members: User2, User3
+
 #### Deletion of Access Lists
 
 Access Lists synchronized from Okta will automatically be deleted when there are no members assigned to them in

docs/pages/reference/access-controls/access-lists.mdx

@@ -29,10 +29,10 @@ to live on the order of hours or days.
 
 ## Access List Ownership
 
-Access List owners are Teleport users who are granted special privileges over
+Access List owners are Teleport users or nested Access Lists who are granted special privileges over
 an Access List. These owners are defined explicitly as part of the Access List, and
 must be added by a Teleport user who has RBAC access to access lists, which the preset `editor`
-role has.. Owners must meet requirements in order for their ownership to be effective.
+role has. Owners must meet requirements in order for their ownership to be effective.
 
 Provided owners meet requirements, owners are able to do the following:
 
@@ -46,14 +46,51 @@ and traits are granted by the Access List.
 
 ## Access List Membership
 
-Access List members are Teleport users who are granted the roles and traits specified
-by the Access List. Upon login, users will be granted these roles and traits along with
-their statically defined user permissions. These roles and traits will then tie into
-Teleport's existing RBAC system. Members can be optionally granted an expire date, after
-which their membership will no longer confer any grants to the user.
+Access List members are Teleport users or nested Access Lists who are granted the roles
+and traits specified by the Access List. Upon login, users will be granted these
+roles and traits along with their statically defined user permissions. These roles and
+traits will then tie into Teleport's existing RBAC system. Members can be optionally
+granted an expiry date, after which their membership will no longer confer any
+grants to the user.
 
 Members must meet requirements in order for their membership to be effective.
 
+## Nested Access Lists
+
+Access Lists can be nested within other Access Lists as members or owners. This enables
+hierarchical permission structures where permissions can be inherited from multiple levels of
+parent Access Lists. Inheritance is recursive – members of a child Access List can
+themselves be Access Lists with their own members, and so on.
+
+### Membership Inheritance
+
+If an Access List is a member of another Access List, members of the nested Access List will
+inherit the member grants (roles and traits) of the parent Access List.
+
+Users granted membership through inheritance must meet both the nested Access List's membership
+requirements, and the parent Access List's membership requirements in order for the
+membership to be valid.
+
+### Ownership Inheritance
+
+If an Access List is an owner of another Access List, members of the nested Access List will
+inherit the owner grants (roles and traits), as well as ownership of, the parent Access List.
+
+Users granted ownership through inheritance must meet both the nested Access List's
+membership requirements, and the parent Access List's ownership requirements in order
+for the ownership to be valid.
+
+### Limitations
+
+- **Circular Nesting**: Circular nesting is not allowed. Access Lists' membership and
+ownership cannot be self-referential, directly or indirectly.
+- **Nesting Depth**: Nesting is limited to a maximum depth of 10 levels. This means that
+a child Access List cannot be more than 10 levels removed from the root Access List in
+the hierarchy.
+- **Deletion**: Deleting Access Lists that are members or owners of other Access Lists
+is not allowed. Access Lists must be removed from all parent Access Lists before they
+can be deleted.
+
 ## Access List Auditing
 
 Access Lists must be defined with an audit frequency, which specifies how often the
@@ -91,12 +128,13 @@ spec:
       start: 336h # two weeks
     next_audit_date: "2025-01-01T00:00:00Z"
   description: "A description of the Access List and its purpose"
-  # owners are a list of Teleport users who own the Access List. Provided the owners
-  # meet the ownership requirements, these users can control membership requirements
-  # and membership to the Access List.
+  # owners are a list of Teleport users or Access Lists who own the Access List.
+  # Provided the owners meet the ownership requirements, these users can control
+  # membership requirements and membership to the Access List.
   owners:
   - description: test user 1
     name: teleport-admin
+    membership_kind: MEMBERSHIP_KIND_USER
   # ownership_requires defines roles and traits that are required for an owner to be
   # able to manage the Access List and its membership.
   ownership_requires:
@@ -116,7 +154,7 @@ spec:
     roles:
     - access
     traits:
-      trait1: 
+      trait1:
       - value1
   # membership_requires defines roles and traits that are required for a member
   # to be granted the above roles and traits. Even if a user has been added as a
@@ -126,10 +164,17 @@ spec:
     roles:
     - required_role1
     traits:
-      required_trait1: 
+      required_trait1:
       - required_value1
 ```
 
+## Access Lists and Deny Rules
+
+Use of [deny rules](./roles.mdx) in Access List roles is discouraged.
+Access Lists are not intended to be used as a tool for privilege reduction,
+and Teleport may assume it is safe to ignore Access Lists under certain conditions.
+Roles intended to reduce privileges should be assigned directly to users.
+
 ## Managing Access Lists from the CLI
 
 In addition to using the web UI, Access Lists can be created and managed from the CLI

docs/pages/reference/access-controls/roles.mdx

@@ -12,6 +12,7 @@ A Teleport role manages access by having two lists of rules: `allow` rules and
 
 - Nothing is allowed by default.
 - Deny rules get evaluated first and take priority.
+- Deny rules should be avoided on roles granted through Access Lists.
 
 You can use any of the following to manage Teleport roles and other dynamic
 resources:
@@ -571,7 +572,7 @@ attribute or OIDC claim called `trait`.
 
 You can specify an external trait in dot syntax if it begins with a letter and
 contains only letters, numbers, and underscores. Otherwise, you must use bracket
-syntax to specify a trait. 
+syntax to specify a trait.
 
 When using Azure AD or ADFS as your IdP, you must use bracket notation, as these
 IdPs assign attribute keys to URLs such as the following: