# Machine & Workload Identity with Application Access Teleport protects and controls access to HTTP and TCP applications. Machine & Workload Identity can be used to grant machines secure, short-lived access to these applications. In this guide, you will configure Machine & Workload Identity's agent, `tbot`, to produce credentials that can be used to access an application enrolled in your Teleport cluster. ## 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 ``` * If you have not already connected your application to Teleport, follow the [Protect a Web Application with Teleport](https://goteleport.com/docs/enroll-resources/application-access/getting-started.md). * 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 access applications. For more information, see the [deployment guides](https://goteleport.com/docs/machine-workload-identity/deployment.md). ## Step 1/3. Configure RBAC First, Teleport should be configured to allow the credentials produced by `tbot` to be used to connect to an Application. This is done by creating a role that grants the necessary permissions and then assigning this role to a Bot. Create a file called `role.yaml` with the following content: ``` kind: role version: v6 metadata: name: example-role spec: allow: # Grants access to all applications. app_labels: '*': '*' ``` Replace `example-role` with a descriptive name related to your use case. This grants access to all applications. In production environments you should modify these labels to grant access to only the applications that the machine will need access to. 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` There are two implementation options available when using `tbot` to grant a client access to an application. The option you choose will depend on your specific needs. The first option is the `application-tunnel` service. This operates a local proxy that your client can connect to. The service will automatically attach the credentials to the connection, meaning that the client does not need to support client certificates. However, this does mean that the `tbot` process must be running for the client to access the application. The second option is the `application` output service. This will write TLS credentials to a destination where your client will read them from. The client must support client certificates and reloading them from disk when they are renewed. In addition, this option is not compatible with a TLS-terminating load-balancer between the client and the Teleport Proxy service. Unlike the `application-tunnel`, the `tbot` process does not need to be running for the client to access the application - this can be ideal for CI/CD pipelines. If you aren't sure which to use, we recommend starting with the `application-tunnel` service as this is compatible with more clients. **application-tunnel service** To configure the `application-tunnel` service, first determine where you want the listener to bind to. As any client that can connect to the service listener will be able to access the application, it is recommended to bind to the loopback interface (e.g. `127.0.0.1`) as this will prevent access from other hosts. Modify your `tbot` configuration to add an `application-tunnel` service: ``` services: - type: application-tunnel app_name: dumper listen: tcp://127.0.0.1:1234 ``` Replace: - `dumper` with the name of the application you registered in Teleport. - `listen` with the address and port you wish the service to bind to. Ensure that `tbot` is not configured to run in one-shot mode, as the application tunnel will not start in this mode. Restart `tbot` to apply the new configuration. **application service** Output services must be configured with a destination. In this example, the `directory` destination will be used. This will write artifacts 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 will be accessing applications. Modify your `tbot` configuration to add an `application` service: ``` services: - type: application # specify the name of the application you wish the credentials to grant # access to. app_name: dumper 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 ``` Ensure you replace `dumper` with the name of the application you registered in Teleport. If operating `tbot` as a background service, restart it. If running `tbot` in one-shot mode, it must be executed before you attempt to use the credentials. ## Step 3/3. Connect to your web application **application-tunnel service** Once the `application-tunnel` service has been configured, you can connect to the application using the listen address you specified. For example, to access the application using `curl`: ``` $ curl http://127.0.0.1:1234/ ``` **application service** Once `tbot` has been run, credentials will be output to the directory specified in the destination. Using the example of `/opt/machine-id`: - `/opt/machine-id/tlscert`: the client TLS certificate - `/opt/machine-id/key`: the TLS certificate's private key You may use these credentials with any client application that supports them. The Teleport Proxy makes apps available via subdomains of its public web address. Given the debug application named `dumper` and a Teleport Proxy at `https://example.teleport.sh:443`, the app may be accessed at `https://dumper.example.teleport.sh:443`. For example, to access the application using `curl`: ``` $ curl \ --cert /opt/machine-id/tlscert \ --key /opt/machine-id/key \ https://dumper.example.teleport.sh/ ``` No CA certificate needs to be specified so long as your Teleport Proxy is configured with a valid wildcard CA from Let's Encrypt or another public certificate authority. Note that if the certificates are invalid or otherwise misconfigured, clients will be redirected to the Teleport login page when attempting to access the app. ## Troubleshooting ### Client application requires certificates with standard extensions If your automated service requires TLS certificates with a specific file extension, you may also enable the `specific_tls_naming` option for the output service: ``` services: - type: application destination: type: directory path: /opt/machine-id app_name: grafana-example specific_tls_naming: true ``` This will generate `tls.crt` and `tls.key` inside `/opt/machine-id` with identical content to the certificate files listed above. ### Clients are redirected to the Teleport login page As with human users, scripted clients will be redirected to the Teleport login page when attempting to access an app through the Teleport Proxy Service without valid credentials. Ensure the bot's certificates have not expired and that the client application has been configured to use both the client certificate and key. ## Next steps - Review the [Access Controls Reference](https://goteleport.com/docs/reference/access-controls/roles.md) to learn about restricting which Applications and other Teleport resources your bot may access. - Configure [JWTs](https://goteleport.com/docs/enroll-resources/application-access/jwt/introduction.md) for your Application to remove the need for additional login credentials. - Read the [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available configuration options.