{"token_count": 3777}

# Creating an Access List with the Custom Form

Identity Governance is available only with Teleport Enterprise.

The web UI's **Custom Form** creates an Access List by directly assigning existing roles to members and owners. Unlike the guided flows ([Standing](https://goteleport.com/docs/identity-governance/access-lists/standing-access-list.md) and [Just-in-Time](https://goteleport.com/docs/identity-governance/access-lists/jit-access-list.md)), it does not generate roles for you — you pick from roles that already exist in the cluster.

This guide will help you:

- Decide when the Custom Form is the right fit
- Create an Access List with the Teleport Web UI, `tctl`, or Terraform
- Verify that members get access on login

## When to use this flow

Use the Custom Form when:

- You already have roles in the cluster that capture the access you want to grant, and you'd rather assign those roles than have the guided flow generate new ones.
- You need fine-grained control over the role and trait grants that isn't exposed in the guided flow.
- You're comfortable editing the underlying roles yourself.

If you'd rather have Teleport generate the roles for you from a resource picker, use the [Standing Access Guide](https://goteleport.com/docs/identity-governance/access-lists/standing-access-list.md) (access on login) or the [Just-in-Time Access Guide](https://goteleport.com/docs/identity-governance/access-lists/jit-access-list.md) (access on request).

## Prerequisites

- A running Teleport Enterprise cluster accessible at a hostname with a valid TLS certificate. 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, 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:

     **Mac/Linux**

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

     **Windows - Powershell**

     ```
     $ $TELEPORT_DOMAIN = "teleport.example.com:443"
     $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").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/single-machine.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
     ```

  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`](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/2. Create the Access List

Choose how to create the list.

**Web UI**

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, then click **Use Custom Form Instead**.

The Custom Form is a single page split into three sections. Fill them out top to bottom, then click **Create Access List** at the bottom.

### Basic Information

- **Title** — required. The display name of the list.
- **Description** — optional context.
- **Review recurrence** — how often the list must be reviewed (frequency and day of month). Periodic reviews are how owners reaffirm that the right members are still on the list.
- **Deadline for first review** — the first review date. Pick a date in the future.

### List Owners

Owners manage members and membership requirements, and conduct periodic access reviews.

- **Eligibility (required roles)** (optional) — restrict who can be added as an owner. A Teleport user assigned as an owner takes effect only if they hold every role listed here; if they later lose one, ownership has no effect until it is restored.

![Owner Eligibility](/docs/assets/images/eligibility-6744449e5d412700a3921ea419c76909.png)

- **Owners** — the users to enroll as owners.

![Owners](/docs/assets/images/owners-ed997c2d49114f6ed0e9e78118a5b2be.png)

- **Grants** (optional) — roles an owner receives by being an owner. Typically used to grant the ability to review [Access Requests](https://goteleport.com/docs/identity-governance/access-requests.md) for this list — the preset [`reviewer`](https://goteleport.com/docs/reference/access-controls/roles.md#preset-roles) role is a common choice.

![Owner Grants](/docs/assets/images/owner-grants-6d9ca755fded3e488244ebbfe48b7dfd.png)

### Members

Members are the users who receive the list's grants. Granting members access is the primary purpose of most Access Lists.

- **Eligibility (required roles)** (optional) — restrict who can be a member. A user added as a member takes effect only if they hold every role listed here; if they lose one later, the list's grants no longer apply to them until it is restored.

![Member Eligibility](/docs/assets/images/eligibility-6744449e5d412700a3921ea419c76909.png)

- **Members** — the users to enroll as members.

![Members](/docs/assets/images/members-78db0a35e70511f7caae9f763b86a8a2.png)

- **Grants** — the roles members receive by being on the list.

![Member Grants](/docs/assets/images/member-grants-f0109092d75dac0694857b8a8b694000.png)

**tctl**

`tctl acl create` was introduced in `tctl` v18.10.3. On earlier versions of `tctl`, use the Web UI.

The following command creates a list that grants the `support-engineer` role to `bob`, and lets `alice` own and review it. Substitute the usernames and role names with ones that exist in your cluster:

```
$ tctl acl create \
    --title "Production access for support engineers" \
    --description "Grant access to production to engineers in the support rotation." \
    --audit-frequency 6 \
    --audit-day 1 \
    --owners alice \
    --owner-required-roles manager \
    --members bob \
    --member-required-roles engineer \
    --member-grant-roles support-engineer
```

See [`tctl acl create`](https://goteleport.com/docs/reference/cli/tctl.md#tctl-acl-create) for the full list of flags, including the trait equivalent of each grant and eligibility flag above.

Every list-valued flag takes a comma-separated string, for example `--members bob,carol`. Members can also be added after the fact with [`tctl acl users add`](https://goteleport.com/docs/reference/cli/tctl.md#tctl-acl-users-add).

**Terraform**

`tctl acl create` accepts `--output terraform` as of `tctl` v19.0.0. On earlier versions of `tctl`, write the Terraform configuration by hand as described in [Creating Access Lists with IaC](https://goteleport.com/docs/configuration/resource-guides/access-list.md). The Custom Form does not generate Terraform; only the guided flows do.

### Generate the configuration

The `tctl acl create --output terraform` command will not create anything, but instead prints a Terraform module describing the Access List the other flags define, which you can write straight to a file.

The following command generates a module for a list that grants the `support-engineer` role to `bob`, and lets `alice` own and review it. Substitute the usernames and role names with ones that exist in your cluster:

```
$ tctl acl create \
    --title "Production access for support engineers" \
    --description "Grant access to production to engineers in the support rotation." \
    --owners alice \
    --owner-required-roles manager \
    --members bob \
    --member-required-roles engineer \
    --member-grant-roles support-engineer \
    --output terraform > access-list.tf
```

See [`tctl acl create`](https://goteleport.com/docs/reference/cli/tctl.md#tctl-acl-create) for the full list of flags, including the trait equivalent of each grant and eligibility flag above.

The dry-run is a complete module: a provider block, the Access List itself, and one member resource per user you passed to `--members`. The provider's `addr` is filled in from the cluster `tctl` is talking to, so your output will be similar to the following:

```
terraform {
  required_providers {
    teleport = {
      source  = "terraform.releases.teleport.dev/gravitational/teleport"
      version = "~> 19.0"
    }
  }
}

provider "teleport" {
  addr = "teleport.example.com:443"
}

resource "teleport_access_list" "acl-0a1b2c3d-4e5f-6789-abcd-ef0123456789" {
  header = {
    kind    = "access_list"
    version = "v1"
    metadata = {
      name = "0a1b2c3d-4e5f-6789-abcd-ef0123456789"
    }
  }

  spec = {
    description = "Grant access to production to engineers in the support rotation."
    owners = [{
      membership_kind = "1"
      name            = "alice"
    }]
    membership_requires = {
      roles = ["engineer"]
    }
    ownership_requires = {
      roles = ["manager"]
    }
    grants = {
      roles = ["support-engineer"]
    }
    title = "Production access for support engineers"
    type  = "static"
  }
}

resource "teleport_access_list_member" "acl-member-bob_86c6a0d4" {
  depends_on = [teleport_access_list.acl-0a1b2c3d-4e5f-6789-abcd-ef0123456789]

  header = {
    kind    = "access_list_member"
    version = "v1"
    metadata = {
      name = "bob"
    }
  }

  spec = {
    access_list     = "0a1b2c3d-4e5f-6789-abcd-ef0123456789"
    name            = "bob"
    membership_kind = "1"
  }
}

```

Note the `type = "static"` field. Access Lists managed with Terraform must be static so that Terraform can own their membership, and static lists do not support periodic auditing. To learn the differences, see [Static versus default Access Lists](https://goteleport.com/docs/configuration/resource-guides/access-list.md#static-versus-default-access-lists).

### Apply the configuration

Log in to your cluster, assigning teleport.example.com:443 to your Teleport proxy address and email\@example.com to your Teleport username:

```
$ tsh login --proxy=teleport.example.com:443 --user=email@example.com
```

Generate temporary credentials for the Terraform provider:

```
$ eval "$(tctl terraform env)"
```

Initialize Terraform, preview the changes, and apply them:

```
$ terraform init
$ terraform plan
$ terraform apply
```

The Access List is created once `terraform apply` completes.

---

NOTE

The steps above use `tctl terraform env` to issue short-lived credentials, which is convenient for trying things out locally. For remote environments such as CI/CD pipelines or cloud VMs, see the [Terraform provider documentation](https://goteleport.com/docs/configuration/terraform-provider.md) for guidance on setting up the provider.

---

To write the configuration by hand instead of generating it, or for the full set of fields on the `teleport_access_list` and `teleport_access_list_member` resources, see [Creating Access Lists with IaC](https://goteleport.com/docs/configuration/resource-guides/access-list.md).

## Step 2/2. Verify the access

Log in as one of the members you added. The resources granted by the roles you assigned should appear in the resource list and you should be able to connect to them.

## Next steps

- Create an Access List whose members get access on login with the [Standing Access Guide](https://goteleport.com/docs/identity-governance/access-lists/standing-access-list.md).
- Create an Access List whose members request temporary access with the [Just-in-Time Access Guide](https://goteleport.com/docs/identity-governance/access-lists/jit-access-list.md).
- Group members by inheriting access from other lists with [nested Access Lists](https://goteleport.com/docs/identity-governance/access-lists/nested-access-lists.md).
- Manage the list from the command line after creating it — `tctl acl get`, `tctl acl update`, `tctl acl users`, and `tctl acl rm` are documented in the [`tctl` reference](https://goteleport.com/docs/reference/cli/tctl.md#tctl-acl-create).
- Learn more about managing Access Lists as code with the [Terraform provider and Kubernetes operator](https://goteleport.com/docs/configuration/resource-guides/access-list.md).