diff --git a/technology/applications/web/Teleport.md b/technology/applications/web/Teleport.md index 2841685..d595e39 100644 --- a/technology/applications/web/Teleport.md +++ b/technology/applications/web/Teleport.md @@ -3,12 +3,13 @@ obj: application website: https://goteleport.com repo: https://github.com/gravitational/teleport --- + # 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, 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. +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. @@ -63,6 +64,153 @@ proxy_service: 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 `.:` 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 @@ -80,7 +228,7 @@ proxy_service: --proxy=tele.example.com:443 ``` 4. Enable Teleport Service -```shell +``` [Unit] Description=Teleport Service After=network.target @@ -98,6 +246,26 @@ LimitNOFILE=524288 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 @@ -109,19 +277,19 @@ Generate a user invitation token. Usage: `tctl users add --roles=ROLES [] ` ##### Options -| Option | Description | -| -------- | ------------------------------------------- | -| --logins | List of allowed SSH logins for the new user | +| Option | Description | +| -------- | ---------------------------------------------------------------- | +| --logins | List of allowed [SSH](../network/SSH.md) logins for the new user | #### users update Update user account. Usage: `tctl users update [] ` ##### Options -| Option | Description | -| -------------- | ---------------------------------------------------------------- | -| `--set-roles` | List of roles for the user to assume, replaces current roles | -| `--set-logins` | List of allowed SSH logins for the user, replaces current logins | +| 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. @@ -135,6 +303,19 @@ Usage: `tctl users rm ` Reset user password and generate a new token. Usage: `tctl users reset ` +#### get +Print a [YAML](../../files/YAML.md) declaration of various Teleport resources. +Usage: `tctl get [] ` + +##### Options +| Option | Description | +| ---------- | --------------------------------------- | +| `--format` | Output format: `yaml`, `json` or `text` | + +#### edit +Edit a Teleport resource. +Usage: `tctl edit []` + #### nodes add Generate a node invitation token. Usage: `tctl nodes add []` @@ -146,7 +327,7 @@ Usage: `tctl nodes add []` | `--ttl` | Time to live for a generated token | #### nodes ls -List all active SSH nodes within the cluster. +List all active [SSH](../network/SSH.md) nodes within the cluster. Usage: `tctl nodes ls [] []` #### tokens add @@ -169,6 +350,18 @@ Usage: `tctl tokens rm []` 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` @@ -185,15 +378,15 @@ Usage: `tsh [options...] [ ...]` ### Commands #### ssh -Run shell or execute a command on a remote SSH node. +Run [shell](../cli/Shell.md) or execute a command on a remote [SSH](../network/SSH.md) node. Usage: `tsh ssh [] <[user@]host> [...]` ##### scp -Transfer files to a remote SSH node. +Transfer files to a remote [SSH](../network/SSH.md) node. Usage: `tsh scp [] ...` ##### ls -List remote SSH nodes. +List remote [SSH](../network/SSH.md) nodes. Usage: `tsh ls [] []` ##### login @@ -210,7 +403,7 @@ Usage: `tsh status` ##### config Print [SSH](../network/SSH.md) config details. -This allows you to use regular `ssh` command to connect to teleport servers. +This allows you to use regular [`ssh`](../network/SSH.md) command to connect to teleport servers. ```shell tsh config >> ~/.ssh/config -``` \ No newline at end of file +```