knowledge/technology/applications/web/Teleport.md

---
obj: application
website: https://goteleport.com
repo: https://github.com/gravitational/teleport
rev: 2024-08-07
---

# Teleport
Teleport provides connectivity, authentication, access controls and audit for infrastructure.

It includes an identity-aware access proxy, a CA that issues short-lived certificates, a unified access control system and a tunneling system to access resources behind the firewall.

Teleport understands the [SSH](../network/SSH.md), [HTTPS](../../internet/HTTP.md), RDP, Kubernetes API, MySQL, [MongoDB](../development/MongoDB.md) and PostgreSQL wire protocols, plus many others. It can integrate with Single Sign-On providers and enables you to apply access policies using infrastructure-as-code and GitOps tools.

## Setup
You need a [domain](../../internet/Domain.md) pointing at your teleport proxy instance.

Docker-Compose:
```yml
version: '3'
services:
  teleport:
    image: public.ecr.aws/gravitational/teleport:14
    restart: unless-stopped
    hostname: <yourdomain.com>
    ports:
      - "3080:3080"  # Web UI
      - "3022:3022"  # SSH
      - "8443:8443"  # HTTPS
    volumes:
      - ./config/teleport.yaml:/etc/teleport/teleport.yaml
      - ./data:/var/lib/teleport
```

teleport.yml:
```yml
version: v3
teleport:
  nodename: <yourdomain.com>
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: INFO
    format:
      output: text
  ca_pin: ""
  diag_addr: ""
auth_service:
  enabled: "yes"
  listen_addr: 0.0.0.0:3025
  proxy_listener_mode: multiplex
  authentication:
    type: local
    second_factor: true
    webauthn:
        rp_id: <yourdomain.com>
    connector_name: passwordless
ssh_service:
  enabled: "no"
proxy_service:
  enabled: "yes"
  public_addr: <yourdomain.com>:443
  https_keypairs: []
  https_keypairs_reload_interval: 0s
  acme: {}
```

## Application Setup
Teleport assigns a subdomain to each application you configure for Application Access. For example, if you enroll Grafana as a resource, Teleport assigns the resource to the `grafana.teleport.example.com` subdomain.

1. Generate a token
  ```shell
  tctl tokens add \
    --type=app \
    --app-name=grafana \
    --app-uri=http://localhost:3000
  ```
2. Install and configure teleport
  ```shell
  sudo teleport configure \
  --output=file \
  --proxy=teleport.example.com:443 \
  --token=/tmp/token \
  --roles=app \
  --app-name=grafana \
  --app-uri=http://localhost:3000
  ```

### Advanced
#### Customize public address
By default applications are available at `<app-name>.<proxy-host>:<proxy-port>` address. To override the public address, specify the `public_addr` field:
```yml
- name: "jira"
  uri: "https://localhost:8001"
  public_addr: "jira.example.com"
```

#### Skip TLS certificate verification
> Danger Zone
> This is insecure and not recommended for use in production.

Teleport checks if the certificates presented by the applications are signed by a trusted Certificate Authority. When using self-signed certificates for internal applications, use `insecure_skip_verify: true` to skip this verification step:
```yml
- name: "app"
  uri: "https://localhost:8443"
  public_addr: "app.example.com"
  insecure_skip_verify: tru
```

#### Deeplink to a subdirectory
Some applications are available in a subdirectory. Examples include the Kubernetes Dashboard.. The URI should be updated to include the subdirectory:
```yml
- name: "k8s"
  uri: "http://10.0.1.60:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/#/overview"
  public_addr: "k8s.example.com"
```

#### Rewrite redirect
To support web apps that perform internal redirects, application access provides an option to rewrite the hostname of the Location header on redirect responses to the application's public address:
```yml
- name: "jenkins"
  uri: "https://localhost:8001"
  public_addr: "jenkins.example.com"
  rewrite:
    # Rewrite the "Location" header on redirect responses replacing the
    # host with the public address of this application.
    redirect:
    - "localhost"
    - "jenkins.internal.dev"
```

#### Headers passthrough
You can configure application access to inject additional headers in the requests forwarded to a web application.

For apps defined in the `teleport.yaml` configuration, the `headers` field of each app is a list of strings. Be careful to quote the entire value to ensure it is parsed correctly.
```yml
- name: "dashboard"
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  rewrite:
    headers:
    # Inject a static header.
    - "X-Custom-Header: example"
    # Inject headers with internal/external user traits.
    - "X-Internal-Trait: {{internal.logins}}"
    - "X-External-Trait: {{external.env}}"
    # Inject header with Teleport-signed JWT token.
    - "Authorization: Bearer {{internal.jwt}}"
    # Override Host header.
    - "Host: dashboard.example.com"
```

Headers injected this way override any headers with the same names that may be sent by an application. The following headers are reserved and can't be rewritten:
- `Teleport-Jwt-Assertion`
- `Cf-Access-Token`
- Any header matching the pattern `X-Teleport-*`
- Any header matching the pattern `X-Forwarded-*`

Rewritten header values support the same templating variables as role templates. In the example above, `X-Internal-Trait` header will be populated with the value of internal user trait logins and `X-External-Trait` header will get the value of the user's external env trait coming from the identity provider.

Additionally, the `{{internal.jwt}}` template variable will be replaced with a [JWT](../../internet/JWT.md) token signed by Teleport that contains user identity information.

#### [JSON Web Token](../../internet/JWT.md) Integration
Teleport sends a [JWT](../../internet/JWT.md) token signed with Teleport's authority with each request to a target application in a `Teleport-Jwt-Assertion` header.

You can use the [JWT](../../internet/JWT.md) token to get information about the authenticated Teleport user, its roles, and its traits. This allows you to:
- Map Teleport identity/roles/traits onto the identity/roles/traits of your web application.
- Trust Teleport identity to automatically sign in users into your application.

Example [JWT](../../internet/JWT.md):
```jsonc
{
  "aud": [
    "http://127.0.0.1:34679"
  ],
  "iss": "aws",
  "nbf": 1603835795,
  "sub": "alice",
  // Teleport user name.
  "username": "alice"
  // Teleport user roles.
  "roles": [
    "admin"
  ],
  // Teleport user traits.
  "traits": {
    "logins": [
      "root",
      "ubuntu",
      "ec2-user"
    ]
  },
  // Teleport identity expiration.
  "exp": 1603943800,
}
```

##### Validate [JWT](../../internet/JWT.md)
Teleport provides a JSON Web Key Set (jwks) endpoint to verify that the [JWT](../../internet/JWT.md) can be trusted. This endpoint is `https://[cluster-name]:3080/.well-known/jwks.json`:

Example jwks.json:
```json
{
  "keys": [
    {
      "kty": "RSA",
      "n": "xk-0VSVZY76QGqeN9TD-FJp32s8jZrpsalnRoFwlZ_JwPbbd5-_bPKcz8o2tv1eJS0Ll6ePxRCyK68Jz2UC4V4RiYaqJCRq_qVpDQMB1sQ7p9M-8qvT82FJ-Rv-W4RNe3xRmBSFDYdXaFm51Uk8OIYfv-oZ0kGptKpkNY390aJOzjHPH2MqSvhk9Xn8GwM8kEbpSllavdJCRPCeNVGJXiSCsWrOA_wsv_jqBP6g3UOA9GnI8R6HR14OxV3C184vb3NxIqxtrW0C4W6UtSbMDcKcNCgajq2l56pHO8In5GoPCrHqlo379LE5QqpXeeHj8uqcjeGdxXTuPrRq1AuBpvQ",
      "e": "AQAB",
      "alg": "RS256"
    }
  ]
}
```

## [SSH](../network/SSH.md) Agent Setup
1. Install teleport on your host:
    ```shell
    curl https://goteleport.com/static/install.sh | bash -s 14.2.0
    ```
2. On your teleport proxy, create a join token:
    ```shell
    tctl tokens add --type=node --format=text > token.file
    ```
3. Join the server to the cluster:
    ```shell
    sudo teleport node configure \
   --output=file:///etc/teleport.yaml \
   --token=/path/to/token.file \
   --proxy=tele.example.com:443
    ```
4. Enable Teleport Service
```
[Unit]
Description=Teleport Service
After=network.target

[Service]
Type=simple
Restart=on-failure
EnvironmentFile=-/etc/default/teleport
ExecStart=/usr/local/bin/teleport start --config /etc/teleport.yaml --pid-file=/run/teleport.pid
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/teleport.pid
LimitNOFILE=524288

[Install]
WantedBy=multi-user.target
```

## Machine ID Setup
Teleport Machine ID enables machines, such as CI/CD workflows, to securely authenticate with your Teleport cluster in order to connect to resources and configure the cluster itself. This is sometimes referred to as machine-to-machine access.

1. Create a bot user:
  ```shell
  tctl bots add robot --roles=access --logins=root
  ```
2. Start Machine ID (or run as Service):
   ```shell
   sudo tbot start \
   --data-dir=/var/lib/teleport/bot \
   --destination-dir=/opt/machine-id \
   --token=abcd123-insecure-do-not-use-this \
   --join-method=token \
   --auth-server=example.teleport.sh:443
   ```
3. Use:
  ```shell
  ssh -F /opt/machine-id/ssh_config root@node-name.example.com
  ```

## `tctl`
Admin tool for the Teleport Access Platform
Usage: `tctl [<flags>] <command> [<args> ...]`

### Commands
#### users add
Generate a user invitation token.
Usage: `tctl users add --roles=ROLES [<flags>] <account>`

##### Options
| Option   | Description                                                      |
| -------- | ---------------------------------------------------------------- |
| --logins | List of allowed [SSH](../network/SSH.md) logins for the new user |

#### users update
Update user account.
Usage: `tctl users update [<flags>] <account>`

##### Options
| Option         | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `--set-roles`  | List of roles for the user to assume, replaces current roles                          |
| `--set-logins` | List of allowed [SSH](../network/SSH.md) logins for the user, replaces current logins |

#### users ls
Lists all user accounts.
Usage: `tctl users ls`

#### users rm
Deletes user accounts.
Usage: `tctl users rm <logins>`

#### users reset
Reset user password and generate a new token.
Usage: `tctl users reset <account>`

#### get
Print a [YAML](../../files/YAML.md) declaration of various Teleport resources.
Usage: `tctl get [<flags>] <resources>`

##### Options
| Option     | Description                             |
| ---------- | --------------------------------------- |
| `--format` | Output format: `yaml`, `json` or `text` |

#### edit
Edit a Teleport resource.
Usage: `tctl edit [<resource type/resource name>]`

#### nodes add
Generate a node invitation token.
Usage: `tctl nodes add [<flags>]`

##### Options
| Option    | Description                                              |
| --------- | -------------------------------------------------------- |
| `--roles` | Comma-separated list of roles for the new node to assume |
| `--ttl`   | Time to live for a generated token                       |

#### nodes ls
List all active [SSH](../network/SSH.md) nodes within the cluster.
Usage: `tctl nodes ls [<flags>] [<labels>]`

#### tokens add
Create a invitation token.
Usage: `tctl tokens add --type=TYPE [<flags>]`

##### Options
| Option     | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `--type`   | Type(s) of token to add, e.g. `--type=node,app,db,proxy,etc` |
| `--labels` | Set token labels, e.g. `env=prod,region=us-west`             |
| `--ttl`    | Set expiration time for token, default is 30 minutes         |
| `--format` | Output format, 'text', 'json', or 'yaml'                     |

#### tokens rm
Delete/revoke an invitation token.
Usage: `tctl tokens rm [<token>]`

#### tokens ls
List node and user invitation tokens.
Usage: `tctl tokens ls`

#### bots ls
List all certificate renewal bots registered with the cluster.
Usage: `tctl bots ls`

#### bots add
Add a new certificate renewal bot to the cluster.
Usage: `tctl bots add --roles ROLES [--logins LOGINS] BOT_NAME`

#### bots rm
Permanently remove a certificate renewal bot from the cluster.
Usage: `tctl bots rm BOT_NAME`

#### status
Report cluster status.
Usage: `tctl status`

## `tsh`
Teleport Command Line client for interacting with your infrastructure.
Usage: `tsh [options...] <command> [<args> ...]`

### Options
| Option    | Description                                   |
| --------- | --------------------------------------------- |
| `--proxy` | Teleport proxy address                        |
| `--user`  | Teleport user, defaults to current local user |
 
### Commands
#### ssh
Run [shell](../cli/Shell.md) or execute a command on a remote [SSH](../network/SSH.md) node.
Usage: `tsh ssh [<flags>] <[user@]host> [<command>...]`

##### scp
Transfer files to a remote [SSH](../network/SSH.md) node.
Usage: `tsh scp [<flags>] <from, to>...`

##### ls
List remote [SSH](../network/SSH.md) nodes.
Usage: `tsh ls [<flags>] [<labels>]`

##### login
Log in to a cluster and retrieve the session certificate.
Usage: `tsh login [<flags>] [<cluster>]`

> **Info:** If no passwordless authentification methods are available you can login with `--auth=local`

##### logout
Delete a cluster certificate.
Usage: `tsh logout`

##### status
Display the list of proxy servers and retrieved certificates.
Usage: `tsh status`

##### config
Print [SSH](../network/SSH.md) config details.
This allows you to use regular [`ssh`](../network/SSH.md) command to connect to teleport servers.
```shell
tsh config >> ~/.ssh/config
```