# Machine & Workload Identity with tctl `tctl` is the Teleport cluster management CLI tool. Whilst it usually uses the credentials from the locally logged in user, it is also possible to use credentials issued by Machine & Workload Identity. This allows `tctl` to be leveraged as part of a custom automation workflow deployed in a non-interactive environment (e.g. CI/CD). In this guide, you will configure `tbot` to produce credentials for `tctl`, and then use `tctl` to deploy Teleport roles defined in files. ## Prerequisites - A running Teleport 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\) 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 18.7.3 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. * `tbot` must already be installed and configured on the machine that will use `tctl`. For more information, see the [deployment guides](https://goteleport.com/docs/machine-workload-identity/deployment.md). ## Step 1/3. Configure RBAC First, Teleport must be configured to allow the credentials produced by `tbot` to modify the Teleport configuration. This is done by creating a role that grants the necessary permissions and then assigning this role to a Bot. It's important to grant as few privileges as possible in order to limit the blast radius of an attack, so in this example we grant only the ability to create and update roles. Create a file called `role.yaml` with the following content: ``` kind: role version: v6 metadata: name: example-role spec: allow: rules: - resources: # Specify the names of resources you wish to manage with tctl. # For this guide, we will only manage roles. - role verbs: - create - read - update - delete - list ``` Replace `example-role` with a descriptive name related to your use case. Use `tctl create -f ./role.yaml` to create the role. --- TIP You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit. --- Now, use `tctl bots update` to add the role to the Bot. Replace `example` with the name of the Bot you created in the deployment guide and `example-role` with the name of the role you just created: ``` $ tctl bots update example --add-roles example-role ``` ## Step 2/3. Configure `tbot` output service Now, `tbot` needs to be configured with a service that will produce the credentials needed by `tctl`. As `tctl` will be accessing the Teleport API, the correct service type to use is `identity`. For this guide, the `directory` destination will be used. This will write these credentials to a specified directory on disk. Ensure that this directory can be written to by the Linux user that `tbot` runs as, and that it can be read by the Linux user that `tctl` will run as. Modify your `tbot` configuration to add an `identity` output: ``` services: - type: identity destination: type: directory # For this guide, /opt/machine-id is used as the destination directory. # You may wish to customize this. Multiple output services cannot share the # same destination. path: /opt/machine-id ``` If operating `tbot` as a background service, restart it. If running `tbot` in one-shot mode, it must be executed before you attempt to execute `tctl` later. You should now see an `identity` file under `/opt/machine-id`. This contains the private key and signed certificates needed by `tctl` to authenticate with the Teleport Auth Service. ## Step 3/3. Use `tctl` with the identity output service As an example, `tctl` will be used to apply a directory of YAML files that define Teleport roles. If these were stored in version control (e.g., `git`) and this were executed on change, this would form the basis for managing Teleport roles in a GitOps style. The example role will not be useful within the context of your Teleport cluster and should be modified once you have completed this guide. Create a directory called `roles/` and within it create `example.yaml`: ``` kind: role version: v6 metadata: name: tctl-test spec: # This role does nothing as it is an example role. allow: {} ``` To configure `tctl` to use the identity file, the `-i` flag is used. As the identity file does not specify the address of Teleport, `--auth-server` must also be specified with the address of your Teleport Proxy or Teleport Auth Server. Run `tctl`, replacing `example.teleport.sh:443` with the address of your Teleport Proxy or Auth Service and `/opt/machine-id/identity` with the path to the generated identity file if you have modified this: ``` $ tctl --auth-server example.teleport.sh:443 -i /opt/machine-id/identity create -f roles/*.yaml ``` Check your Teleport cluster, ensuring the role has been created. ``` $ tctl get role/tctl-test ``` ## Next steps - Explore the [`tctl` reference](https://goteleport.com/docs/reference/cli/tctl.md) to discover all `tctl` can do. - Read the [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available `tbot` configuration options.