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.comtsh app 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 app login grafanaLogged 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:
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":"[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 app logoutLogged out of app "grafana"
Application information
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:
tsh app 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 app config --format=urihttps://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:
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