{"token_count": 2152} # Getting Started with Access Lists Identity Governance is available only with Teleport Enterprise. This guide walks you through the Teleport Web UI to: - Create an Access List - Assign a member to it - Verify permissions granted through the list membership If you'd rather manage Access Lists as code, follow the [Access Lists with Terraform and Kubernetes Operator](https://goteleport.com/docs/configuration/resource-guides/access-list.md) guide instead. ## Prerequisites - A running Teleport Enterprise (v18.8.0 or higher) cluster. If you don't have one yet, [sign up](https://goteleport.com/signup) for a free trial. * Permissions to create Access Lists, users, and roles. These are included in the preset [`editor`](https://goteleport.com/docs/reference/access-controls/roles.md#preset-roles) role, or you can copy and paste the following into your own role: ``` allow: rules: - resources: - access_list - user - role verbs: - read - list - create - update - delete ``` ## Step 1/4. Enroll a test resource We need at least one resource on the cluster to grant access to. If you already have a resource enrolled that you can use for testing, skip to the next step. Otherwise, follow the [Connect Infrastructure](https://goteleport.com/docs/get-started/connect.md) guide to enroll a host through the Web UI's guided setup. The linked page uses an Ubuntu server as its example, but the same flow works for your own machine (Linux or macOS) — just pick your OS during the guided setup and run the install command it gives you. --- TIP When the guided setup asks you to add labels, add at least one — for example, `env: test`. We'll use this label in Step 3 to select the host. (You can also match all hosts with a `*` wildcard, but using a real label is closer to how you'd build an Access List in practice.) --- The rest of this guide assumes you've enrolled an SSH server. ## Step 2/4. Create a test user We need to create a simple test user that has only the `requester` role, which has no default access to anything within a cluster. This user will only be used for the purposes of this guide, so you may use another user if you so choose. If you would rather use your own user, skip to the next step. From the sidebar menu, click **Zero Trust Access** > **Users** > **Enroll Users**. Fill in `test-user` as the name and select `requester` as the role. ![Create Test User](/docs/assets/images/create-test-user-337acc26c6375ba511093dba6140a79b.png) Submit the form to create the user, then navigate to the provided URL in order to set up the credentials for your test user. Try logging into the cluster with the test user to verify that no resources show up in the resources page. ## Step 3/4. Create an Access List Next, we'll create an Access List that grants its members access to the SSH host we enrolled in Step 1. Login as the admin user mentioned in the prerequisites. From the sidebar menu, hover over **Add New** then click **Access List**. Enter `test-list` as the Access List name, optionally add a description, then select **Standing Access Guide** — this is the flow that grants members access on login, which is what we want for this tutorial. (Other options: [Just-in-Time Access](https://goteleport.com/docs/identity-governance/access-lists/jit-access-list.md) makes resources *requestable* instead of granted automatically, and the [Custom Form](https://goteleport.com/docs/identity-governance/access-lists/custom-access-list.md) lets you assign existing roles directly without the guided flow.) Click **Start Guide**. --- PREFER TERRAFORM? As you fill out the guided flow, a Terraform panel on the side mirrors your input live. At the final **Deployment** step you can choose to apply the list with Teleport directly or follow the in-UI instructions to apply it with Terraform. --- ### 1. Define Access to Resources - Click **Server** from the resource-type column on the left. - Click the `env: test` label next to your host (or whichever label you set in Step 1) to select it. - If you didn't add a label, type `*` into the label input box and press **Enter** to match all servers. This gives members of the list access to SSH servers matching the `env: test` label (or any SSH server, if you used `*`). --- PREVIEWING RESOURCES After defining access for a resource type, the UI shows a preview of matching resources. The preview is limited by your own role permissions — members may be granted access to additional resources that aren't visible to you. --- ### 2. Define Resource Identities or Principals - Under Server Identities **Logins**, add the OS user(s) you want members to be able to log in as on the host (for example, `ubuntu` on a Linux server or your local username on macOS). Note: this screen only asks for SSH logins because Server was the only resource type you selected in the previous step. ### 3. Basic Information - Confirm the title and description. - Select a date in the future for the next review. ### 4. Define Membership - Add your test user as a member. - Optionally, expand **Optional Advanced Settings** and select `requester` as a required role. The required role ensures any member of the list must hold `requester` to be granted access; if a member loses the role later, they will not be granted the access described in the list. ### 5. Define Ownership - Add your admin user as an eligible owner. - Optionally, expand **Optional Advanced Settings** and select `editor` as a required role. The required role ensures any owner must hold `editor` to manage the list; if an owner loses the role later, they remain reflected as an owner but cannot manage the list. ### 6. Deployment - Review the summary and click **Create Access List Now**. --- EDITING THE GENERATED ROLES Avoid directly modifying the roles the guided flow creates for this Access List. Keep their names and their `teleport.internal/access-list-preset*` labels unchanged — the Web UI relies on both to recognize them as the roles generated for this Access List. To change what the list grants, update it through the Web UI Access List editor: 1. From the sidebar menu, click **Identity Governance** > **Access Lists**. 2. Click on the target Access List. 3. Click the **Access Definition** tab. 4. Click **Edit Access**. If you created the list with Terraform produced by the Web UI editor, you can still use the web editor to update the Access List and copy the updated Terraform it generates. Editing the roles directly (via Terraform, `tctl`, or the role editor) may make the Access List editor in the Web UI unable to parse them (only a limited subset of role fields is supported by the editor) — at which point you can no longer use the Web UI editor to change the list's grants, and must update the roles directly for the rest of the Access List's life. --- ## Step 4/4. Log in as the test user Log in as the test user in the Web UI. You should see the SSH server from Step 1 in the **Resources** list. Click **Connect**, then click one of the logins you allowed in the **Define Resource Identities or Principals** step to SSH into the server. ## Cleanup (optional) If you'd like to remove the SSH server you enrolled in Step 1, follow [Uninstall Teleport](https://goteleport.com/docs/installation/uninstall-teleport.md#step-13-stop-any-running-teleport-processes). Once the agent is stopped, Teleport automatically removes the server from the resource list after a few minutes. ## Next steps - Read more about the flow you just used in [Standing Access Lists](https://goteleport.com/docs/identity-governance/access-lists/standing-access-list.md). - Create an Access List whose members can [request temporary access to resources](https://goteleport.com/docs/identity-governance/access-lists/jit-access-list.md) instead of receiving them on login. - Create an Access List by assigning existing roles directly with the [Custom Form](https://goteleport.com/docs/identity-governance/access-lists/custom-access-list.md). - Read [Creating Access Lists with IaC](https://goteleport.com/docs/configuration/resource-guides/access-list.md) for instructions on managing Access Lists with the Teleport Terraform provider and Kubernetes operator. - Familiarize yourself with the CLI tooling available for managing Access Lists in the [reference](https://goteleport.com/docs/reference/access-controls/access-lists.md). - Learn how to work with nested Access Lists in the [nested Access Lists guide](https://goteleport.com/docs/identity-governance/access-lists/nested-access-lists.md).