Teleport

Access REST APIs With Teleport Application Access

OpenSource
Enterprise
Cloud

Application API Access

Teleport Application Access can be used to access applications' (REST or Teleport's own gRPC) APIs with tools like curl or Postman.

Prerequisites

You will need a running Teleport cluster, either self hosted or in Teleport Cloud. We'll assume that you followed the Getting Started guide or the general App Access Usage guide to connect the web application providing an API to Teleport.

For simplicity's sake, we'll use Grafana running in a Docker container and execute API queries against it. You can launch Grafana too with a single Docker command:

docker run -d -p 3000:3000 grafana/grafana

Connect Grafana to your Teleport cluster by adding the following section in the Teleport App Service YAML configuration file:

app_service:
  enabled: yes
  apps:
  - name: "grafana"
    description: "Test Grafana server"
    uri: "http://localhost:3000"
    labels:
      "env": "dev"

Accessing the API

Log into your Teleport cluster and view available applications:

tsh login --proxy=teleport.example.com
tsh apps ls
Application Description         Public Address               Labels
----------- ------------------- ---------------------------- -------
grafana     Test Grafana server grafana.teleport.example.com env=dev

Retrieve short-lived X.509 certificate for the application:

tsh apps login grafana
Logged into app grafana. Example curl command:
curl \  --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.

CA and Key Pair Files

Note the paths to your user's certificate/key pair in the command - curl will use a client certificate to authenticate with Teleport.

The Teleport Proxy Service is usually configured with a wildcard certificate issued by a public certificate authority such as Let's Encrypt. If your Teleport Proxy Service has been configured to use a self-signed certificate instead, you will need to include it in your curl command using --cacert <path>.

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:

curl --user admin:admin \  --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":"[email protected]","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:

tsh apps logout
Logged out of app "grafana"

Application information

tsh apps 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:

tsh apps 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:

tsh apps config --format=uri
https://grafana-root.gravitational.io:3080
tsh apps config --format=ca
/Users/alice/.tsh/keys/teleport.example.com/certs.pem
tsh apps config --format=cert
/Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem
tsh apps 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:

curl --user admin:admin \  --cert $(tsh apps config --format=cert) \  --key $(tsh apps config --format=key) \    $(tsh apps config --format=uri)/api/users

Have a suggestion or can’t find something?

IMPROVE THE DOCS