Version: 19.x (unreleased)

App V3 Reference

Is this page helpful?

Kind: app
Version: v3

The app resource represents an application that is dynamically registered with Teleport.

If you configure the Teleport Application Service with dynamic resource watchers, the service queries the Teleport backend for app resources that match their configured filters. For each matching app, the Application Service creates an app_server resource configured to proxy the target application.

To learn more about using the app resource, see Dynamic App Registration.

To learn more about the app_server resource, see the reference guide.

Top-level fields

Example:

kind: "string"
sub_kind: "string"
version: "string"
metadata: # [...]
spec: # [...]
scope: "string"

Field Name	Description	Type
kind	The app resource kind. Always "app".	string
metadata	The app resource metadata.	Metadata
scope	The App's scope.	string
spec	The app resource spec.	App Spec V3
sub_kind	An optional resource subkind.	string
version	The resource version. It must be specified. Supported values are:`v3`.	string

App AWS

Contains additional options for AWS applications.

Example:

external_id: "string"
roles_anywhere_profile: # [...]
region: "string"

Field Name	Description	Type
external_id	The AWS External ID used when assuming roles in this app.	string
region	A cloud region for the app. This field is set for apps that integrates with AWS applications/APIs.	string
roles_anywhere_profile	Contains the IAM Roles Anywhere fields associated with this Application. These fields are set when performing the synchronization of AWS IAM Roles Anywhere Profiles into Teleport Apps.	App AWS Roles Anywhere Profile

App AWS Roles Anywhere Profile

Contains the fields that represent an AWS IAM Roles Anywhere Profile.

Example:

profile_arn: "string"
accept_role_session_name: true

Field Name	Description	Type
accept_role_session_name	Whether this Roles Anywhere Profile accepts a custom role session name. When not supported, the AWS Session Name will be the X.509 certificate's serial number. When supported, the AWS Session Name will be the identity's username. This value comes from: https://docs.aws.amazon.com/rolesanywhere/latest/APIReference/API_ProfileDetail.html / acceptRoleSessionName	Boolean
profile_arn	The AWS IAM Roles Anywhere Profile ARN that originated this Teleport App.	string

App Identity Center

Encapsulates information about an AWS Identity Center account application.

Example:

account_id: "string"
permission_sets: 
  - # [...]
  - # [...]
  - # [...]

Field Name	Description	Type
account_id	Account ID is the AWS-assigned ID of the account	string
permission_sets	Lists the available permission sets on the given account	[]Identity Center Permission Set

App Spec V3

The AppV3 resource spec.

Example:

uri: "string"
public_addr: "string"
dynamic_labels: 
  "string": # [...]
  "string": # [...]
  "string": # [...]
insecure_skip_verify: true
rewrite: # [...]
aws: # [...]
cloud: "string"
UserGroups: 
  - "string"
  - "string"
  - "string"
integration: "string"
required_app_names: 
  - "string"
  - "string"
  - "string"
cors: # [...]
identity_center: # [...]
tcp_ports: 
  - # [...]
  - # [...]
  - # [...]
use_any_proxy_public_addr: true
mcp: # [...]
inference: # [...]
tls: # [...]

Field Name	Description	Type
UserGroups	A list of user group IDs that this app is associated with.	[]string
aws	Contains additional options for AWS applications.	App AWS
cloud	Identifies the cloud instance the app represents.	string
cors	Policy defines the Cross-Origin Resource Sharing settings for the app.	CORS Policy
dynamic_labels	The app's command labels.	map[string]Command Label V2
identity_center	Encapsulates information specific to AWS IAM Identity Center. Only valid for Identity Center account apps.	App Identity Center
inference	Contains LLM inference endpoint related configurations.	LLM
insecure_skip_verify	Disables app's TLS certificate verification.	Boolean
integration	The integration name that must be used to access this Application. Only applicable to AWS App Access. If present, the Application must use the Integration's credentials instead of ambient credentials to access Cloud APIs.	string
mcp	Contains MCP server related configurations.	MCP
public_addr	The public address the application is accessible at.	string
required_app_names	A list of app names that are required for this app to function. Any app listed here will be part of the authentication redirect flow and authenticate alongside this app.	[]string
rewrite	A list of rewriting rules to apply to requests and responses.	Rewrite
tcp_ports	A list of ports and port ranges that an app agent can forward connections to. Only applicable to TCP App Access. If this field is not empty, URI is expected to contain no port number and start with the tcp protocol.	[]Port Range
tls	Contains the app TLS configuration.	App TLS
uri	The web app endpoint.	string
use_any_proxy_public_addr	Will rebuild this app's fqdn based on the proxy public addr that the request originated from. This should be true if your proxy has multiple proxy public addrs and you want the app to be accessible from any of them. If `public_addr` is explicitly set in the app spec, setting this value to true will overwrite that public address in the web UI.	Boolean

App TLS

Contains the app TLS configuration.

Example:

mode: "string"
server_name: "string"
server_spiffe_id: "string"
allowed_cas: 
  - "string"
  - "string"
  - "string"
client_cert_mode: "string"

Field Name	Description	Type
allowed_cas	The list of user provided CAs used for verifying upstream certificates. Accepted values are PEM-encoded CA certificates and Teleport CA aliases. Supported aliases: "workload_identity" (workload Identity CA. Allows accepting certificates issued by `tbot`).	[]string
client_cert_mode	Specifies which client certificate mode to use for the upstream connection. Supported values: "managed" (app service will issue client certificates to use in the app upstream connection, establishing mTLS connections), "disabled" (app upstream connection won't use client certificates).	string
mode	Defines the TLS verification. Supported values: "verify-full" (performs certificate validation, and asserts server name and SPIFFE ID), "verify-server-name" (performs certificate validation, and asserts server name), "verify-spiffe-id": (performs certificate validation, and asserts SPIFFE ID. Requires `server_spiffe_id` option), "insecure": (accepts any certificate provided by app)	string
server_name	Specifies a custom hostname used for TLS verification against the upstream certificate.	string
server_spiffe_id	Specifies a SPIFFE ID that must be present on the server certificate.	string

CORS Policy

Defines the CORS policy for AppSpecV3

Example:

allowed_origins: 
  - "string"
  - "string"
  - "string"
allowed_methods: 
  - "string"
  - "string"
  - "string"
allowed_headers: 
  - "string"
  - "string"
  - "string"
allow_credentials: true
max_age: 1
exposed_headers: 
  - "string"
  - "string"
  - "string"

Field Name	Description	Type
allow_credentials	Allow_credentials indicates whether credentials are allowed.	Boolean
allowed_headers	Allowed_headers specifies which headers can be used when accessing the app.	[]string
allowed_methods	Allowed_methods specifies which methods are allowed when accessing the app.	[]string
allowed_origins	Allowed_origins specifies which origins are allowed to access the app.	[]string
exposed_headers	Exposed_headers indicates which headers are made available to scripts via the browser.	[]string
max_age	Max_age indicates how long (in seconds) the results of a preflight request can be cached.	number

Command Label V2

A label that has a value as a result of the output generated by running a command, e.g. hostname

Example:

period: # [...]
command: 
  - "string"
  - "string"
  - "string"
result: "string"

Field Name	Description	Type
command	A command to run	[]string
period	A time between command runs	Duration
result	Captures standard output	string

Duration

A wrapper around duration to set up custom marshal/unmarshal

Represents a single HTTP header passed over to the proxied application.

Example:

name: "string"
value: "string"

Field Name	Description	Type
name	The http header name.	string
value	The http header value.	string

Identity Center Permission Set

Defines a permission set that is available on an IdentityCenter account app

Example:

arn: "string"
name: "string"
assignment_name: "string"

Field Name	Description	Type
arn	The fully-formed ARN of the Permission Set.	string
assignment_name	The ID of the Teleport Account Assignment resource that represents this permission being assigned on the enclosing Account.	string
name	The human-readable name of the Permission Set.	string

LLM

Contains LLM inference endpoint related configurations.

Example:

format: "string"
provider: "string"
models: 
  - # [...]
  - # [...]
  - # [...]
fallback_model: "string"
quota: # [...]

Field Name	Description	Type
fallback_model	Defines a model that will be used if the model requested is not on the list. The fallback model must be in the "models" list.	string
format	Defines the LLM inference API format.	string
models	Defines the list of supported models, and optionally their name on the inference provider.	[]LLM_Model
provider	Defines which inference provider will be used to serve the requests.	string
quota	Defines usage quota for the inference endpoint.	LLM_Quota

LLM_Model

Model is a provider model definition.

Example:

name: "string"
provider_name: "string"

Field Name	Description	Type
name	Defines the model name. This is the requested value.	string
provider_name	Represents the model name in the configured provider.	string

LLM_Quota

Quota contains LLM inference usage quota settings.

Example:

requests: # [...]
intervals: 
  - # [...]
  - # [...]
  - # [...]

Field Name	Description	Type
intervals	Defines a list of quota settings per time interval.	[]LLM_Quota_Interval
requests	Specifies quota-related settings for LLM requests.	LLM_Quota_Requests

LLM_Quota_Interval

Interval contans information about a quota interval.

Example:

interval: "string"
input_tokens: 1
output_tokens: 1
reset_options: # [...]

Field Name	Description	Type
input_tokens	Defines the number of input tokens available for the interval. At least one of `input_tokens` or `output_tokens` is required. If not specified, defaults to unlimited input tokens.	number
interval	Defines the interval type being. Supported values: "daily" (reset at the configured time each day), "weekly" (reset on Sunday), "monthly" (reset on the first day of each month), "yearly" (reset at January 1st), "lifetime" (never reset automatically)	string
output_tokens	Defines the number of output tokens available for the interval. At least one of `input_tokens` or `output_tokens` is required. If not specified, defaults to unlimited output tokens.	number
reset_options	Defines the reset settings for the interval. Not applicable when interval type is "lifetime".	LLM_Quota_Interval_Reset

LLM_Quota_Interval_Reset

Reset cotains the interval reset settings.

Example:

timezone: "string"
time: "string"

Field Name	Description	Type
time	Defines at which time the interval resets in `HH:MM` format. Defaults to `00:00` (midnight).	string
timezone	Defines which timezone, in IANA format (such as `America/Los_Angeles`), the interval resets. Defaults to `UTC`.	string

LLM_Quota_Requests

Requests contains quota settings for LLM requests.

Example:

default_max_tokens: 1

Field Name	Description	Type
default_max_tokens	Defines the default max tokens value to set when a request doesn't include it.	number

MCP

Contains MCP server-related configurations.

Example:

command: "string"
args: 
  - "string"
  - "string"
  - "string"
run_as_host_user: "string"
oauth: # [...]

Field Name	Description	Type
args	To execute with the command.	[]string
command	To launch stdio-based MCP servers.	string
oauth	Contains the OAuth settings clients use to log in to the MCP server. Only supported for MCP servers using streamable HTTP transport.	MCPOAuth
run_as_host_user	The host user account under which the command will be executed. Required for stdio-based MCP servers.	string

MCPOAuth

Contains the OAuth settings clients such as tsh use to log in to an OAuth-protected MCP server. These are defaults for clients and are not enforced by Teleport.

Example:

mode: "string"
client_id: "string"
callback_port: 1
redirect_uri: "string"
scopes: 
  - "string"
  - "string"
  - "string"
auth_server_metadata_url: "string"

Field Name	Description	Type
auth_server_metadata_url	The URL of the OAuth authorization server metadata document, such as "https://auth.example.com/.well-known/oauth-authorization-server". When set, clients fetch the metadata from it instead of discovering it from the MCP server, and do not check its issuer against the URL.	string
callback_port	The local port of the OAuth callback registered with the OAuth provider. Mutually exclusive with redirect_uri.	number
client_id	The OAuth client ID of a pre-registered client. When set, clients skip dynamic client registration.	string
mode	Declares whether the MCP server requires OAuth. When empty, it is unspecified. Supported values: "required" (the MCP server requires OAuth), "not_required" (the MCP server does not use OAuth)	string
redirect_uri	The loopback OAuth redirect URI registered with the OAuth provider, such as "http://localhost:3118/callback". Mutually exclusive with callback_port.	string
scopes	The list of OAuth scopes to request.	[]string

Metadata

Resource metadata

Example:

name: "string"
description: "string"
labels: 
  "string": "string"
  "string": "string"
  "string": "string"
expires: # See description
revision: "string"

Field Name	Description	Type
description	Object description	string
expires	A global expiry time header can be set on any resource in the system.
labels	A set of labels	map[string]string
name	An object name	string
revision	An opaque identifier which tracks the versions of a resource over time. Clients should ignore and not alter its value but must return the revision in any updates of a resource.	string

Port Range

Describes a port range for TCP apps. The range starts with Port and ends with EndPort. PortRange can be used to describe a single port in which case the Port field is the port and the EndPort field is 0.

Example:

port: 1
end_port: 1

Field Name	Description	Type
end_port	Describes the end of the range, inclusive. If set, it must be between 2 and 65535 and be greater than Port when describing a port range. When omitted or set to zero, it signifies that the port range defines a single port.	number
port	Describes the start of the range. It must be between 1 and 65535.	number

Rewrite

A list of rewriting rules to apply to requests and responses.

Example:

redirect: 
  - "string"
  - "string"
  - "string"
headers: 
  - # [...]
  - # [...]
  - # [...]
jwt_claims: "string"

Field Name	Description	Type
headers	A list of headers to inject when passing the request over to the application.	[]Header
jwt_claims	Configures whether roles/traits are included in the JWT token.	string
redirect	Defines a list of hosts which will be rewritten to the public address of the application if they occur in the "Location" header.	[]string

Was this page helpful?

Top-level fields​

App AWS​

App AWS Roles Anywhere Profile​

App Identity Center​

App Spec V3​

App TLS​

CORS Policy​

Command Label V2​

Duration​

Header​

Identity Center Permission Set​

LLM​

LLM_Model​

LLM_Quota​

LLM_Quota_Interval​

LLM_Quota_Interval_Reset​

LLM_Quota_Requests​

MCP​

MCPOAuth​

Metadata​

Port Range​

Rewrite​

Top-level fields

App AWS

App AWS Roles Anywhere Profile

App Identity Center

App Spec V3

App TLS

CORS Policy

Command Label V2

Duration

Header

Identity Center Permission Set

LLM

LLM_Model

LLM_Quota

LLM_Quota_Interval

LLM_Quota_Interval_Reset

LLM_Quota_Requests

MCP

MCPOAuth

Metadata

Port Range

Rewrite