mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-04 19:12:46 +08:00
Zac Bergquist
c924be5c6d
The `tsh appps` family of commands is aliased to `tsh apps`, so both invocations work correctly. The command itself is defined as `tsh apps`, so this is what appears in the help message. Update references to `tsh app` to recommend `tsh apps` instead so that there isn't confusion when browsing `tsh help` and looking for a missing `app` subcommand. Fixes #21367
148 lines
4.8 KiB
Plaintext
148 lines
4.8 KiB
Plaintext
---
|
|
title: Access REST APIs With Teleport Application Access
|
|
description: How to access REST APIs with Teleport Application Access.
|
|
---
|
|
|
|
# Application API Access
|
|
|
|
Teleport Application Access can be used to access applications' (REST or Teleport's own gRPC) APIs with
|
|
tools like [curl](https://man7.org/linux/man-pages/man1/curl.1.html) 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](../getting-started.mdx)
|
|
guide or the general [App Access Usage](./connecting-apps.mdx) guide to connect the web application providing an API to Teleport.
|
|
|
|
For simplicity's sake, we'll use Grafana running in a
|
|
[Docker container](https://grafana.com/docs/grafana/latest/installation/docker/)
|
|
and execute API queries against it. You can launch Grafana too with a single Docker
|
|
command:
|
|
|
|
```code
|
|
$ 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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```code
|
|
$ 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:
|
|
|
|
```code
|
|
$ 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.
|
|
|
|
<Admonition
|
|
type="note"
|
|
title="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.
|
|
|
|
<ScopedBlock scope={["oss", "enterprise"]}>
|
|
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>`.
|
|
</ScopedBlock>
|
|
</Admonition>
|
|
|
|
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:
|
|
|
|
```code
|
|
$ 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:
|
|
|
|
```code
|
|
$ tsh apps logout
|
|
# Logged out of app "grafana"
|
|
```
|
|
|
|
## Application information
|
|
|
|
```code
|
|
$ 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:
|
|
|
|
```code
|
|
$ 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:
|
|
|
|
```code
|
|
$ 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:
|
|
|
|
```code
|
|
$ curl --user admin:admin \
|
|
--cert $(tsh apps config --format=cert) \
|
|
--key $(tsh apps config --format=key) \
|
|
$(tsh apps config --format=uri)/api/users
|
|
```
|