Skip to main content

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

Start your free trial

Creating an Access List for Just-in-Time Access

Report an Issue

The Just-in-Time Access Guide creates an Access List whose members are required to request access to a defined set of resources, rather than being granted that access automatically. The list's members submit an Access Request; the list's owners review and approve or deny it. Once approved, the member receives temporary access bounded by the request's TTL, capped by the member's remaining Teleport session.

In this guide, you will:

  • Decide when a Just-in-Time Access List is the right fit
  • Create one with the Teleport Web UI, tctl, or Terraform
  • Verify the request-and-approval experience as a member

When to use this flow​

Use a Just-in-Time Access List when:

  • The resources are sensitive enough that members should justify each access event.
  • You want a clear audit trail of who requested what, when, and who approved it.
  • You want a single list to govern who can request the access, with periodic reviews so the membership is reaffirmed rather than left to drift.
  • You'd rather have Teleport generate the supporting roles than write role specs by hand.

If members instead need access immediately on login for the duration of their session, use the Standing Access Guide instead.

Prerequisites​

  • A running Teleport Enterprise (v18.8.0 or higher) cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients, required only if creating the list with tctl or Terraform.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025

  • At least one user who will be a member of the list, preferably a user with no access to resources to verify the access flow later.

  • At least one resource enrolled in the cluster for the Access List to grant access to.

  • Permissions to create Access Lists, users, and roles. These 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

Step 1/2. Create the Access List​

Choose how to create the list.

In the Teleport Web UI, hover over Add New from the sidebar menu then click Access List.

Enter a name and optional description for the list.

Click Just-in-Time Access Guide and click Start Guide.

The guide steps you through:

  1. Define Access to Resources — for each resource type, specify the matching criteria. Most resource types are matched by labels; others may ask you to select the resource itself. Members can request access to anything that matches.

    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 — for resource types that need them (e.g. SSH logins, database users, Kubernetes users/groups, etc.), specify which principals members can use to connect once their request is approved.

  3. Basic Information — confirm the name and description of the Access List, and select the next review date. Periodic reviews are how list owners reaffirm that the right members are still on the list.

  4. Define Membership — add the users who should be eligible to request access through this list.

  5. Define Ownership — add the users responsible for managing the list, reviewing membership, and reviewing Access Requests submitted through this list.

At the final Deployment step, click Create Access List Now. The list is created directly via the Teleport API and is immediately active.

Editing the supporting roles

However you created the list, keep the supporting roles' names and their teleport.internal/access-list-preset* labels unchanged. Both the Web UI Access List editor and tctl acl update rely on them to recognize which roles belong to this Access List.

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. It updates the supporting roles for you.
  • Terraform — rerun tctl acl update with the resource flags you want and --output terraform to regenerate the configuration, then apply it.

Both tools support only a limited subset of role fields. If the roles end up outside that subset, neither can change the list's grants — the Web UI editor can no longer parse them, and tctl acl update rejects them rather than silently dropping the fields you added. From that point on you must manage the roles directly for the rest of the Access List's life.

Step 2/2. Verify the request flow​

Log in as one of the members you added. The resources the list covers should appear in the resource list with a Request Access button rather than a direct connect button.

  1. Submit a request for one of the resources, optionally providing a reason.
  2. Log in as one of the owners and approve the request. (The JIT preset grants owners a reviewer role automatically, which is what lets them approve.)
  3. Back as the member, assume the approved request. You now have temporary access to the resource; once the request expires or your session ends, the access is gone.

Next steps​