# Getting Started with Access Lists

This guide will help you:

- Create an Access List
- Assign a member to it
- Verify permissions granted through the list membership

## Prerequisites

- A running Teleport Enterprise cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

- The `tctl` and `tsh` clients.

  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:

     **Mac**

     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.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username:
  ```
  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  Cluster  teleport.example.com
  Version  19.0.0-dev
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
  ```
  If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions.
* 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

One of the easiest ways to get resources on the cluster for testing is to set up a Teleport Application Service instance with the debugging application enabled. To do this, add the following config to your `teleport.yaml` configuration:

```
app_service:
  enabled: true
  debug_app: true

```

And restart Teleport. The "dumper" app should show up in the resource list.

![Debug app](/docs/assets/images/debug-app-4dc7b6205e7dc4e79f36ec4f46c1a740.png)

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

To create a user, first navigate to Zero Trust Access in the left pane and click Users. Click on "Enroll Users" and fill in `test-user` as the name and select `requester` as the role.

![Create Test User](/docs/assets/images/create-test-user-337acc26c6375ba511093dba6140a79b.png)

Click "Save," and 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 a simple Access List that will grant the `access` role to its members. Login as the administrative user mentioned in the prerequisites. Click on "Add New" in the left pane, and then "Create an Access List."

![Navigate to create new Access List](/docs/assets/images/create-new-access-list-f60c5795ca9da285be0a09d1e9661da3.png)

Here, fill in a title, description, and grant the `access` role. Select a date in the future for the next review date.

![Fill out Access List Fields](/docs/assets/images/fill-out-access-list-fields-78bf6e0e74086e2a657555fb3dd62d52.png)

Under "List Owners" select `editor` as a required role, then add your administrative user under "Add Eligible List Owners." By selecting `editor` as a required role, this will ensure that any owner of the list must have the `editor` role in order to actually manage the list. If the user loses this role later, they will not be able to manage the list, though they will still be reflected as an owner.

![Select an owner](/docs/assets/images/select-owner-a2c9c11c689c39ad7a370e2766b70a6e.png)

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 not be granted the roles or traits described in the Access List.

![Add a member](/docs/assets/images/add-member-d39bce5052f9f68228c066d1f88fc730.png)

Finally, click "Create Access List" at the bottom of the page.

## Step 4/4. Login as the test user

Again, login as the test user. When logging in now, you should now see the dumper application contained within the cluster, and should be able to interact with it as expected.

## Next steps

- Read [Creating Access Lists with IaC](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/managing-resources/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).