docs: Add initial docs for Nested Access Lists

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

@@ -11,4 +11,6 @@ traits, which then tie easily back into Teleport's existing RBAC system.
 
 [Getting Started with Access Lists](./access-lists/guide.mdx)
 
+[Nested Access Lists](./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,88 @@
+---
+title: Nested Access Lists
+description: Learn how to use nested Access Lists to manage complex permissions and grant inheritance in Teleport.
+---
+
+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
+
+## Prerequisites
+
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
+
+- (!docs/pages/includes/tctl.mdx!)
+- A user with the `editor` role or equivalent permissions to 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` to add to the Access List.
+- At least one application or resource to grant access to.
+
+## What Are Nested Access Lists?
+
+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.
+
+### How Inheritance Works
+
+- **Membership Inheritance**: If Access List B is added as a member of Access List A,
+all users who are members of Access List B inherit Access List A's member grants (roles and traits).
+- **Ownership Inheritance**: If Access List B is added as an owner of Access List A,
+all users who are members of Access List B inherit Access List A's owner grants, and
+can perform owner actions on Access List A, such as modifying it or managing its members.
+
+Inheritance is recursive – members of a child Access List 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).
+
+## Creating a Nested Access List
+
+Let's walk through an example of creating a nested Access List and establishing inheritance.
+
+### Step 1/4. Create Parent 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 for the parent Access List. For example:
+
+- **Title**: Parent Access List
+- **Deadline for First Review**: Select a future date.
+- **Member Grants**: Add roles or traits that you want members to inherit, such as the `access` role.
+- **Owners**: Add yourself or any appropriate users as owners.
+- **Members**: Leave this empty for now, as we'll add a child Access List as a member later.
+
+Click "Create Access List" to save the new Access List.
+
+### Step 2/4. Create Child Access List
+
+From the "Access Lists" page, create another Access List to serve as the child Access List. For example:
+
+- **Title**: Child Access List
+- **Deadline for First Review**: Select a future date.
+- **Member Grants**: Leave this empty for now, as the child 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 child Access List.
+
+### Step 3/4. Add Child Access List as a Member
+
+To establish inheritance, we need to add the child Access List as a member of the parent Access List.
+Navigate to the "Parent Access List" from the "Access Lists" page, and click "Enroll New Members or Access Lists".
+Search for and select the child Access List, optionally set an expiry date for the membership,
+and click "Enroll New Members" to add it as a member.
+
+### Step 4/4. Verifying Inherited Permissions
+
+To confirm that members of the child Access List have inherited member grants from the parent, 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 the child Access List and the parent Access List. For example, if a Teleport Application Service
+instance with the debugging application enabled is set up, and the `access` role is granted through the parent,
+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.

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,7 +164,7 @@ spec:
     roles:
     - required_role1
     traits:
-      required_trait1: 
+      required_trait1:
       - required_value1
 ```