Teleport Access Controls Reference

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
    # mfa_verification_interval optionally defines the maximum duration that can elapse between successive MFA verifications.
    # This variable is used to ensure that users are periodically prompted to verify their identity, enhancing
    # security by preventing prolonged sessions without re-authentication when using tsh proxy * derivatives.
    mfa_verification_interval: 1h
    # 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
    # Sets the default shell for auto-provisioned SSH users. An absolute path to a shell or a name
    # reachable through the system PATH are both valid values. Only applies when
    # create_host_user_mode is not set to off.
    create_host_user_default_shell: bash
    # 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']

      # Starting version 16.4.7:
      # 'kubernetes_resources' restricts what kinds of Kubernetes resources
      # a user can request access to. In the below example, users can
      # request only Kubernetes namespaces. Default (when nothing is defined) allows
      # access requests to any Kubernetes resource or the entire cluster.
      kubernetes_resources:
        - kind: "namespace"

      # 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', 'peer']

    # 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: {}

kind: role
version: v5
metadata:
  name: example-role
spec:
  allow:
    node_labels:
      'env': 'stage'

  deny:
    node_labels:
      # Multiple labels are interpreted as an "or" operation. In this case,
      # Teleport will deny access to any node labeled as 'workload=database' or
      # 'workload=backup'
      'workload': ['database', 'backup']

    db_labels:
      'env': 'prod'
      'region': ['us-west-1', 'eu-central-1']

kind: role
version: v5
metadata:
  name: example-role
spec:
  allow:
    node_labels:
      # literal strings:
      'environment': 'test'
      # the wildcard ('*') means "any node"
      '*': '*'
      # a list of alternative options:
      'environment': ['test', 'staging']
      # regular expressions are also supported, for example the equivalent
      # of the list example above can be expressed as:
      'environment': '^test|staging$'

kind: role
version: v7
metadata:
  name: example-role
spec:
  allow:
    node_labels_expression: |
      labels["env"] == "staging" ||
      contains(user.spec.traits["teams"], labels["team"])

allow:
  - resources: [session]
    verbs: [list]

allow:
  rules:
    # CRUD options for managing Teleport Server Access Nodes
    - resources:
        - node
      verbs: [list, create, read, update, delete]
    - resources:
        - app
      verbs: [list, create, read, update, delete]
    - resources:
        - kube_service
      verbs: [list, create, read, update, delete]
    - resources:
        - kube_cluster
      verbs: [list, create, read, update, delete]
    - resources:
        - db
      verbs: [list, create, read, update, delete]
    - resources:
        - windows_desktop
      verbs: [list, create, read, update, delete]
    - resources:
        - role
      verbs: [list, create, read, update, delete]
    # Auth connectors are also known as SSO connectors
    - resources:
        - auth_connector
      verbs: [list, create, read, update, delete]
    # Session: Provides access to Session Recordings.
    # e.g If session read is false, users can't play the recordings
    # It is possible to restrict "list" but to allow "read" (in this case a user will
    # be able to replay a session using `tsh play` if they know the session ID).
    - resources:
        - session
      verbs: [list, read]
    - resources:
        - trusted_cluster
      verbs: [list, create, read, update, delete]
    # Events: Determines whether a user can view the audit log
    # and session recordings.
    - resources:
        - event
      verbs: [list, read]
    - resources:
        - user
      verbs: [list, create, read, update, delete]
    - resources:
        - token
      verbs: [list, create, read, update, delete]

kind: role
version: v7
metadata:
  name: enroll-servers
spec:
  allow:
    node_labels:
      'env': 'us-lab'
    rules:
      - resources: [token]
        verbs: [list, create, read, update, delete]
  deny: {}

version: v5
kind: role
metadata:
  name: only-own-sessions
spec:
  allow:
    rules:
    # Users can only view session recordings for sessions in which they
    # participated.
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants, user.metadata.name)

version: v5
kind: role
metadata:
  name: only-own-ssh-sessions
spec:
  allow:
    rules:
    # Teleport allows session access to the user's sessions
    # and sessions they can join by default. This allows seeing any sessions.
    - resources: [session_tracker]
      verbs: ['*']
  deny:
    rules:
    # ... and then limit that access via a deny rule.
    # Deny rules take precedence over allow rules, so the resulting role
    # only allows user to see their own active sessions.
    - resources: [session_tracker]
      verbs: [list, read, update, delete]
      where: '!contains(session_tracker.participants, user.metadata.name)'

logins:
  - '{{internal.logins}}'

<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname">
        <AttributeValue>firstname.lastname</AttributeValue>
</Attribute>

logins:
   - '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}'

http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname