From 82603301a96977ddd54b6b1028765300bb0e4c27 Mon Sep 17 00:00:00 2001 From: Roman Tkachenko Date: Tue, 23 Mar 2021 08:41:35 -0700 Subject: [PATCH] Address review comments --- docs/config.json | 2 +- docs/pages/application-access.mdx | 31 +++---- .../application-access/getting-started.mdx | 38 ++++---- docs/pages/application-access/guides.mdx | 2 +- .../application-access/guides/api-access.mdx | 18 ++-- .../guides/{usage.mdx => connecting-apps.mdx} | 92 ++++++++++--------- docs/pages/application-access/guides/jwt.mdx | 37 +++++--- 7 files changed, 114 insertions(+), 106 deletions(-) rename docs/pages/application-access/guides/{usage.mdx => connecting-apps.mdx} (73%) diff --git a/docs/config.json b/docs/config.json index 9ef2d666d7b8f..4169f5534ebf1 100644 --- a/docs/config.json +++ b/docs/config.json @@ -27,7 +27,7 @@ "title": "Guides", "slug": "/application-access/guides/", "entries": [ - { "title": "General Usage", "slug": "/application-access/guides/usage/" }, + { "title": "Connecting Apps", "slug": "/application-access/guides/connecting-apps/" }, { "title": "Integrating with JWT", "slug": "/application-access/guides/jwt/" }, { "title": "API Access", "slug": "/application-access/guides/api-access/" } ] diff --git a/docs/pages/application-access.mdx b/docs/pages/application-access.mdx index dadec20d61d13..f423c1b7671b9 100644 --- a/docs/pages/application-access.mdx +++ b/docs/pages/application-access.mdx @@ -5,15 +5,12 @@ description: How to set up and configure Teleport for Application access with SS # Application Access -Teleport Application Access has been designed to provide secure access to -internal dashboards and applications, building on Teleport's strong foundations -of security and identity. - -You can secure any web application using application access: +Teleport Application Access is designed to provide secure access to +internal dashboards and applications, such as: - Internal control panels. -- Wikis / Tooling that's only available on the VPN. -- Infra dashboards - Kubernetes, Grafana. +- Wikis / tooling that's only available on the VPN. +- Infrastructure dashboards, such as Kubernetes or Grafana. - Developer tools, such as Jenkins, Gitlab or Opsgenie. ## Demo @@ -44,16 +41,11 @@ Get started with Application Access in a 10 minute [guide](./application-access/ ## Guides -* [Application Access Usage](./application-access/guides/usage.mdx) +* [Connecting Applications](./application-access/guides/connecting-apps.mdx) * [JWT Tokens](./application-access/guides/jwt.mdx) * [API Access](./application-access/guides/api-access.mdx) -## Example Applications - -As outlined in our introduction, Application Access has been designed to -support two types of applications. - -### Example Legacy App +## Example Legacy Apps A device such as a load balancer might come with a control panel, but it doesn't have any authentication and can only be access via a privileged network. @@ -64,14 +56,13 @@ Other example legacy apps: - An internal admin tool. - Control panel for networking devices. -### Example Modern App +## Example Modern Apps -Teleport Application Access supports all modern applications, these could be -built in-house or off-the-shelf software such as Jenkins, Kubernetes Dashboard -and Jupyter workbooks. +Teleport Application Access supports web applications such as internal web +tools and infrastructure software like: -- Kubernetes Internal Dashboard. +- Kubernetes Dashboard. - Grafana. - Jupyter notebooks. - In-house Single Page Apps (SPA). -- SPA with custom Json Web Token support (JWT). +- SPA with custom JSON Web Token support (JWT). diff --git a/docs/pages/application-access/getting-started.mdx b/docs/pages/application-access/getting-started.mdx index 0661ea6054a7c..9320a0a9d2c86 100644 --- a/docs/pages/application-access/getting-started.mdx +++ b/docs/pages/application-access/getting-started.mdx @@ -5,9 +5,7 @@ description: Getting started with Teleport Application Access # Getting Started -Let's connect to Grafana using Teleport Application Access. - -To achieve this we will: +Let's connect to Grafana using Teleport Application Access in 3 steps: 1. Launch Grafana in a Docker container. 2. Install Teleport and configure it it to proxy Grafana. @@ -15,12 +13,12 @@ To achieve this we will: ## Prerequisites -* Docker to launch Grafana in a container. Alternatively, if you have another - web application you'd like to protect with App Access, you can use that instead. -* Configured DNS records for the host where Teleport service will be running - are required to automatically fetch a Let's Encrypt certificate. For this - guide we will assume your Teleport cluster will be accessible at `teleport.example.com` - and `*.teleport.example.com`. +* We will use Docker to launch Grafana in a container. Alternatively, if you + have another web application you'd like to protect with App Access, you can + use that instead. +* We will assume your Teleport cluster is accessible at `teleport.example.com` + and `*.teleport.example.com`. Configured DNS records are required to + automatically fetch a Let's Encrypt certificate. ## Step 1/3. Start Grafana @@ -35,9 +33,6 @@ with a single command: $ docker run -d -p 3000:3000 grafana/grafana ``` -Make sure to launch it on the same node where your Teleport service will be -running, for the simplicity of the tutorial. - ## Step 2/3. Install and Configure Teleport Download the latest version of Teleport for your platform from our @@ -46,28 +41,29 @@ Download the latest version of Teleport for your platform from our Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt [ACME](https://letsencrypt.org/how-it-works/) protocol. -As mentioned in prerequisites above, we will assume that you have configured DNS -records for `teleport.example.com` and `*.teleport.example.com` to point to the -node where you're launching Teleport. +We will assume that you have configured DNS records for `teleport.example.com` +and `*.teleport.example.com` to point to the Teleport node. Let's generate a Teleport config with ACME enabled: ```shell -$ teleport configure --cluster-name=teleport.example.com --acme --acme-email=alice@example.com > /tmp/teleport.yaml +$ teleport configure --cluster-name=teleport.example.com --acme --acme-email=alice@example.com -o file ``` - Teleport's ACME protocol integration currently requires web proxy to run on - port 443. + Teleport uses [TLS-ALPN-01](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01) + ACME challenge to validate certificate requests which only works on port `443`. + As such, in order to use ACME for certificate management, web proxy needs to + be accessible on port `443`. Now start Teleport and point it to the application endpoint: ```shell -$ sudo teleport start --config=/tmp/teleport.yaml \ +$ sudo teleport start \ --roles=proxy,auth,app \ --app-name=grafana \ --app-uri=http://localhost:3000 @@ -106,7 +102,7 @@ to access it. Dive deeper into the topics relevant to your Application Access use-case: -* Learn in more detail about Application Access [usage](./guides/usage.mdx). +* Learn in more detail about [connecting applications](./guides/connecting-apps.mdx) with Application Access. * Learn about integrating with [JWT tokens](./guides/jwt.mdx) for auth. * Learn how to use Application Access with [RESTful APIs](./guides/api-access.mdx). * See full configuration and CLI [reference](./reference.mdx). diff --git a/docs/pages/application-access/guides.mdx b/docs/pages/application-access/guides.mdx index 999ebdbc1c72d..95a8f7fe903ea 100644 --- a/docs/pages/application-access/guides.mdx +++ b/docs/pages/application-access/guides.mdx @@ -5,6 +5,6 @@ description: Guides for configuring Teleport Application Access # Guides -- [Application Access Usage](./guides/usage.mdx) +- [Connecting Applications](./guides/connecting-apps.mdx) - [JWT Tokens](./guides/jwt.mdx) - [API Access](./guides/api-access.mdx) diff --git a/docs/pages/application-access/guides/api-access.mdx b/docs/pages/application-access/guides/api-access.mdx index bacb64a6f7403..aa2e67b654bac 100644 --- a/docs/pages/application-access/guides/api-access.mdx +++ b/docs/pages/application-access/guides/api-access.mdx @@ -34,6 +34,8 @@ app_service: - name: "grafana" description: "Test Grafana server" uri: "http://localhost:3000" + labels: + "env": "dev" ``` ## Accessing API @@ -44,8 +46,8 @@ Log into your Teleport cluster and view available applications: $ tsh login --proxy=teleport.example.com:3080 $ tsh app ls Application Description Public Address Labels ------------ ------------------- ---------------------------- ------ -grafana Test Grafana server grafana.teleport.example.com +----------- ------------------- ---------------------------- ------- +grafana Test Grafana server grafana.teleport.example.com env=dev ``` Retrieve short-lived X.509 certificate for the application: @@ -62,9 +64,12 @@ curl \ ``` The login message shows an example `curl` command you can run to call the -target application's API through Teleport App Access. Note the paths to the -CA certificate and your user's certificate/key pair in the command - `curl` -will use a client certificate to authenticate with Teleport. +target application's API through Teleport App Access. + + +Note the paths to the CA certificate and your user's certificate/key pair in +the command - `curl` will use a client certificate to authenticate with Teleport. + As Grafana's API requires authentication, let's update the `curl` command to provide basic auth information using default Grafana username/password and @@ -89,8 +94,7 @@ Logged out of app "grafana" ## App Information -Teleport provides a way to see information about the application you're -logged into via CLI, such as app URI and paths to the secrets. This is useful +`tsh app config` shows current app URI and paths to the secrets. This is useful when configuring CLI tools (such as `curl`) or GUI tools (such as Postman). Let's print the app information in a table format: diff --git a/docs/pages/application-access/guides/usage.mdx b/docs/pages/application-access/guides/connecting-apps.mdx similarity index 73% rename from docs/pages/application-access/guides/usage.mdx rename to docs/pages/application-access/guides/connecting-apps.mdx index 0cd7624331dc7..44a7496d5dbc6 100644 --- a/docs/pages/application-access/guides/usage.mdx +++ b/docs/pages/application-access/guides/connecting-apps.mdx @@ -3,7 +3,7 @@ title: Using Application Access Guide description: How to configure Teleport for Application Access --- -# Application Access Usage +# Connecting Web Applications Download the latest version of Teleport for your platform from our [downloads page](https://goteleport.com/teleport/download) and follow the installation [instructions](../../installation.mdx). @@ -57,48 +57,51 @@ In our example: * `teleport.example.com` will host the Access Plane. * `*.teleport.example.com` will host all of the applications e.g. `grafana.teleport.example.com`. -Teleport supports accessing these applications on other domains if required. -DNS entries must be configured and the correct certificates need to be obtained -for this to work. +Teleport can obtain a certificate automatically from Let's Encrypt using +[ACME](https://letsencrypt.org/how-it-works/) protocol. + +Enable ACME in your proxy config: ```yaml proxy_service: enabled: "yes" - listen_addr: 0.0.0.0:3023 - tunnel_listen_addr: 0.0.0.0:3024 - public_addr: teleport.example.com:443 - # Example of two HTTPs keypairs. - https_keypairs: - - key_file: /etc/letsencrypt/live/teleport.example.com/privkey.pem - cert_file: /etc/letsencrypt/live/teleport.example.com/fullchain.pem - - key_file: /etc/letsencrypt/live/*.teleport.example.com/privkey.pem - cert_file: /etc/letsencrypt/live/*.teleport.example.com/fullchain.pem + web_listen_addr: ":443" + public_addr: "teleport.example.com:443" + acme: + enabled: "yes" + email: "alice@example.com" ``` - Let's Encrypt provides free wildcard certificates. If using [certbot](https://certbot.eff.org/) - with DNS challenge, the below script will make setup easy. Update [EMAIL] and [DOMAIN] - - ```sh - certbot certonly --manual \ - --preferred-challenges=dns \ - --email [EMAIL] \ - --agree-tos \ - --manual-public-ip-logging-ok \ - -d "teleport.example.com, *.teleport.example.com" - ``` + Teleport uses [TLS-ALPN-01](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01) + ACME challenge to validate certificate requests which only works on port `443`. + As such, in order to use ACME for certificate management, web proxy needs to + be accessible on port `443`. -### Create a User +Alternatively, if you have obtained certificate/key pairs for your domain +(e.g. using [certbot](https://certbot.eff.org/)), they can be provided directly +to the proxy service: -In order to be able to access the application, a Teleport user needs to have -a role that allows them to see it. +```yaml +proxy_service: + enabled: "yes" + web_listen_addr: ":443" + public_addr: "teleport.example.com:443" + https_keypairs: + - key_file: "/etc/letsencrypt/live/teleport.example.com/privkey.pem" + cert_file: "/etc/letsencrypt/live/teleport.example.com/fullchain.pem" + - key_file: "/etc/letsencrypt/live/*.teleport.example.com/privkey.pem" + cert_file: "/etc/letsencrypt/live/*.teleport.example.com/fullchain.pem" +``` + +### Create a User -Teleport comes with a built-in `access` role that provides access to all -applications: +A Teleport user needs their role's permission to access an application. Teleport +comes with a built-in `access` role that grants access to all apps: ```sh $ tctl --config=/path/to/teleport.yaml users add --roles=access appuser @@ -124,17 +127,16 @@ a reverse tunnel. ### Application Name -When picking an application name, it's important to make sure the name will -make a valid sub-domain (<=63 characters, no spaces, only `a-z 0-9 _ -` allowed). +An application name should make a valid sub-domain (<=63 characters, no spaces, only `a-z 0-9 _ -` allowed). -After Teleport is running, the application will be accessible at -`app-name.proxy_public_addr.com` e.g. `grafana.teleport.example.com`. Teleport -also provides the ability to override `public_addr` e.g `grafana.acme.com` -if you configure the appropriate DNS entry to point to the Teleport proxy server. +After Teleport is running, users can access the app at `app-name.proxy_public_addr.com` +e.g. `grafana.teleport.example.com`. You can also override `public_addr` e.g +`grafana.acme.com` if you configure the appropriate DNS entry to point to the +Teleport proxy server. ## Start Application Service with Config File -Example `/etc/teleport-app.yaml` configuration: +Example `teleport.yaml` configuration: ```yaml teleport: @@ -183,7 +185,7 @@ proxy_service: Start the application service: ```sh -$ teleport start --config=/etc/teleport-app.yaml +$ teleport start --config=/path/to/teleport.yaml ``` ## Advanced Options @@ -214,10 +216,14 @@ address. To override the public address, specify the `public_addr` field: ### Skip TLS Certificate Verification -Teleport attempts to check if the certificates presented by the applications -are signed by a trusted CA (Certificate Authority). When using self-signed -certificates for internal applications, use `insecure_skip_verify: true` to -skip this verification step: + +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: ```yaml - name: "app" diff --git a/docs/pages/application-access/guides/jwt.mdx b/docs/pages/application-access/guides/jwt.mdx index 8790dd838ece4..851e6e8420321 100644 --- a/docs/pages/application-access/guides/jwt.mdx +++ b/docs/pages/application-access/guides/jwt.mdx @@ -5,16 +5,21 @@ description: How to integrate use JWT tokens authentication with Application Acc # Integrating with JWTs -Teleport includes a JWT token signed with Teleport's authority with each -request to a target application. The token is sent in a `Teleport-Jwt-Assertion` -header. +Teleport sends a JWT token signed with Teleport's authority with each request +to a target application in a `Teleport-Jwt-Assertion` header. + +You can use the JWT token to get information about the authenticated Teleport +user and its roles. This allows you to: + +* Map Teleport identity/roles onto the identity/roles of your web application. +* Trust Teleport identity to automatically sign in users into your application. ## Introduction to JWTs JSON Web Token (JWT) is an open standard that defines a secure way to transfer information between parties as a JSON Object. -For a in-depth explanation please visit [https://jwt.io/introduction/](https://jwt.io/introduction/). +For an in-depth explanation please visit [https://jwt.io/introduction/](https://jwt.io/introduction/). Teleport JWTs include three sections: @@ -24,7 +29,7 @@ Teleport JWTs include three sections: ### Header -**Example Header** +*Example Header* ```json { @@ -35,36 +40,39 @@ Teleport JWTs include three sections: ### Payload -**Example Payload** +*Example Payload* ```json { "aud": [ "http://127.0.0.1:34679" ], - "exp": 1603943800, "iss": "aws", "nbf": 1603835795, + "sub": "alice", + // Teleport user name. + "username": "alice" + // Teleport user roles. "roles": [ "admin" ], - "sub": "benarent", - "username": "benarent" + // Teleport identity expiration. + "exp": 1603943800, } ``` The JWT will be sent with the header: `Teleport-Jwt-Assertion`. -**Example Teleport JWT Assertion** +*Example Teleport JWT Assertion* ```json eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiaHR0cDovLzEyNy4wLjAuMTozNDY3OSJdLCJleHAiOjE2MDM5NDM4MDAsImlzcyI6ImF3cyIsIm5iZiI6MTYwMzgzNTc5NSwicm9sZXMiOlsiYWRtaW4iXSwic3ViIjoiYmVuYXJlbnQiLCJ1c2VybmFtZSI6ImJlbmFyZW50In0.PZGUyFfhEWl22EDniWRLmKAjb3fL0D4cTmkxEfb-Q30hVMzVhka5WB8AUsPsLPVhTzsQ6Nkk1DnXHdz6oxrqDDfumuRrDnpJpjiXj_l0D3bExrchN61enzBHxSD13VkRIqP1V6l4i8yt8kXDIBWc-QejLTodA_GtczkDfnnpuAfaxIbD7jEwF27KI4kZu7uES9LMu2iCLdV9ZqarA-6HeDhXPA37OJ3P6eVQzYpgaOBYro5brEiVpuJLr1yA0gncmR4FqmhCpCj-KmHi2vmjmJAuuHId6HZoEZJjC9IAsNlrSA4GHH9j82o7FF1F4J2s38bRy3wZv46MT8X8-QBSpg ``` -## Validate JWT with JSON Web Key Set (JWKS) +## Validate JWT -Teleport provides a `jwks` endpoint to verify that the JWT can be trusted. This -endpoint is `https://[cluster-name]:3080/.well-known/jwks.json`: +Teleport provides a JSON Web Key Set (`jwks`) endpoint to verify that the JWT +can be trusted. This endpoint is `https://[cluster-name]:3080/.well-known/jwks.json`: *Example jwks.json* @@ -80,3 +88,6 @@ endpoint is `https://[cluster-name]:3080/.well-known/jwks.json`: ] } ``` + +See the example Go program used to validate Teleport's JWT tokens on our +[Github](https://github.com/gravitational/teleport/blob/v6.0.2/examples/jwt/verify-jwt.go).