Skip to main content

Identity Governance is available only with Teleport Enterprise. Start your free trial.

Start your free trial
Version: 18.x

Getting Started with Access Lists

Report an Issue

In this guide, you will use 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 guide instead.

Skill Available

Teleport Access List Review

This skill helps you perform periodic access list reviews in Teleport. It fetches lists due for audit, assesses risk, auto-recertifies low-risk ones (with your approval), and flags higher-risk ones for manual review in the web UI.

View Raw Skill
Skill Available

Teleport Access List Lifecycle

Use this skill to give users access to specific Teleport resources. Browse available servers, databases, applications, Kubernetes clusters, and more, choose which ones and how users connect to them, then create, update, or retire the access list that grants that access.

View Raw Skill

Prerequisites​

  • A running Teleport Enterprise (v18.8.0 or higher) cluster. If you don't have one yet, sign up for a free trial.
  • Permissions to create Access Lists, users, and roles. If you use the local Terraform workflow, you also need permission to create temporary bots and provisioning tokens. These permissions are included in the preset editor 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

  # Required only when using the local Terraform workflow.
  - resources:
    - bot
    verbs:
    - create
  - resources:
    - token
    verbs:
    - create
    - update

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 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.

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 makes resources requestable instead of granted automatically, and the Custom Form 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 supporting roles

Avoid directly modifying the supporting roles for this Access List. Keep their names and their teleport.internal/access-list-preset* labels unchanged — the Web UI Access List editor and tctl acl update rely on both to recognize them.

To change what the list grants:

  • Web UI — from the sidebar menu, click Identity Governance > Access Lists, click the target Access List, open the Access Definition tab, then click Edit Access.
  • tctl — rerun tctl acl update with the resource flags you want.
  • Terraform — rerun tctl acl update with the resource flags you want and --iac terraform to regenerate the configuration, then apply it.

The Web UI editor and tctl acl update support only a limited subset of role fields. Editing the roles directly (via Terraform, tctl, or the role editor) may make them incompatible with those tools. From that point on you must manage 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.

Once the agent is stopped, Teleport automatically removes the server from the resource list after a few minutes.

Next steps​