Meet us at KubeCon + CloudNativeCon: Paris, France - March 19
Book Demo
Teleport logoTry For Free
Fork me on GitHub

Teleport

Access REST APIs With Teleport Application Access

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

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

Non-HTTP API Support

Use TCP application access for non-HTTP APIs (like gRPC).

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 15.0.2.

    See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.3.6.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.6 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.6 go1.21

Proxy version: 14.3.6Proxy: teleport.example.com
  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 15.0.2.

    You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.6.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.6 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.6 go1.21

Proxy version: 14.3.6Proxy: teleport.example.com
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines.

    For example:

    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 15.0.2

    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 subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl 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/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 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 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