teleport/docs/pages/application-access/reference.mdx

---
title: Application Access Reference Documentation
description: Configuration and CLI reference documentation for Teleport application access.
---

## Configuration

(!docs/pages/includes/backup-warning.mdx!)

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

```yaml
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"
```

## Application resource

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

```yaml
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:

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">

```code
# 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
```

</TabItem>
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">

```code
# 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
```

</TabItem>

</Tabs>

## CLI

This section shows CLI commands relevant for application access.

### tsh apps ls

Lists available applications.

```code
$ tsh apps ls
```

### tsh apps login

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

```code
$ 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.

```code
# 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.

```code
# 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:

```code
$ tsh az <command>
```

`<command>`: A valid command within the `az` CLI, including arguments and flags.
See the [Azure
documentation](https://learn.microsoft.com/en-us/cli/azure/reference-index?view=azure-cli-latest)
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](cloud-apis/azure.mdx).