From a20f85a530bc84a3f9f760068e5a049e3f40c313 Mon Sep 17 00:00:00 2001 From: Roman Tkachenko Date: Wed, 17 Mar 2021 17:15:46 -0700 Subject: [PATCH 1/2] Update application access docs --- docs/config.json | 21 +- docs/pages/application-access.mdx | 344 ++---------------- .../application-access/getting-started.mdx | 112 ++++++ docs/pages/application-access/guides.mdx | 10 + .../application-access/guides/api-access.mdx | 133 +++++++ docs/pages/application-access/guides/jwt.mdx | 82 +++++ .../pages/application-access/guides/usage.mdx | 273 ++++++++++++++ docs/pages/application-access/reference.mdx | 105 ++++++ 8 files changed, 766 insertions(+), 314 deletions(-) create mode 100644 docs/pages/application-access/getting-started.mdx create mode 100644 docs/pages/application-access/guides.mdx create mode 100644 docs/pages/application-access/guides/api-access.mdx create mode 100644 docs/pages/application-access/guides/jwt.mdx create mode 100644 docs/pages/application-access/guides/usage.mdx create mode 100644 docs/pages/application-access/reference.mdx diff --git a/docs/config.json b/docs/config.json index d862d3fb1a964..9ef2d666d7b8f 100644 --- a/docs/config.json +++ b/docs/config.json @@ -5,12 +5,12 @@ "title": "Documentation", "entries": [ { "title": "Introduction", "slug": "/" }, - { "title": "Getting Started", "slug": "/getting-started/" }, + { "title": "Getting Started", "slug": "/getting-started/" }, { "title": "Installation", "slug": "/installation/" }, { "title": "Application Access", "slug": "/application-access/" }, { "title": "Kubernetes Access", "slug": "/kubernetes-access/" }, { "title": "Database Access", "slug": "/database-access/" }, - { "title": "Cloud", "slug": "/cloud/" }, + { "title": "Cloud", "slug": "/cloud/" }, { "title": "User Manual", "slug": "/user-manual/" }, { "title": "Admin Manual", "slug": "/admin-guide/" }, { "title": "Production Guide", "slug": "/production/" }, @@ -18,6 +18,23 @@ { "title": "Changelog", "slug": "/changelog/" } ] }, + { + "icon": "window", + "title": "Application Access", + "entries": [ + { "title": "Getting Started", "slug": "/application-access/getting-started/" }, + { + "title": "Guides", + "slug": "/application-access/guides/", + "entries": [ + { "title": "General Usage", "slug": "/application-access/guides/usage/" }, + { "title": "Integrating with JWT", "slug": "/application-access/guides/jwt/" }, + { "title": "API Access", "slug": "/application-access/guides/api-access/" } + ] + }, + { "title": "Reference", "slug": "/application-access/reference/" } + ] + }, { "icon": "kubernetes", "title": "Kubernetes Access", diff --git a/docs/pages/application-access.mdx b/docs/pages/application-access.mdx index ec0f05d7dab6d..dadec20d61d13 100644 --- a/docs/pages/application-access.mdx +++ b/docs/pages/application-access.mdx @@ -1,19 +1,20 @@ --- title: Application Access Guide description: How to set up and configure Teleport for Application access with SSO and RBAC -h1: Application Access Guide --- -## Introduction +# 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 now put applications onto the internet safely and securely. +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: -- Internal control panels +- Internal control panels. - Wikis / Tooling that's only available on the VPN. -- Infra dashboards - Kubernetes, Grafana -- Developer tools, such as Jenkins, Gitlab or Opsgenie +- Infra dashboards - Kubernetes, Grafana. +- Developer tools, such as Jenkins, Gitlab or Opsgenie. ## Demo @@ -37,321 +38,40 @@ You can secure any web application using application access: Your browser does not support the video tag. -### Hardware Requirements +## Getting Started -[How it works](https://gravitational.com/teleport/how-it-works/) page will give you a good overview of the setup. +Get started with Application Access in a 10 minute [guide](./application-access/getting-started.mdx). -### Networking Requirements +## Guides - - Teleport uses SSH reverse tunnels to connect applications to the proxy. This is why the configuration below mentions SSH ports. - - -| Port | Service | Description | -| - | - | - | -| 3023 | Proxy | SSH port for clients who need tsh login | -| 3024 | Proxy | SSH port used to create reverse SSH tunnels from behind-firewall environments into a trusted proxy server. | -| 3025 | Auth | TLS port used by the Auth Service to serve its API to other nodes in a cluster. | -| 3080 | Proxy | HTTPS connection to authenticate `tsh` users and web users into the cluster. The same connection is used to serve a Teleport UI. | - -### TLS Requirements - -TLS is required to secure Teleport's Unified Access Plane and any connected applications. When setting up Teleport, the minimum requirement is a certificate for the proxy and a wildcard certificate for its sub-domain. This is where everyone will log into Teleport. - -Example: `teleport.example.com` will host the Access Plane. `*.teleport.example.com` will host all of the applications e.g. `jenkins.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. - -```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 -``` - - - 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 Application Service Setup - -There are two options for running Teleport, once installed it can be set up with -inline options using `teleport start` or using a `teleport.yaml` config file. - -### Starting Teleport - -| Variable to replace | Description | -| - | - | -| `--roles=app` | The 'app' role will set up the reverse proxy for applications | -| `--token` | A dynamic or static `app` token obtained from the root cluster | -| `--auth-server` | URL of the root cluster auth server or public proxy address | -| `--app-name` | Application name | -| `--app-uri` | URI and Port of Application | - -```sh -teleport start --roles=app --token=xyz --auth-server=proxy.example.com:3080 \ - --app-name="example-app" \ - --app-uri="http://localhost:8080" -``` - -### 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). - -After Teleport is running, the application will be accessible at `app-name.proxy_public_addr.com` e.g. `jenkins.teleport.example.com`. Teleport also provides the ability to override `public_addr`. e.g `jenkins.acme.com` if you configure the appropriate DNS entry to point to the Teleport proxy server. - -### Starting Teleport with config file - -**Define `/etc/teleport.yaml`** - -| Variable to replace | Description | -| - | - | -| `auth_token` & `tokens` | Example static join tokens | -| `proxy_service: public_addr` | Public URL and Port for Teleport. | -| `https_keypairs` | HTTPS TLS Certificate key pairs | -| `-key_file` | LetsEncrypt Key File | -| `-cert_file` | LetsEncrypt Cert File | -| `app_service: enabled: yes` | Application Service should be enabled | -| `apps: name` | Application Name | -| `apps: uri` | URL and port of application | - -```yaml -teleport: - data_dir: /var/lib/teleport - auth_token: a3aff444e182cf4ee5c2f78ad2a4cc47d8a30c95747a08f8 -auth_service: - enabled: "yes" - listen_addr: 0.0.0.0:3025 - tokens: - - proxy,node,app:a3aff444e182cf4ee5c2f78ad2a4cc47d8a30c95747a08f8 -ssh_service: - enabled: "false" -app_service: - enabled: yes - # We've a small debug app that can be used to make sure application - # Access is working correctly. It'll output JWTs so it can be useful - # for when extending your application. - debug_app: true - apps: - - name: "kubernetes-dashboard" - # URI and port of application. - uri: "https://localhost:3040" - # Optional Label: These can be used in combination with RBAC rules - # to limit access to applications - labels: - env: "prod" - # Optional Dynamic Labels - commands: - - name: "os" - command: ["/usr/bin/uname"] - period: "5s" -proxy_service: - enabled: "yes" - listen_addr: 0.0.0.0:3023 - # Public address defaults to port 3080 which doesn't - # require Teleport starting as root - public_addr: teleport.example.com:443 - # Example using a wildcard cert - 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 -``` - -#### [Optional] Obtain a new App Token - -In the above example we've hard coded a join token `a3aff444e182cf4ee5c2f78ad2a4cc47d8a30c95747a08f8`. You can use this to join apps or create a dynamic token using the `tctl` command below. - -```bash -$ tctl tokens add --type=app -``` - -## Advanced Options - -### Running Debug Application - -For testing and debugging purposes we provide an inbuilt debugging app. This can be turned on use `debug_app: true`. - -```yaml -app_service: - enabled: yes - debug_app: true -``` - -### Customize Public Address - -```yaml - - name: "jira" - uri: "https://localhost:8001" - public_addr: "jira.example.com" -``` - -### Skip TLS certificate verification - -Corporations often use self-signed certificates for internal applications. Teleport attempts to check if the certificates are signed by a trusted CA (Certificate Authority). If using self-signed certificates use `insecure_skip_verify: true` to skip this verification step. - -```yaml - - name: "app" - uri: "https://localhost:8443" - public_addr: "app.example.com" - insecure_skip_verify: true -``` - -### Deeplink to Subdirectory - -Some Applications are available on a Subdirectory, examples include the [Kubernetes Dashboard.](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/). The URI should be updated to include -the subdirectory. - -```yaml - - name: "k8s" - uri: "http://10.0.1.60:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/#/overview?namespace=default" - public_addr: "k8s.example.com" -``` - -### Rewrite - -We provide simple rewrites. This is helpful for applications that provide internal redirect -headers. - -```yaml - - name: "jira" - uri: "https://localhost:8001" - public_addr: "jira.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" -``` - -## View Applications in Teleport - -Teleport provides a UI for quickly launching connected applications. They can be -viewed by navigating to a cluster and selecting Applications. The URL structure is -below. - -`https://[cluster-url:cluster-port]/web/cluster/[cluster-name]/apps` - -## Logging out of Applications - -When you log into an application, you'll get a certificate and login session per your defined RBAC. If you want to force logout before this period you can force a log out by hitting the `/teleport-logout` endpoint: - -[https://internal-app.teleport.example.com/teleport-logout](https://internal-app.teleport.example.com/teleport-logout) - -## Integrating with JWTs - -### 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/) - -Teleport JSON Web Tokens (JWT) include three sections: - -- Header -- Payload -- Signature - -### Header - -**Example Header** - -```json -{ - "alg": "RS256", - "typ": "JWT" -} -``` - -### Payload - -**Example Payload** - -```json -{ - "aud": [ - "http://127.0.0.1:34679" - ], - "exp": 1603943800, - "iss": "aws", - "nbf": 1603835795, - "roles": [ - "admin" - ], - "sub": "benarent", - "username": "benarent" -} -``` - -The JWT will be sent with the header: `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) - -Teleport provides a jwks endpoint to verify that the JWT 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" - } - ] -} -``` +* [Application Access Usage](./application-access/guides/usage.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. +As outlined in our introduction, Application Access has been designed to +support two types of applications. -**Example Legacy App**
-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. These applications are supported and can extend access beyond your network. +### Example Legacy App + +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. +These applications are supported and can extend access beyond your network. Other example legacy apps: -- An internal admin tool -- Control panel for networking devices +- An internal admin tool. +- Control panel for networking devices. + +### Example Modern App -**Example Modern App**
-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 all modern applications, these could be +built in-house or off-the-shelf software such as Jenkins, Kubernetes Dashboard +and Jupyter workbooks. -- Kubernetes Internal Dashboard -- Grafana -- Jupyter notebooks -- In-house Single Page Apps (SPA) -- SPA with custom JSON Web Token (JWT) support +- Kubernetes Internal Dashboard. +- Grafana. +- Jupyter notebooks. +- In-house Single Page Apps (SPA). +- 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 new file mode 100644 index 0000000000000..0661ea6054a7c --- /dev/null +++ b/docs/pages/application-access/getting-started.mdx @@ -0,0 +1,112 @@ +--- +title: Application Access Getting Started Guide +description: Getting started with Teleport Application Access +--- + +# Getting Started + +Let's connect to Grafana using Teleport Application Access. + +To achieve this we will: + +1. Launch Grafana in a Docker container. +2. Install Teleport and configure it it to proxy Grafana. +3. Access Grafana through Teleport. + +## 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`. + +## Step 1/3. Start Grafana + +We've picked Grafana for this tutorial since it's very easy to run with zero +configuration required. If you have another web application you'd like to +expose, skip over to Step 2. + +Grafana can be launched in a [Docker container](https://grafana.com/docs/grafana/latest/installation/docker/) +with a single command: + +```sh +$ 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 +[downloads page](https://goteleport.com/teleport/download). + +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. + +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's ACME protocol integration currently requires web proxy to run on + port 443. + + +Now start Teleport and point it to the application endpoint: + +```shell +$ sudo teleport start --config=/tmp/teleport.yaml \ + --roles=proxy,auth,app \ + --app-name=grafana \ + --app-uri=http://localhost:3000 +``` + +Make sure to update `--app-name` and `--app-uri` accordingly if you're using +your own web application. + +Next let's create a user that access to the application we've just connected. +Teleport has a built-in role called `access` that allows users to access cluster +resources. Create a local user assigned this role: + +```sh +$ tctl users add --roles=access alice +``` + +The command will output a signup link. Use it to choose a password and set up +second factor. After that it will take you to the Teleport web UI. + +## Step 3/3. Access the Application + +There are a couple of ways to access the proxied application. + +Every application is assigned a public address which you use to navigate to +the application directly. In our sample Grafana application we have provided a public address with +the `--app-public-addr` flag, so go to https://grafana.teleport.example.com +(replace with your app public address) to access the app. If you're not logged into Teleport, +you will need to authenticate before the application will show. + +Alternatively, log into the Teleport web UI at https://teleport.example.com +(replace with your proxy public address). All available applications are +displayed on the Applications tab. Click on the Grafana application tile +to access it. + +## Next Steps + +Dive deeper into the topics relevant to your Application Access use-case: + +* Learn in more detail about Application Access [usage](./guides/usage.mdx). +* 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 new file mode 100644 index 0000000000000..999ebdbc1c72d --- /dev/null +++ b/docs/pages/application-access/guides.mdx @@ -0,0 +1,10 @@ +--- +title: Application Access Guides +description: Guides for configuring Teleport Application Access +--- + +# Guides + +- [Application Access Usage](./guides/usage.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 new file mode 100644 index 0000000000000..bacb64a6f7403 --- /dev/null +++ b/docs/pages/application-access/guides/api-access.mdx @@ -0,0 +1,133 @@ +--- +title: Using Application Access to Access APIs +description: How to access RESTful APIs using Teleport Application Access +--- + +# API Access + +Application Access can be used to access applications' RESTful APIs with +tools like [curl](https://man7.org/linux/man-pages/man1/curl.1.html) or +[Postman](https://www.postman.com/). + +## Prerequisites + +We will assume that you followed the [Getting Started](../getting-started.mdx) +guide or the general [App Access Usage](./usage.mdx) guide to connect the web +application providing an API to Teleport. + +For the simplicity of the guide, we will be using Grafana running in a +[Docker container](https://grafana.com/docs/grafana/latest/installation/docker/) +and run API queries against it. You can launch Grafana too with a single Docker +command: + +```sh +$ docker run -d -p 3000:3000 grafana/grafana +``` + +Connect Grafana to your Teleport cluster by adding the following section in +the Teleport App Service configuration file: + +```yaml +app_service: + enabled: yes + apps: + - name: "grafana" + description: "Test Grafana server" + uri: "http://localhost:3000" +``` + +## Accessing API + +Log into your Teleport cluster and view available applications: + +```sh +$ tsh login --proxy=teleport.example.com:3080 +$ tsh app ls +Application Description Public Address Labels +----------- ------------------- ---------------------------- ------ +grafana Test Grafana server grafana.teleport.example.com +``` + +Retrieve short-lived X.509 certificate for the application: + +```sh +$ tsh app login grafana +Logged into app grafana. Example curl command: + +curl \ + --cacert /Users/alice/.tsh/keys/teleport.example.com/certs.pem \ + --cert /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem \ + --key /Users/alice/.tsh/keys/teleport.example.com/alice \ + https://grafana.teleport.example.com:3080 +``` + +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. + +As Grafana's API requires authentication, let's update the `curl` command to +provide basic auth information using default Grafana username/password and +call its `/api/users` endpoint: + +```sh +$ curl --user admin:admin \ + --cacert /Users/alice/.tsh/keys/teleport.example.com/certs.pem \ + --cert /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem \ + --key /Users/alice/.tsh/keys/teleport.example.com/alice \ + https://grafana.teleport.example.com:3080/api/users +[{"id":1,"name":"","login":"admin","email":"admin@localhost","avatarUrl":"/avatar/46d229b033af06a191ff2267bca9ae56","isAdmin":true,"isDisabled":false,"lastSeenAt":"2021-03-18T17:25:59Z","lastSeenAtAge":"\u003c 1m","authLabels":[]}] +``` + +The app's X.509 certificate will expire on its own after the TTL allowed by +your user's role. You can also remove it explicitly: + +```sh +$ tsh app logout +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 +when configuring CLI tools (such as `curl`) or GUI tools (such as Postman). + +Let's print the app information in a table format: + +```sh +$ tsh app config +Name: grafana +URI: https://grafana.teleport.example.com:3080 +CA: /Users/alice/.tsh/keys/teleport.example.com/certs.pem +Cert: /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem +Key: /Users/alice/.tsh/keys/teleport.example.com/alice +``` + +We can also provide different `--format` values to print specific parts +of the app configuration: + +```sh +$ tsh app config --format=uri +https://grafana-root.gravitational.io:3080 + +$ tsh app config --format=ca +/Users/alice/.tsh/keys/teleport.example.com/certs.pem + +$ tsh app config --format=cert +/Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem + +$ tsh app config --format=key +/Users/alice/.tsh/keys/teleport.example.com/alice +``` + +This can be useful in automation for simple templating e.g. to construct an +appropriate `curl` command. Using our Grafana `/api/users` example above: + +```sh +$ curl --user admin:admin \ + --cacert $(tsh app config --format=ca) \ + --cert $(tsh app config --format=cert) \ + --key $(tsh app config --format=key) \ + $(tsh app config --format=uri)/api/users +``` diff --git a/docs/pages/application-access/guides/jwt.mdx b/docs/pages/application-access/guides/jwt.mdx new file mode 100644 index 0000000000000..8790dd838ece4 --- /dev/null +++ b/docs/pages/application-access/guides/jwt.mdx @@ -0,0 +1,82 @@ +--- +title: Using Application Access JWT Tokens +description: How to integrate use JWT tokens authentication with Application Access +--- + +# 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. + +## 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/). + +Teleport JWTs include three sections: + +- Header +- Payload +- Signature + +### Header + +**Example Header** + +```json +{ + "alg": "RS256", + "typ": "JWT" +} +``` + +### Payload + +**Example Payload** + +```json +{ + "aud": [ + "http://127.0.0.1:34679" + ], + "exp": 1603943800, + "iss": "aws", + "nbf": 1603835795, + "roles": [ + "admin" + ], + "sub": "benarent", + "username": "benarent" +} +``` + +The JWT will be sent with the header: `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) + +Teleport provides a `jwks` endpoint to verify that the JWT 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" + } + ] +} +``` diff --git a/docs/pages/application-access/guides/usage.mdx b/docs/pages/application-access/guides/usage.mdx new file mode 100644 index 0000000000000..0cd7624331dc7 --- /dev/null +++ b/docs/pages/application-access/guides/usage.mdx @@ -0,0 +1,273 @@ +--- +title: Using Application Access Guide +description: How to configure Teleport for Application Access +--- + +# Application Access Usage + +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). + +## Start Auth/Proxy Service + +Create a configuration file for a Teleport service that will be running +auth and proxy servers: + +```yaml +teleport: + data_dir: /var/lib/teleport +auth_service: + enabled: "yes" +proxy_service: + enabled: "yes" + # Set public address proxy will be reachable at. + public_addr: teleport.example.com:3080 +ssh_service: + enabled: "no" +``` + +Start the service: + +```sh +$ teleport start --config=/path/to/teleport.yaml +``` + +### Generate Token + +A join token is required to authorize a Teleport Application Proxy service to +join the cluster. Generate a short-lived join token and save it for example +in `/tmp/token`: + +```sh +$ tctl tokens add \ + --type=app \ + --app-name=grafana \ + --app-uri=http://localhost:3000 +``` + +### TLS Requirements + +TLS is required to secure Teleport's Unified Access Plane and any connected +applications. When setting up Teleport, the minimum requirement is a certificate +for the proxy and a wildcard certificate for its sub-domain. This is where +everyone will log into Teleport. + +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. + +```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 +``` + + + 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" + ``` + + +### Create a User + +In order to be able to access the application, a Teleport user needs to have +a role that allows them to see it. + +Teleport comes with a built-in `access` role that provides access to all +applications: + +```sh +$ tctl --config=/path/to/teleport.yaml users add --roles=access appuser +``` + +## Start Application Service with CLI Flags + +A Teleport Application Proxy agent can be started with a single CLI command: + +```sh +$ teleport start \ + --roles=app \ + --token=/tmp/token \ + --auth-server=teleport.example.com:3080 \ + --app-name="grafana" \ + --app-uri="http://localhost:3000" \ + --labels=env=dev +``` + +Note that the `--auth-server` flag must point to the Teleport cluster's proxy +endpoint because the application service always connects back to the cluster over +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). + +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. + +## Start Application Service with Config File + +Example `/etc/teleport-app.yaml` configuration: + +```yaml +teleport: + # Data directory for the Application Proxy service. If running on the same + # node as Auth/Proxy service, make sure to use different data directories. + data_dir: /var/lib/teleport-app + # Instructs the service to load the join token from the specified file + # during initial registration with the cluster. + auth_token: /tmp/token + # Proxy address to connect to. Note that it has to be the proxy address + # because the app service always connects to the cluster over a reverse + # tunnel. + auth_servers: + - teleport.example.com:3080 +app_service: + enabled: yes + # Teleport provides a small debug app that can be used to make sure application + # access is working correctly. It'll output JWTs so it can be useful + # when extending your application. + debug_app: true + # This section contains definitions of all applications proxied by this + # service. It can contain multiple items. + apps: + # Name of the application. Used for identification purposes. + - name: "grafana" + # URI and port the application is available at. + uri: "http://localhost:3000" + # Optional application public address to override. + public_addr: "grafana.teleport.example.com" + # Optional static labels to assign to the app. Used in RBAC. + labels: + env: "prod" + # Optional dynamic labels to assign to the app. Used in RBAC. + commands: + - name: "os" + command: ["/usr/bin/uname"] + period: "5s" +auth_service: + enabled: "no" +ssh_service: + enabled: "no" +proxy_service: + enabled: "no" +``` + +Start the application service: + +```sh +$ teleport start --config=/etc/teleport-app.yaml +``` + +## Advanced Options + +### Running Debug Application + +For testing and debugging purposes we provide a built-in debug app. It can +be turned on using `debug_app: true`. + +```yaml +app_service: + enabled: yes + debug_app: true +``` + +The app will dump all the request headers in the response. + +### Customize Public Address + +By default applications are available at `.:` +address. To override the public address, specify the `public_addr` field: + +```yaml +- name: "jira" + uri: "https://localhost:8001" + public_addr: "jira.example.com" +``` + +### 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: + +```yaml +- name: "app" + uri: "https://localhost:8443" + public_addr: "app.example.com" + insecure_skip_verify: true +``` + +### Deeplink to Subdirectory + +Some applications are available on a subdirectory. Examples include the +[Kubernetes Dashboard.](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/). +The URI should be updated to include the subdirectory: + +```yaml +- name: "k8s" + uri: "http://10.0.1.60:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/#/overview?namespace=default" + public_addr: "k8s.example.com" +``` + +### Rewrite + +Application access supports simple rewrites. This is helpful for applications +that provide internal redirect headers: + +```yaml +- name: "jira" + uri: "https://localhost:8001" + public_addr: "jira.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" +``` + +## View Applications in Teleport + +Teleport provides a UI for quickly launching connected applications. + +They can be viewed by navigating to a cluster's web UI and selecting the Applications tab. +The URL structure looks like this: + +`https://[cluster-url:cluster-port]/web/cluster/[cluster-name]/apps` + +## Logging out of Applications + +When you log into an application, you'll get a certificate and login session +per your defined RBAC. If you want to force logout before this period you can +do so by hitting the `/teleport-logout` endpoint: + +[https://internal-app.teleport.example.com/teleport-logout](https://internal-app.teleport.example.com/teleport-logout) diff --git a/docs/pages/application-access/reference.mdx b/docs/pages/application-access/reference.mdx new file mode 100644 index 0000000000000..cb616c035b664 --- /dev/null +++ b/docs/pages/application-access/reference.mdx @@ -0,0 +1,105 @@ +--- +title: Application Access Reference +description: Configuration and CLI reference for Teleport Application Access +--- + +# Application Access Reference + +## Configuration + +The following snippet shows full YAML configuration of an Application Service +appearing in the `teleport.yaml` configuration file: + +```yaml +app_service: + # Enables application proxy service. + enabled: yes + # Enable debug app that can be used to make sure application access is + # working correctly. It'll output JWTs so it can be useful for when + # extending your application. + debug_app: true + # This section contains definitions of all applications proxied by this + # service. It can contain multiple items. + apps: + # Name of the application. Used for identification purposes. + - name: "grafana" + # Free-form application description. + description: "This is an internal Grafana instance" + # URI and port the application is available at. + uri: "http://localhost:3000" + # Optional application public address to override. + public_addr: "grafana.teleport.example.com" + # Rewrites section. + rewrite: + # Rewrite the "Location" header on redirect responses replacing the + # host with the public address of this application. + redirect: + - "grafana.internal.dev" + # Disable application certificate validation. + insecure_skip_verify: true + # Optional static labels to assign to the app. Used in RBAC. + labels: + env: "prod" + # Optional dynamic labels to assign to the app. Used in RBAC. + commands: + - name: "hostname" + command: ["hostname"] + period: 1m0s +``` + +## CLI + +This section shows CLI commands relevant for Application Access. + +### tsh app ls + +Lists available applications. + +```sh +$ tsh app ls +``` + +### tsh app login + +Retrieves short-lived X.509 certificate for CLI application access. + +```sh +$ tsh app login grafana +``` + +### tsh app logout + +Removes CLI application access certificate. + +```sh +# Log out of a particular app. +$ tsh app logout grafana + +# Log out of all apps. +$ tsh app logout +``` + +### tsh app config + +Prints application connection information. + +```sh +# Print app information in a table form. +$ tsh app config + +# Print information for a particular app. +$ tsh app config grafana + +# Print an example curl command. +$ tsh app config --format=curl + +# Construct a curl command. +$ curl $(tsh app config --format=uri) \ + --cacert $(tsh app config --format=ca) \ + --cert $(tsh app config --format=cert) \ + --key $(tsh app config --format=key) +``` + +| Flag | Description | +| - | - | +| `--format` | Optional print format, one of: `uri` to print app address, `ca` to print CA cert path, `cert` to print cert path, `key` print key path, `curl` to print example curl command.| From 82603301a96977ddd54b6b1028765300bb0e4c27 Mon Sep 17 00:00:00 2001 From: Roman Tkachenko Date: Tue, 23 Mar 2021 08:41:35 -0700 Subject: [PATCH 2/2] 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).