![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Access REST APIs With Teleport Application Access
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
The Teleport Application Service can be used to access applications' (REST or Teleport's own gRPC) APIs with tools like curl or Postman.
Use TCP application access for non-HTTP APIs (like gRPC).
Prerequisites
-
A running Teleport cluster version 16.2.1 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
-
The
tctl
admin tool andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
-
To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials.For example:
tsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
If you can connect to the cluster and run the
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions. -
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/grafanaConnect 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.comtsh apps lsApplication 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 grafanaLogged 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.
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 you are
running a self-hosted Teleport cluster, and 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":"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:
tsh apps logoutLogged 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 configName: 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=urihttps://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