# Teleport Application Service Reference

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: true
  # 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:
      # Specify whether to include roles or traits in the JWT.
      # Options:
      # - roles-and-traits: include both roles and traits
      # - roles: include only roles
      # - traits: include only traits
      # - none: exclude both roles and traits from the JWT token
      # Default: roles-and-traits
      jwt_claims: roles-and-traits
      # 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 [Access Controls Reference](https://goteleport.com/docs/reference/access-controls/roles.md).

## 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](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](https://goteleport.com/docs/enroll-resources/application-access/cloud-apis/azure.md).