Teleport Resources

This reference guide lists dynamic resources you can manage with Teleport. For more information on dynamic resources, see our guide to Using Dynamic Resources.

Examples of applying dynamic resources with tctl:

# List all connectors:
$ tctl get connectors

# Dump a SAML connector called "okta":
$ tctl get saml/okta

# Delete a SAML connector called "okta":
$ tctl rm saml/okta

# Delete an OIDC connector called "gworkspace":
$ tctl rm oidc/gworkspace

# Delete a github connector called "myteam":
$ tctl rm github/myteam

# Delete a local user called "admin":
$ tctl rm users/admin

# Show all devices:
$ tctl get devices

# Fetch a specific device:
$ tctl get devices/<asset-tag>

# Fetch the cluster auth preferences
$ tctl get cluster_auth_preference

note

Although tctl get connectors will show you every connector, when working with an individual connector you must use the correct kind, such as saml or oidc. You can see each connector's kind at the top of its YAML output from tctl get connectors.

List of dynamic resources

Here's the list of resources currently exposed via tctl:

Resource Kind	Description
user	A user record in the internal Teleport user DB.
role	A role assumed by interactive and non-interactive users.
connector	Authentication connectors for Single Sign-On (SSO) for SAML, OIDC and GitHub.
node	A registered SSH node. The same record is displayed via tctl nodes ls.
windows_desktop	A registered Windows desktop.
cluster	A trusted cluster. See here for more details on connecting clusters together.
login_rule	A Login Rule, see the Login Rules guide for more info.
device	A Teleport Trusted Device, see the Device Trust guide for more info.
ui_config	Configuration for the Web UI served by the Proxy Service
cluster_auth_preference	Configuration for the cluster's auth preferences.
database_object_import_rule	Database object import rules.

User

Teleport supports interactive local users, non-interactive local users (bots) and single-sign on users that are represented as a resource.

kind: user
version: v2
metadata:
  name: joe
spec:
  # roles is a list of roles assigned to this user
  roles:
  - admin
  # status sets user temporarily locked in a Teleport system, for example
  # when users exceed predefined amount of failed login attempts
  status:
    is_locked: false
    lock_expires: 0001-01-01T00:00:00Z
    locked_time: 0001-01-01T00:00:00Z
  # traits are key, list of values pairs assigned to a user resource.
  # Traits can be used in role templates as variables.
  traits:
    logins:
    - joe
    - root
  # expires, if not empty, sets automatic expiry of the resource
  expires: 0001-01-01T00:00:00Z
  # created_by is a system property that tracks
  # identity of the author of this user resource.
  created_by:
    time: 0001-01-01T00:00:00Z
    user:
      name: builtin-Admin

Role

Interactive and non-interactive users (bots) assume one or many roles.

Roles govern access to databases, SSH servers, Kubernetes clusters, web services and applications and Windows Desktops.

kind: role
version: v7
metadata:
  name: example
  description: This is an example role.
spec:
  # options specify connection, in case if user has multiple non-default
  # conflicting options, teleport chooses the least permissive value.
  options:
    # max_session_ttl defines the TTL (time to live) of certificates
    # issued to the users with this role.
    max_session_ttl: 8h
    # forward_agent controls whether SSH agent forwarding is allowed
    forward_agent: true
    # port_forwarding controls whether TCP port forwarding is allowed for SSH
    port_forwarding: true
    # ssh_file_copy controls whether file copying (SCP/SFTP) is allowed.
    # Defaults to true.
    ssh_file_copy: false
    # client_idle_timeout determines if SSH sessions to cluster nodes are
    # forcefully terminated after no activity from a client (idle client).
    # it overrides the global cluster setting. examples: '30m', '1h' or '1h30m'
    client_idle_timeout: never
    # Determines if the clients will be forcefully disconnected when their
    # certificates expire in the middle of an active session.
    # It overrides the global cluster setting.
    disconnect_expired_cert: no
    # max_sessions is the total number of session channels that can be established
    # across a single connection. Setting it to 10 matches OpenSSH default behavior.
    # (enterprise-only)
    max_sessions: 10
    # Defines which events are recorded by the BPF-based session recorder.
    enhanced_recording:
    - command
    - disk
    - network
    # permit_x11_forwarding allows users to use X11 forwarding with openssh
    # clients and servers through the proxy
    permit_x11_forwarding: true
    # device_trust_mode enforces authenticated device access for assigned user of this role.
    device_trust_mode: optional|required|off
    # require_session_mfa require per-session MFA for any assigned user of this role
    require_session_mfa: true
    # lock sets locking mode for user of this role,
    # valid values are 'strict' or 'best_effort'
    lock: strict
    # enterprise-only request_access field is 'optional', 'always' or 'reason'. If set to always or reason,
    # it instructs tsh or the web UI clients to always create an Access Request. If it is
    # set to 'reason', the user will be required to indicate why they are
    # generating the Access Request.
    request_access: reason
    # the 'request_prompt' field can be used to tell the user what should
    # be supplied in the request reason field.
    request_prompt: Please provide your ticket ID
    # enterprise-only max_connections field sets a limit of concurrent sessions within a
    # cluster. This setting slows down Teleport performance because it has to track
    # connections cluster-wide.
    max_connections: 2
    # limit number of concurrent Kubernetes sessions per user
    max_kubernetes_connections: 1
    # Define how Teleport deals with session recording failures, such as a full
    # disk error. The value can be set to either 'best_effort' or 'strict'. If
    # set to 'strict', the session will terminate immediately. If set to
    # 'best_effort', the session won’t be terminated, and the recording will be
    # disabled. The configuration is done per service (currently, only 'ssh' is
    # supported).
    record_session:
      # Specify whether or not to record the user's desktop sessions.
      # Desktop session recording is enabled if one or more of the user's
      # roles has enabled recording. Defaults to true if unspecified.
      # Desktop sessions will never be recorded if auth_service.session_recording
      # is set to 'off' in teleport.yaml (Auth Service) or if the cluster's
      # session_recording_config resource has set 'mode: off'.
      desktop: true
      # Optional: the default session recording mode to use when a
      # protocol-specific mode is not set.
      default: best_effort|strict
      # Optional: Session recording mode for SSH sessions (Teleport Server
      # Access). If not set, the value set on default will be used.
      ssh: best_effort|strict
    # Specify whether clipboard sharing should be allowed with the
    # remote desktop (requires a supported browser). Defaults to true
    # if unspecified. If one or more of the user's roles has disabled
    # the clipboard, then it will be disabled.
    desktop_clipboard: true
    # Specify whether directory sharing should be allowed from the
    # local machine to remote desktop (requires a supported browser). Defaults to true
    # if unspecified. If one or more of the user's roles has disabled
    # directory sharing, then it will be disabled.
    desktop_directory_sharing: true
    # enterprise-only: when enabled, the source IP that was used to log in is embedded in the user
    # certificates, preventing a compromised certificate from being used on another
    # network. The default is false.
    pin_source_ip: true
    # Specify a list of names and associated values to be included in user SSH keys.
    # The key type can only be 'ssh' and the mode can only be 'extension'.
    # The name and value fields can be arbitrary strings and the value field
    # supports variable interpolation.
    cert_extensions:
     - type: ssh
       mode: extension
       name: [email protected]
       value: '{{ external.github_login }}'
    # Controls whether this role supports auto provisioning of SSH users.
    # Options: keep (keep users at session end), insecure-drop (remove user on session end),
    #          and off (disable host user creation)
    create_host_user_mode: keep
    # Controls whether this role requires automatic database user provisioning.
    # Options: off (disable database user auto-provisioning), keep (disables the
    # user at session end, removing the roles and locking it), and
    # best_effort_drop (try to drop the user at session end, if it doesn't
    # succeed, fallback to disabling it).
    create_db_user_mode: keep
    # Specifies role specific options for identity provider access.
    idp:
      # Specifies role specific options for SAML identity provider access.
      saml:
        # Specifies whether this role has access to the SAML identity provider.
        # Defaults to true.
        enabled: true

  # The allow section declares a list of resource/verb combinations that are
  # allowed for the users of this role. By default, nothing is allowed.
  allow:
    # The logins array defines the OS/UNIX logins a user is allowed to use.
    # both strings and template variables are supported in this field
    logins: [root, '{{internal.logins}}']

    # Windows logins a user is allowed to use for desktop sessions.
    windows_desktop_logins: [Administrator, '{{internal.logins}}']

    # node_labels: a user with this role will be allowed to connect to
    # SSH nodes with labels matching below.
    node_labels:
      # literal strings:
      'env': 'test'
      # the wildcard ('*') means any node
      '*': '*'
      # a list of alternative options:
      'region': ['us-west-1', 'eu-central-1']
      # Regular expressions start with ^ and end with $.
      # Teleport uses Go's regular expression syntax:
      # https://github.com/google/re2/wiki/Syntax
      # The list example above can be expressed as:
      # 'region': '^us-west-1|eu-central-1$'
      'reg': '^us-west-1|eu-central-1$'

    # List of host groups the created user will be added to. Any that don't
    # already exist are created. Only applies when create_host_user_mode
    # is not 'off'.
    host_groups: [ubuntu, nginx, other]

    # List of entries to include in a temporary sudoers file created in
    # `/etc/sudoers.d`. The records are removed on session close.
    host_sudoers: [
      # This line will allow the login user to run `systemctl restart nginx.service`
      # as root without requiring a password. The sudoers entry will be prefixed
      # with the logged in username.
      "ALL = (root) NOPASSWD: /usr/bin/systemctl restart nginx.service"
    ]

    # kubernetes_groups specifies Kubernetes groups a user with this role will assume.
    # You can refer to a SAML/OIDC trait via the 'external' property bag.
    # This allows you to specify Kubernetes group membership in an identity manager:
    kubernetes_groups: ['system:masters', '{{external.trait_name}}']

    # kubernetes_users is an optional field that specifies kubernetes users
    # this role can assume.
    kubernetes_users: ['IAM#{{external.foo}};']

    # kubernetes_labels: a user with this role will be allowed to connect to
    # k8s clusters with labels matching below.
    kubernetes_labels:
      # A user can only access prod environments
      'env': 'prod'
      # User can access any region in us-west, e.g us-west-1, us-west-2
      'region': 'us-west-*'
      # Regular expressions start with ^ and end with $.
      # Teleport uses Go's regular expression syntax:
      # https://github.com/google/re2/wiki/Syntax
      # The list example above can be expressed as:
      # 'region': '^us-west-1|eu-central-1$'
      'cluster_name': '^us.*\.example\.com$'

    # kubernetes_resources indicates the Kubernetes resources that a user with
    # this role is allowed to access.
    kubernetes_resources:
        # The resource kind. Teleport currently supports:
        # - * (all resources)
        # - pod
        # - secret
        # - configmap
        # - namespace
        # - service
        # - serviceaccount
        # - kube_node
        # - persistentvolume
        # - persistentvolumeclaim
        # - deployment
        # - replicaset
        # - statefulset
        # - daemonset
        # - clusterrole
        # - kube_role
        # - clusterrolebinding
        # - rolebinding
        # - cronjob
        # - job
        # - certificatesigningrequest
        # - ingress
      - kind: '*'
        # The name of the Kubernetes namespace in which to allow access the
        # resources you specify with 'name' and 'kind'.
        # The wildcard character '*' matches any sequence of characters.
        # If the value begins with '^' and ends with '$', the Kubernetes
        # Service will treat it as a regular expression.
        namespace: '*'
        # The name of the resource to allow access to.
        # The wildcard character '*' matches any sequence of characters.
        # If the value begins with '^' and ends with '$', the Kubernetes
        # Service will treat it as a regular expression.
        name: '^nginx-[a-z0-9-]+$'
        # The verbs that the user is allowed to perform on the resource.
        # Teleport currently supports:
        # - * (all verbs)
        # - get
        # - list
        # - watch
        # - create
        # - update
        # - patch
        # - delete
        # - deletecollection
        # - exec - allows users to execute commands in a pod
        # - portforward - allows users to forward ports from a pod
        verbs: ['*']

    # Functions transform variables.
    db_users: ['{{email.local(external.email)}}']
    db_names: ['{{external.db_names}}']
    db_labels:
      'env': '{{regexp.replace(external.env, "^(staging)$", "$1")}}'

    # List of database roles to grant. Mutually exclusive with 'db_permissions'.
    db_roles: ['{{external.db_roles}}']

    # Grant all possible Postgres permissions for all tables.
    # List of database permissions to grant. Mutually exclusive with 'db_roles'.
    db_permissions:
    - match:
        object_kind: table
      permissions:
	    - SELECT
	    - INSERT
	    - UPDATE
	    - DELETE
	    - TRUNCATE
	    - REFERENCES
	    - TRIGGER

    # app_labels: a user with this role will be allowed to connect to
    # applications with labels matching below.
    app_labels:
      # A user can only access prod environments
      'env': 'prod'
      # User can access any region in us-west, e.g us-west-1, us-west-2
      'region': 'us-west-*'
      # Regular expressions start with ^ and end with $.
      # Teleport uses Go's regular expression syntax:
      # https://github.com/google/re2/wiki/Syntax
      # The list example above can be expressed as:
      # 'region': '^us-west-1|eu-central-1$'
      'cluster_name': '^us.*\.example\.com$'

    # group_labels: a user with this role will be given permissions to the
    # underlying user_groups. Services such as the Okta service may use these
    # permissions to grant access to external services.
    group_labels:
      # A user is given group membership to production related groups.
      'env': 'prod'

    # cluster_labels: a user with this role will be allowed to connect to remote
    # clusters with labels matching below.
    cluster_labels:
      'env': 'prod'

    # node_labels_expression has the same purpose as node_labels but
    # supports predicate expressions to configure custom logic.
    # A user with this role will be allowed to access nodes if they are in the
    # staging environment *or* if they belong to one of the user's own teams.
    node_labels_expression: |
      labels["env"] == "staging" ||
      contains(user.spec.traits["teams"] , labels["team"])

    # The below <kind>_labels_expression fields have the same purpose of the
    # matching <kind>_labels fields, but support predicate expressions instead
    # of label matchers.
    app_labels_expression: 'labels["env"] == "staging"'
    cluster_labels_expression: 'labels["env"] == "staging"'
    kubernetes_labels_expression: 'labels["env"] == "staging"'
    db_labels_expression: 'labels["env"] == "staging"'
    db_service_labels_expression: 'labels["env"] == "staging"'
    windows_desktop_labels_expression: 'labels["env"] == "staging"'
    group_labels_expression: 'labels["env"] == "staging"'

    # aws_role_arns allows a user with this role to assume AWS roles when
    # accessing AWS console using UI or AWS API using CLI
    aws_role_arns:
      - 'arn:aws:iam::1234567890:role/ec2-read-only'
      - 'arn:aws:iam::1234567890:role/ec2-full-access'
      - 'arn:aws:iam::0987654321:role/example-role'

    # impersonate allows a user with this role to issue certificates on behalf
    # of other users and roles matching expressions below
    impersonate:
      users: ['*']
      roles: ['jenkins']
      # where is an optional where condition
      # further limiting the scope for matching users and roles
      where: >
        contains(user.spec.traits["group"], impersonate_role.metadata.labels["group"]) &&
        contains(user.spec.traits["group"], impersonate_user.metadata.labels["group"])

    # review_requests allows a user holding this role
    # to approve or deny Access Requests (enterprise-only)
    review_requests:
      # the reviewer can view and approve or deny access requests for any roles
      # listed here
      roles: ['dbadmin']
      # the reviewer can preview details about resources accessible by any roles
      # listed in preview_as_roles when reviewing Resource Access Requests
      preview_as_roles: ['dbadmin']

    # request allows a user user request roles matching
    # expressions below
    request:
      # the 'roles' list can be a mixture of literals and wildcard matchers
      roles: ['common', 'dev-*']

      # 'search_as_roles' allows users to search for and request access to
      # resources accessible by the listed roles (enterprise-only)
      search_as_roles: ['access']

      # thresholds specifies minimum amount of approvers and deniers,
      # defaults to 1 for both (enterprise-only)
      thresholds:
        # requires at least two qualifying approvers and at least one denier.
        - approve: 2
          deny: 1

      # max_duration specifies the maximum duration for which a user can request
      # access to a role. The duration can be specified in seconds (s), minutes
      # (m), hours (h), or days (d), e.g. 4d, 10h, 30m, 60s.
      # The maximum duration is 14 days.
      max_duration: 7d

      # the 'claims_to_roles' mapping works the same as it does in
      # the OIDC connector, with the added benefit that the roles being mapped to
      # can also be matchers.
      #
      # This example leverages Teleport's regular expression support, which allows
      # for dynamic mapping from claims. The below mapping says that users with
      # claims that match 'projects: product-(.*)' can request roles that match
      # '$1-admin', where '$1' is the first capture group in the
      # regular expression.
      # Example: the 'projects: product-foo' claim allows a user to request the
      # 'foo-admin' role
      claims_to_roles:
        - claim: 'projects'
          # matches all group names with a leading 'product-'
          value: '^product-(.*)$'
          # generates a role name from the value capture
          roles: ['$1-admin']

      # Teleport can attach annotations to pending Access Requests. these
      # annotations may be literals, or be variable interpolation expressions,
      # effectively creating a means for propagating selected claims from an
      # external identity provider to the plugin system.
      annotations:
        foo: ['bar']
        groups: ['{{external.groups}}']

    # Moderated Sessions policy that dictates requirements for starting a session.
    require_session_join:
      # Defines the name of the policy. The name serves only as an
      # identifier in logs and for organisation/categorisation.
      - name: Auditor oversight
        # Specifies an RBAC predicate that is used to define
        # which users count against the required user count of the policy.
        filter: 'contains(user.spec.roles, 'auditor')'
        # The different session kinds this policy applies to.
        kinds: ['k8s', 'ssh']
        # A list of session participant modes that a participant must have
        # one of in order to count against the policy.
        modes: ['moderator']
        # The minimum amount of users that need to match the filter expression
        # in order to satisfy the policy.
        count: 1
        # The action to take if a moderator leaves a session, causing the policy to no longer be satisfied.
        # This may be either 'terminate' or 'pause'. An empty or unknown value will default to 'terminate'.
        on_leave: 'terminate'

    # Moderated Sessions policy that dictates the ability to join sessions
    join_sessions:
      # Defines the name of the policy. The name serves only as an
      # identifier in logs and for organisation/categorisation.
      - name: Auditor oversight
        # Allows one to join sessions created by other users with these roles
        roles : ['prod-access']
        # The different session kinds this policy applies to.
        kinds: ['k8s', 'ssh']
        # The list of session participant modes the role may join the session as.
        modes: ['moderator', 'observer']

    # spiffe is a list of SPIFFE IDs that the role holder is allowed to request
    # SVIDs for. As long as the request matches one of the blocks within the
    # spiffe list, the certificate will be issued.
    spiffe:
        # The path of the SPIFFE ID that can be requested. This field is
        # required for each block. It must begin with a preceding slash and
        # should not contain a trailing slash.
      - path: "/svc/foo"
        # IP SANs that the user can request be included in a SVID along with the
        # SPIFFE ID in this block. This field is optional and if omitted,
        # the user will not be able to request a SVID with IP SANs.
        ip_sans: ["10.0.0.100/32"]
        # DNS SANs that the user can request be included in a SVID along with
        # the SPIFFE ID in this block. This field is optional and if omitted,
        # the user will not be able to request a SVID with DNS SANs.
        #
        # The '*' wildcard character is supported to indicated one or more of
        # any character. For example, '*.example.com' would match
        # 'foo.example.com'.
        dns_sans: ["foo.svc.example.com"]

    # rules allow a user holding this role to modify other resources
    # matching the expressions below
    # supported resources:
    # role               - role resource
    # user               - user resource
    #
    # auth_connector     - any auth connector resource
    # oidc               - OIDC connector resource
    # saml               - connector resource
    # github             - GitHub connector resource
    #
    # trusted_cluster    - Trusted cluster resource
    # remote_cluster     - remote cluster resource
    #
    # access_request     - Access Request resource
    # access_plugin_data - allows modifying Access Request plugin data
    #
    # session            - session playback records
    # session_tracker    - an active session
    # ssh_session        - allows seeing active sessions page
    # instance           - a Teleport instance
    # event              - structured audit logging event
    #
    #
    # lock                  - lock resource.
    # network_restrictions  - restrictions for SSH sessions
    #
    # auth_server           - Auth Service resource
    # proxy                 - Proxy Service resource
    # node                  - SSH node resource
    # app                   - application resource
    # db                    - database  resource
    # kube_cluster          - Kubernetes cluster resource
    # token                 - provisioning token resource
    # cert_authority        - certificate authority resource
    #
    # cluster_name              - resource that contains the cluster name.
    # cluster_config            - resource that holds cluster level config
    # cluster_auth_preference   - type of authentication for this cluster
    # session_recording_config  - resource for session recording config
    # cluster_audit_config      - resource that holds cluster audit config
    # cluster_networking_config - resource that holds cluster networking config

    rules:
      - resources: [role]
        verbs: [list, create, read, update, delete]
      - resources: [auth_connector]
        verbs: [list, create, read, update, delete]
      - resources: [session]
        verbs: [list, read]
      - resources: [trusted_cluster]
        verbs: [list, create, read, update, delete]
      - resources: [event]
        verbs: [list, read]
      - resources: [user]
        verbs: [list, create, read, update, delete]
      - resources: [token]
        verbs: [list, create, read, update, delete]

  # The deny section uses the identical format as the 'allow' section.
  # The deny rules always override allow rules.
  deny: {}

Role versions

Versions 5, 6 and 7 of the Teleport role resource have different behaviors when accessing Kubernetes resources.

Roles not granting Kubernetes access are equivalent in the three versions.

Roles v5 and v6 can only restrict actions on pods (e.g. executing in them). Role v7 supports restricting all common resource kinds ( see the kubernetes_resource documentation for a complete list).

When no kubernetes_resource is set:

• Roles v5 and v7 grant all access by default
• Roles v6 blocks pod execution by default, this was reverted by roles v7 to improve the user experience.

Allow rule	Role v5	Role v6	Role v7
kubernetes_groups: - "system:masters" kubernetes_labels: {} kubernetes_resources: []	❌ no access	❌ no access	❌ no access
kubernetes_groups: - "system:masters" kubernetes_labels: env: ["dev"] kubernetes_resources: []	✅ full access to dev clusters	❌ cannot exec in pods ✅ can access other resources like secrets	✅ full access to dev clusters
kubernetes_groups: - "system:masters" kubernetes_labels: env: ["dev"] kubernetes_resources: - name: "*" kind: pod namespace: "foo"	✅ can exec in pods in foo ✅ can access secrets in all namespaces. ❌ cannot exec in other namespaces	✅ can exec in pods in foo ✅ can access secrets in all namespaces. ❌ cannot exec in other namespaces	✅ can exec in pods in foo ❌ cannot access secrets in all namespaces ❌ cannot exec in other namespaces
kubernetes_groups: - "system:masters" kubernetes_labels: env: ["dev"] kubernetes_resources: - name: "*" kind: pod namespace: "foo" - name: "*" kind: secret namespace: "foo"	⚠️ not supported	⚠️ not supported	✅ can exec in pods in foo ✅ can access secrets in foo ❌ cannot exec in other namespaces ❌ cannot access secrets in other namespaces ❌ cannot access configmaps in foo
kubernetes_groups: - "system:masters" kubernetes_labels: env: ["dev"] kubernetes_resources: - kind: "namespace" name: "foo"	⚠️ not supported	⚠️ not supported	✅ full access in namespace foo ❌ cannot access other namespaces

Windows desktop

In most cases, Teleport will register windows_desktop resources automatically based on static hosts in your configuration file or via LDAP-based discovery.

However, you can also manage windows_desktop resources manually with tctl. This can be useful for managing inventories of hosts that are not joined to an Active Directory domain.

There are a few important considerations to keep in mind when registering desktops this way:

1. The desktop's addr can be a hostname or IP address, and should include the RDP port (typically 3389).
2. The desktop's host_id should be set to the name of a windows_desktop_service that is capable of proxying remote desktop connections to the host. If you have multiple such services, you can create multiple windows_desktop resources with different host_id values.
3. If you intend to log in to the desktop with local Windows users you must set non_ad: true. If you intend to log in with Active Directory users, leave non_ad unset (or false), and specify the Active Directory domain in the domain field.

kind: windows_desktop
metadata:
  name: desktop-without-ad
  labels:
    foo: bar
    baz: quux
spec:
  host_id: 307e091b-7f6b-42e0-b78d-3362ad10b55d
  addr: 192.168.1.153:3389
  domain: ""
  non_ad: true

  # Optional - ensures that all sessions use the same screen size,
  # no matter what the size of the browser window is.
  # Leave blank to use the size of the browser window.
  screen_size:
    width: 1024
    height: 768
version: v3

Login Rules

Login rules contain logic to transform SSO user traits during login.

kind: login_rule
version: v1
metadata:
  # name is a unique name for the Login Rule in the cluster.
  name: example

  # expires is optional and usually should not be set for deployed login
  # rules, but it can be useful to set an expiry a short time in the future
  # while testing new Login Rules to prevent potentially locking yourself out of
  # your teleport cluster.
  # expires: "2023-01-31T00:00:00-00:00"
spec:
  # priority can be used to order the evaluation of multiple Login Rules within
  # a cluster.
  #
  # Login Rules with lower numbered priorities will be applied first, followed
  # by rules with priorities in increasing order. In case of a tie, Login Rules
  # with the same priority will be ordered by a lexicographical sort of their
  # names.
  #
  # The default value is 0, the supported range is -2147483648 to 2147483647
  # (inclusive).
  priority: 0

  # If set, traits_map will determine the traits of all users who log in to the
  # cluster.
  #
  # This is a YAML map where the key must be a static string which will be the
  # final trait key, and the value is a list of predicate expressions which each
  # must evaluate to a set of strings. The final trait will be set to the union
  # of the resulting string sets of all predicate expressions for that trait
  # key.
  #
  # traits_map must contain the complete set of desired traits. Any external
  # traits not found here will not be included in the user's certificates.
  #
  # Exactly one of traits_map or traits_expression must be set.
  traits_map:
    groups:
      - external.groups
    logins:
      - strings.lower(external.username)

  # traits_expression is a string holding a single predicate expression which
  # must evaluate to a dict. This will set all user's traits during login.
  #
  # Exactly one of traits_map or traits_expression must be set.
  traits_expression: |
    external.put("logins", strings.lower(external.logins))

Database object import rule

Database object import rule define the labels to be applied to database objects imported into Teleport.

See Database Access Controls for more details.

kind: db_object_import_rule
metadata:
  name: my_custom_rule
spec:
  # Priority determines how important the rule is, with lower number indicating lower priority.
  # In case of conflicts, when the same label is applied by two rules,
  # the label applied by rule with higher priority wins.
  priority: 123
  # database_labels is a filter specifying which database resources are in scope of this rule.
  database_labels:
  - name: 'env'
    values:
    - 'test'
    - 'staging'
  - name: 'dept'
    values:
    - '*'
  # Each mapping, if matched, introduces a set of labels applied to database object.
  # Database objects without labels are not imported.
  mappings:
  - add_labels:
      # the following properties are supported; 'obj' stands for 'database object'.
      database: '{{obj.database}}'
      object_kind: '{{obj.object_kind}}'
      name: '{{obj.name}}'
      protocol: '{{obj.protocol}}'
      schema: '{{obj.schema}}'
      database_service_name: '{{obj.database_service_name}}'
      # you may use fixed strings or mix with templates
      fixed: const_value
      template: 'foo-{{obj.name}}'
    # match adds objects to be imported; it cannot be empty.
    match:
      # list of all table names
      table_names:
      - 'fixed_table_name'
      - 'partial_wildcard_*'
    # scope reduces scope of import; it may be empty.
    scope:
      database_names:
        - Widget*
      schema_names:
        - public
        - secret
  # Additional mappings can be added here.
  - add_labels:
      confidential: true
    match:
      table_names:
      - '*'
    scope:
      schema_names:
        - secret
version: v1

Device

Device contains information identifying a trusted device.

kind: device
version: v1
metadata:
  # name is a unique random identifier for the device in the cluster.
  name: 5ff09619-527c-4a17-973f-cd9cd5c93990
spec:
  # asset_tag is a user controlled identifier for the device. This is usually a device serial number.
  asset_tag: HD6M74XNCK

  # collected_data is a list of data recently collected from the device.
  # Each list item is an object containing event and device metadata..
  collected_data:
    # collect_time is the device-recorded timestamp of when the data was collected.
  - collect_time: "2023-02-22T21:04:26.312862Z"

    # os_type is the operating system type of the device.
    os_type: macos

    # record_time is the Teleport-recorded timestamp of when the data was received.
    record_time: "2023-02-22T21:04:26.396471Z"

    # serial_number is the serial number of the device, usually matching the asset tag.
    serial_number: HD6M74XNCK

  # create_time is a timestamp of when the device was created and enrolled with Teleport.
  create_time: "2023-02-22T21:04:20.87721Z"

  # update_time is a timestamp of when the device was last updated.
  update_time: "2023-02-22T21:04:26.396471Z"

  # os_type is the operating system type of the device.
  # This must be one of "linux", "windows", or "macos".
  os_type: macos

  # credential is the device credential used by the device to authenticate with Teleport.
  credential:
    # id is the unique identifier of the credential.
    id: ebe41e2b-5dbb-40a0-82fb-cded7d3373dd

    # public_key_der is the base64-encoded DER-formatted public part of the asymmetric keypair used to verify authenticity.
    public_key_der: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhO73Q5+DWIg9nXFc/Nv38cI9iog9nnlwDmdtZXBtRNc6P0WajDG3cWn3NWttkHTKDSxywOOmupliKA8q1VxvfQ==
  
  # enroll_status is the current enrollment status of the device.
  # This must be one of "enrolled", "not_enrolled", or "unspecified".
  enroll_status: enrolled

UI config

Global configuration options for the Web UI served by the Proxy Service. This resource is not set by default, which means a tctl get ui will result in an error if used before this resource has been set.

kind: ui_config
version: v1
metadata:
  name: ui-config
spec:
  # The amount of scrollback in the terminal. Scrollback is the amount of
  # rows that are retained when lines are scrolled beyond the initial
  # viewport. Does not apply to session recording view.
  scrollback_lines: 1000

Cluster maintenance config

Global configuration options for the agents enrolled into automatic updates.

kind: cluster_maintenance_config
spec:
  agent_upgrades:
    # Maintenance window start hour in UTC.
    # The maintenance window lasts 1 hour.
    utc_start_hour: 2
    # Week days when maintenance is allowed
    # Possible values are:
    # - Short names: Sun, Mon, Tue, Wed, Thu, Fri, Sat
    # - Long names: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
    weekdays:
      - Mon
      - Wed
      - Fri

Cluster auth preferences

Global cluster configuration options for authentication.

metadata:
  name: cluster-auth-preference
spec:
  # Sets the type of second factor to use.
  # Possible values: "on", "off", "otp", "webauthn" and "optional".
  # If "on" is set, all MFA protocols are supported.
  second_factor: "otp"

  # The name of the OIDC or SAML connector. if this is not set, the first connector in the backend is used.
  connector_name: ""

  # webauthn is the settings for server-side Web authentication support.
  webauthn:
    # rp_id is the ID of the Relying Party.
    # It should be set to the domain name of the Teleport installation.
    #
    # IMPORTANT: rp_id must never change in the lifetime of the cluster, because
    # it's recorded in the registration data on the WebAuthn device. If the
    # ri_id changes, all existing WebAuthn key registrations will become invalid
    # and all users who use WebAuthn as the second factor will need to
    # re-register.
    rp_id: teleport.example.com
    # Allow list of device attestation CAs in PEM format.
    # If present, only devices whose attestation certificates match the
    # certificates specified here may be registered (existing registrations are
    # unchanged).
    # If supplied in conjunction with `attestation_denied_cas`, then both
    # conditions need to be true for registration to be allowed (the device
    # MUST match an allowed CA and MUST NOT match a denied CA).
    # By default all devices are allowed.
    attestation_allowed_cas: []
    # Deny list of device attestation CAs in PEM format.
    # If present, only devices whose attestation certificates don't match the
    # certificates specified here may be registered (existing registrations are
    # unchanged).
    attestation_denied_cas: []

  # Enforce per-session MFA or PIV-hardware key restrictions on user login sessions.
  # Possible values: true, false, "hardware_key", "hardware_key_touch".
  # Defaults to false.
  require_session_mfa: false

  # Sets whether connections with expired client certificates will be disconnected.
  disconnect_expired_cert: false

  # Sets whether headless authentication is allowed.
  # Headless authentication requires WebAuthn.
  # Defaults to true if webauthn is configured.
  allow_headless: false

  # Sets whether local auth is enabled alongside any other authentication
  # type.
  allow_local_auth: true

  # Sets whether passwordless authentication is allowed.
  # Requires Webauthn to work.
  allow_passwordless: false

  # Sets the message of the day for the cluster.
  message_of_the_day: ""

  # idp is a set of options related to accessing IdPs within Teleport. Requires Teleport Enterprise
  idp:
    # options related to the Teleport SAML IdP.
    saml:
      # enables access to the Teleport SAML IdP.
      enabled: true

  # locking_mode is the cluster-wide locking mode default.
  # Possible values: "strict" or "best_effort"
  locking_mode: best_effort

  # default_session_ttl defines the default TTL (time to live) of certificates
  # issued to the users on this cluster.
  default_session_ttl: "12h"

  # The type of authentication to use for this cluster.
  # Possible values: "local", "oidc", "saml" and "github"
  type: local

version: v2

Bot

Bot resources define a Machine ID Bot identity and its access.

Find out more on the Machine ID configuration reference.

kind: bot
version: v1
metadata:
  # name is a unique identifier for the bot in the cluster.
  name: robot
spec:
  # roles is a list of roles that the bot should be able to generate credentials
  # for.
  roles:
  - editor
  # traits controls the traits applied to the Bot user. These are fed into the
  # role templating system and can be used to grant a specific Bot access to
  # specific resources without the creation of a new role.
  traits:
  - name: logins
    values:
    - root