Application Access Reference Documentation

This guide describes interfaces and options for interacting with the Teleport Application Service, including the static configuration file for the teleport binary, the dynamic app resource, and tsh apps commands.

Configuration

Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

The following snippet shows the full YAML configuration of an Application Service appearing in the teleport.yaml configuration file:

app_service:
  # Enables application proxy service.
  enabled: yes
  # Teleport provides a small debug app called "dumper" that can be used
  # to make sure application access is working correctly. It outputs JWTs,
  #  so it can be useful when extending your application.
  debug_app: true
  # Matchers for application resources created with "tctl create" command.
  resources:
  - labels:
      "*": "*"
  # This section contains definitions of all applications proxied by this
  # service. It can contain multiple items.
  apps:
    # Name of the application. Used for identification purposes.
  - name: "grafana"
    # Free-form application description.
    description: "This is an internal Grafana instance"
    # URI and port the application is available at.
    uri: "http://localhost:3000"
    # Optional application public address to override.
    public_addr: "grafana.teleport.example.com"
    # Rewrites section.
    rewrite:
      # Rewrite the "Location" header on redirect responses replacing the
      # host with the public address of this application.
      redirect:
      - "grafana.internal.dev"
      # Headers passthrough configuration.
      headers:
      - "X-Custom-Header: example"
      - "X-External-Trait: {{external.env}}"
    # Disable application certificate validation.
    insecure_skip_verify: true
    # Optional static labels to assign to the app. Used in RBAC.
    labels:
      env: "prod"
    # Optional dynamic labels to assign to the app. Used in RBAC.
    commands:
    - name: "hostname"
      command: ["hostname"]
      period: 1m0s
    # Optional AWS-specific configurations.
    aws:
      # External ID used when assuming AWS roles for this application.
      external_id: "example-external-id"
  - name: "azure-cli"
    # Optional: For access to cloud provider APIs, specify the cloud provider.
    # Allowed values are "AWS", "Azure", and "GCP".
    cloud: "Azure"

For full details on configuring Teleport roles, including how Teleport populates the external traits, see the Teleport Access Controls Reference.

Application resource

Full YAML spec of application resources managed by tctl resource commands:

kind: app
version: v3
metadata:
  # Application name.
  name: example
  # Application description.
  description: "Example application"
  # Application static labels.
  labels:
    env: local
spec:
  # URI and port application is available at.
  uri: http://localhost:4321
  # Optional application public address.
  public_addr: test.example.com
  # Disable application certificate validation.
  insecure_skip_verify: true
  # Rewrites configuration.
  rewrite:
    # Rewrite the "Location" header on redirect responses replacing the
    # host with the public address of this application.
    redirect:
    - "grafana.internal.dev"
    # Headers passthrough configuration.
    headers:
    - name: "X-Custom-Header"
      value: "example"
    - name: "X-External-Trait"
      value: "{{external.env}}"
  # Optional dynamic labels.
  dynamic_labels:
  - name: "hostname"
    command: ["hostname"]
    period: 1m0s

You can create a new app resource by running the following commands, which assume that you have created a YAML file called app.yaml with your configuration:

Self-Hosted

# Log in to your cluster with tsh so you can use tctl from your local machine.
# You can also run tctl on your Auth Service host without running "tsh login"
# first.
$ tsh login --proxy=teleport.example.com --user=myuser
# Create the resource
$ tctl create -f app.yaml

Teleport Enterprise Cloud

# Log in to your cluster with tsh so you can use tctl from your local machine.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
# Create the resource.
$ tctl create -f app.yaml

CLI

This section shows CLI commands relevant for application access.

tsh apps ls

Lists available applications.

$ tsh apps ls

tsh apps login

Retrieves short-lived X.509 certificate for CLI application access.

$ tsh apps login grafana

Flag	Description
--aws-role	For AWS CLI access, the role ARN or role name of an AWS IAM role.
--azure-identity	For Azure CLI access, the name or URI of an Azure managed identity to use for accessing the Azure CLI.

tsh apps logout

Removes CLI application access certificate.

# Log out of a particular app.
$ tsh apps logout grafana

# Log out of all apps.
$ tsh apps logout

tsh apps config

Prints application connection information.

# Print app information in a table form.
$ tsh apps config

# Print information for a particular app.
$ tsh apps config grafana

# Print an example curl command.
$ tsh apps config --format=curl

# Construct a curl command.
$ curl $(tsh apps config --format=uri) \
  --cacert $(tsh apps config --format=ca) \
  --cert $(tsh apps config --format=cert) \
  --key $(tsh apps config --format=key)

Flag	Description
--format	Optional print format, one of: uri to print app address, ca to print CA cert path, cert to print cert path, key print key path, curl to print example curl command.

tsh az

Run an Azure CLI command via the Teleport Application Service:

$ tsh az <command>

<command>: A valid command within the az CLI, including arguments and flags. See the Azure documentation for the full list of az CLI commands.

To run this command, one of the user's roles must include the spec.allow.azure_identities field with one of the identities used by the Application Service. To learn how to set up secure access to Azure via Teleport, read Protect the Azure CLI with Teleport Application Access.