jmarya/knowledge
jmarya/knowledge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

update teleport

Browse source
This commit is contained in:
JMARyA 2024-03-08 22:19:01 +01:00
parent 6505e80d86
commit 5584be0f1b
Signed by: jmarya
GPG key ID: 901B2ADDF27C2263
1 changed files with 208 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

223
technology/applications/web/Teleport.md
View file

@ -3,12 +3,13 @@ obj: application
website: https://goteleport.com website: https://goteleport.com
repo: https://github.com/gravitational/teleport repo: https://github.com/gravitational/teleport
--- ---
# Teleport # Teleport
Teleport provides connectivity, authentication, access controls and audit for infrastructure. 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. 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 ## Setup
You need a [domain](../../internet/Domain.md) pointing at your teleport proxy instance. You need a [domain](../../internet/Domain.md) pointing at your teleport proxy instance.
@ -63,6 +64,153 @@ proxy_service:
acme: {} 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 ## [SSH](../network/SSH.md) Agent Setup
1. Install teleport on your host: 1. Install teleport on your host:
```shell ```shell
@ -80,7 +228,7 @@ proxy_service:
--proxy=tele.example.com:443 --proxy=tele.example.com:443
``` ```
4. Enable Teleport Service 4. Enable Teleport Service
```shell ```
[Unit] [Unit]
Description=Teleport Service Description=Teleport Service
After=network.target After=network.target
@ -98,6 +246,26 @@ LimitNOFILE=524288
WantedBy=multi-user.target 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` ## `tctl`
Admin tool for the Teleport Access Platform Admin tool for the Teleport Access Platform
@ -109,19 +277,19 @@ Generate a user invitation token.
Usage: `tctl users add --roles=ROLES [<flags>] <account>` Usage: `tctl users add --roles=ROLES [<flags>] <account>`
##### Options ##### Options
| Option | Description | | Option | Description |
| -------- | ------------------------------------------- | | -------- | ---------------------------------------------------------------- |
| --logins | List of allowed SSH logins for the new user | | --logins | List of allowed [SSH](../network/SSH.md) logins for the new user |
#### users update #### users update
Update user account. Update user account.
Usage: `tctl users update [<flags>] <account>` Usage: `tctl users update [<flags>] <account>`
##### Options ##### Options
| Option | Description | | Option | Description |
| -------------- | ---------------------------------------------------------------- | | -------------- | ------------------------------------------------------------------------------------- |
| `--set-roles` | List of roles for the user to assume, replaces current roles | | `--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 | | `--set-logins` | List of allowed [SSH](../network/SSH.md) logins for the user, replaces current logins |
#### users ls #### users ls
Lists all user accounts. Lists all user accounts.
@ -135,6 +303,19 @@ Usage: `tctl users rm <logins>`
Reset user password and generate a new token. Reset user password and generate a new token.
Usage: `tctl users reset <account>` 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 #### nodes add
Generate a node invitation token. Generate a node invitation token.
Usage: `tctl nodes add [<flags>]` Usage: `tctl nodes add [<flags>]`
@ -146,7 +327,7 @@ Usage: `tctl nodes add [<flags>]`
| `--ttl` | Time to live for a generated token | | `--ttl` | Time to live for a generated token |
#### nodes ls #### 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 [<flags>] [<labels>]` Usage: `tctl nodes ls [<flags>] [<labels>]`
#### tokens add #### tokens add
@ -169,6 +350,18 @@ Usage: `tctl tokens rm [<token>]`
List node and user invitation tokens. List node and user invitation tokens.
Usage: `tctl tokens ls` 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 #### status
Report cluster status. Report cluster status.
Usage: `tctl status` Usage: `tctl status`
@ -185,15 +378,15 @@ Usage: `tsh [options...] <command> [<args> ...]`
### Commands ### Commands
#### ssh #### 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 [<flags>] <[user@]host> [<command>...]` Usage: `tsh ssh [<flags>] <[user@]host> [<command>...]`
##### scp ##### scp
Transfer files to a remote SSH node. Transfer files to a remote [SSH](../network/SSH.md) node.
Usage: `tsh scp [<flags>] <from, to>...` Usage: `tsh scp [<flags>] <from, to>...`
##### ls ##### ls
List remote SSH nodes. List remote [SSH](../network/SSH.md) nodes.
Usage: `tsh ls [<flags>] [<labels>]` Usage: `tsh ls [<flags>] [<labels>]`
##### login ##### login
@ -210,7 +403,7 @@ Usage: `tsh status`
##### config ##### config
Print [SSH](../network/SSH.md) config details. 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 ```shell
tsh config >> ~/.ssh/config tsh config >> ~/.ssh/config
``` ```