Teleport 역할 참조

요약

이 가이드는 Teleport 역할을 사용하여 Teleport 클러스터에서 역할 기반 접근 제어(RBAC)를 관리하는 방법을 보여줍니다. Teleport 역할은 두 가지 규칙 목록을 통해 접근을 관리합니다: allow 규칙과 deny 규칙.

이 가이드는 Teleport 역할을 사용하여 Teleport 클러스터에서 역할 기반 접근 제어(RBAC)를 관리하는 방법을 보여줍니다.

Teleport 역할은 두 가지 규칙 목록을 통해 접근을 관리합니다: allow 규칙과 deny 규칙. 접근 규칙을 선언할 때 다음 사항을 염두에 두십시오:

기본적으로 허용되는 것은 없습니다.
Deny 규칙이 먼저 평가되고 우선순위를 갖습니다.
Deny 규칙은 Access Lists를 통해 부여된 역할에서는 사용하지 않는 것이 좋습니다.

다음 중 하나를 사용하여 Teleport 역할 및 기타 동적 리소스를 관리할 수 있습니다:

Teleport 웹 UI
tctl 클라이언트 도구
Teleport Terraform 제공자
Teleport Kubernetes 오퍼레이터
사용자 정의 API 클라이언트

동적 리소스 관리에 대한 자세한 내용은 동적 리소스 가이드를 참조하십시오.

다음 명령어를 실행하여 로컬 워크스테이션에서 클러스터의 모든 역할을 볼 수 있습니다:

# Log in to your cluster with tsh so you can use tctl from your local machine.
$ tsh login --user=myuser --proxy=example.teleport.sh
$ tctl get roles

역할 명세 예시#

전체 역할 명세입니다:

kind: role
version: v8
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
    # ssh_port_forwarding controls which TCP port forwarding modes are allowed over SSH. This replaces
    # the deprecated port_forwarding field, which did not differentiate between remote and local
    # port forwarding modes. If you have any existing roles that allow forwarding by enabling the
    # legacy port_forwarding field then the forwarding controls configured in ssh_port_forwarding will be
    # ignored.
    ssh_port_forwarding:
      # configures remote port forwarding behavior
      remote:
        enabled: true
      # configures local port forwarding behavior
      local:
        enabled: 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: false
    # 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|required-for-humans|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 or Teleport Connect).
    # 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 or Teleport Connect).
    # 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
    # Specify whether this role supports auto-provisioning of local Windows users.
    create_desktop_user: 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: login@github.com
       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

  # 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"
    ]

    # List of local Windows groups the created user will be added to.
    # Any that don't already exist are created. Only applies when
    # create_desktop_user is 'true'.
    desktop_groups:
    - developers
    # to make the newly-created user an administrator
    - Administrators
    # IdP trait templating is also supported
    - '{{external.desktop_groups}}'

    # 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)
        # - <arbitrary string> (Resource plural name, e.g. pods, deployments, cronjobs, mycustomresources)
      - kind: '*'
        # The resource name of the Kubernetes cluster in which to allow access
        # to the resources you specify with 'name' and 'kind'.
        api_group: '*'
        # 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 for namespaced
        # resource. If set, global resources will not match.
        # 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: ['*']

    # Database account names this role can connect as.
    #
    # Supports role templating with traits.
    db_users: ['{{email.local(external.email)}}']
    # Database names this role will be able to connect to. Database names are
    # only enforced for PostgreSQL, MongoDB, and Cloud Spanner databases.
    #
    # Supports role templating with traits.
    db_names: ['{{external.db_names}}']
    # Label selectors for database instances this role has access to.
    #
    # Supports role templating with traits.
    db_labels:
      'env': '{{regexp.replace(external.env, "^(staging)$", "$1")}}'

    # List of database roles to grant to the auto-provisioned user. Mutually
    # exclusive with 'db_permissions'.
    #
    # Supports role templating with traits.
    db_roles: ['{{external.db_roles}}']

    # List of database permissions to grant to the auto-provisioned user.
    # 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'

    # workload_identity_labels: a user/bot with this role will be allowed to
    # issue Workload Identities with labels matching below.
    #
    # Supports role templating with traits.
    workload_identity_labels:
      'env': 'prod'
      'team': '{{external.team}}'

    # 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"'
    workload_identity_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'

    # AWS account and permission set bindings for the Identity Center integration
    account_assignments:
    - # AWS identity center account ID
      account: "<account_id>"
      # name of the permission set in AWS
      name: AdministratorAccess
      # permission set ARN
      permission_set: arn:aws:sso:::permissionSet/ssoins-1234/ps-5678 # permission set ARN

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

      # '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"

      # 'reason' defines settings for the reason for the access provided by the user.
      reason:
        # 'mode' can be either "required" or "optional". Empty string is treated as
        # "optional". If a role has the request reason mode set to "required", then reason
        # is required for all Access Requests requesting roles or resources allowed by
        # this role. It applies only to users who have this role assigned.
        mode: "optional"
        # 'prompt' is a custom message prompted to the user for the requested roles or resources searchable
	      # as other roles. This is only applied to the requested roles and resources specifying the prompt.
        prompt: I am a reason prompt specific to a requested role or resource

      # 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"]

    # GitHub-related permissions used for proxying Git commands.
    github_permissions:
      # List of GitHub organizations the user has access to.
    - orgs:
      - my-org

    # mcp: defines MCP servers related permissions.
    mcp:
      # tools: list of tools allowed for this role.
      #
      # No tools are allowed if not specified.
      # Each entry can be a literal string, a glob pattern, or a regular
      # expression (must start with '^' and end with '$'). A wildcard '*' allows
      # all tools.
      # This value field also supports variable interpolation.
      tools:
      - search-files
      - slack_*
      - ^(get|list|read).*$
      - "{{internal.mcp_tools}}"
      - "{{external.mcp_tools}}"

    # 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
    # instance           - a Teleport instance
    # event              - structured audit logging event
    #
    # workload_identity     - config for Machine & Workload Identity SVIDS
    # bot                   - config for Machine & Workload Identity bots
    #
    # 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
    # git_server            - Git server 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: {}

역할 옵션#

역할은 사용자가 시작한 세션에 특정 제한을 정의할 수 있습니다. 아래 표는 여러 역할이 사용자에게 할당된 경우 각 옵션의 동작을 문서화합니다:

옵션	설명	다중 역할 동작
`max_session_ttl`	사용자의 SSH 인증서의 최대 유효 시간(TTL)	가장 짧은 TTL이 적용됨
`forward_agent`	SSH 에이전트 포워딩 허용	논리적 "OR" 즉 어느 역할이라도 에이전트 포워딩을 허용하면 허용됨
`ssh_port_forwarding`	TCP 포트 포워딩 허용	논리적 "AND" 즉 어느 역할이라도 포트 포워딩을 거부하면 거부됨
`ssh_file_copy`	SCP/SFTP 허용	논리적 "AND" 즉 모든 역할이 파일 복사를 허용하면 허용됨
`client_idle_timeout`	유휴 간격 후 활성 세션을 강제 종료	가장 짧은 타임아웃 값이 적용됨 즉 가장 제한적인 값이 선택됨
`disconnect_expired_cert`	클라이언트 인증서 만료 시 활성 세션을 강제 종료	논리적 "OR" 즉 하나의 역할이라도 세션 종료를 요구하면 "yes"로 평가됨
`max_sessions`	Teleport를 통해 단일 SSH 연결에서 설정할 수 있는 총 세션 채널 수	가장 낮은 값이 우선됨.
`enhanced_recording`	BFP 기반 세션 레코더가 기록해야 할 이벤트 표시
`permit_x11_forwarding`	OpenSSH 클라이언트 및 서버에서 사용자가 X11 포워딩을 활성화할 수 있도록 허용
`device_trust_mode`	이 역할이 할당된 사용자에 대한 인증된 장치 접근 강제 (`required`, `required-for-humans`, `optional`, `off`). 역할의 allow 필드 리소스에만 적용됨.
`require_session_mfa`	사용자 로그인 세션에 세션별 MFA 또는 PIV 하드웨어 키 제한 강제 (`no`, `yes`, `hardware_key`, `hardware_key_touch`). 역할의 allow 필드 리소스에만 적용됨.	세션별 MFA의 경우 논리적 "OR" 즉 하나의 역할이라도 세션 MFA를 요구하면 "yes"로 평가됨
`mfa_verification_interval`	연속적인 MFA 인증 사이에 경과할 수 있는 최대 기간 정의	가장 짧은 간격이 적용됨
`lock`	잠금 모드 (`strict` 또는 `best_effort`)	충돌 시 `strict`가 우선됨
`request_access`	Enterprise 전용 접근 요청 전략 (`optional`, `always` 또는 `reason`)
`request_prompt`	접근 요청 "reason" 필드에 대한 프롬프트
`max_connections`	Enterprise 전용 Teleport를 통해 시작할 수 있는 동시 세션 제한	가장 낮은 값이 우선됨.
`max_kubernetes_connections`	사용자당 최대 동시 Kubernetes 세션 수 정의
`record_session`	세션 녹화 모드를 정의합니다.	가장 엄격한 값이 우선됩니다.
`desktop_clipboard`	데스크톱 세션에서 클립보드 공유 허용	논리적 "AND" 즉 모든 역할이 클립보드 공유를 활성화하면 "yes"로 평가됨
`desktop_directory_sharing`	로컬 워크스테이션 디렉터리를 원격 데스크톱에 공유하는 것을 허용	논리적 "AND" 즉 모든 역할이 디렉터리 공유를 활성화하면 "yes"로 평가됨
`create_desktop_user`	로컬 Windows 데스크톱에서 데스크톱 자동 사용자 생성 허용.	논리적 "AND" 즉 데스크톱 리소스와 일치하는 모든 역할에 대해. 리소스에 대한 접근을 허용하는 모든 역할이 `true`로 설정되면 사용자 생성이 허용됨. 하나라도 `false`로 설정되면 자동 사용자 생성이 거부됨.
`pin_source_ip`	SSH 인증서에 대한 소스 IP 고정 활성화.	논리적 "OR" 즉 하나의 역할이라도 세션 종료를 요구하면 "yes"로 평가됨
`cert_extensions`	SSH 인증서에 포함할 확장 지정
`create_host_user_mode`	호스트에서 사용자가 자동으로 생성되도록 허용	논리적 "AND" 즉 서버와 일치하는 모든 역할이 호스트 사용자 생성을 지정하는 경우 (`off`, `keep`, `insecure-drop`), 모든 역할에서 지정한 옵션으로 평가됨. 일부 역할이 `insecure-drop` 또는 `keep`을 모두 지정하면 `keep`으로 평가됨
`create_db_user_mode`	데이터베이스 사용자 자동 프로비저닝 허용. 옵션: `off` (데이터베이스 사용자 자동 프로비저닝 비활성화), `keep` (세션 종료 시 사용자 비활성화, 역할 제거 및 잠금), `best_effort_drop` (세션 종료 시 사용자 삭제 시도, 실패 시 비활성화로 폴백).	논리적 "OR" 즉 어느 역할이라도 데이터베이스 사용자 자동 프로비저닝을 허용하면 허용됨

사전 설정 역할#

Teleport는 여러 사전 설정 역할을 제공합니다:

Role	Description	Enterprise-only
`access`	Allows access to cluster resources.
`editor`	Allows editing of cluster configuration settings.
`auditor`	Allows reading cluster events, audit logs, and playing back session records.
`access-plugin`	Enables self-hosted Access Request plugin features.
`list-access-request-resources`	Allows reading Access Request resources.
`requester`	Allows a user to create Access Requests.	✔
`reviewer`	Allows review of Access Requests.	✔
`group-access`	Allows access to all user groups.	✔
`device-admin`	Used to manage trusted devices.	✔
`device-enroll`	Used to grant device enrollment powers to users.	✔
`require-trusted-device`	Requires trusted device access to resources.	✔
`terraform-provider`	Allows the Teleport Terraform provider to configure all of its supported Teleport resources.

역할 버전#

현재 지원되는 역할 버전은 v3, v4, v5, v6, v7, v8 총 여섯 가지입니다.

v4 이상의 역할은 v3과 완전히 하위 호환됩니다. 유일한 차이점은 명시적으로 설정되지 않은 경우 역할에 적용되는 기본값입니다. 또한 버전 v5 이상의 역할은 기본적으로 세션 조인을 허용하지 않습니다. v5 이상의 역할에서 세션 조인 구성을 세션 조인을 허용하도록 설정해야 합니다.

레이블	`v3` 기본값	`v4` 이상 기본값
`node_labels`	역할에 로그인이 있으면 `[{"": ""}]`, 없으면 `[]`	`[]`
`app_labels`	`[{"": ""}]`	`[]`
`kubernetes_labels`	`[{"": ""}]`	`[]`
`db_labels`	`[{"": ""}]`	`[]`

역할 v6은 Kubernetes 리소스에 대한 세밀한 제어를 허용하는 새 필드 kubernetes_resources를 도입했습니다. 자세한 내용은 Kubernetes RBAC를 참조하십시오.

역할 v7은 kubernetes_resources 필드에 더 많은 kind 값을 지원합니다.

역할 v8은 Kubernetes CRD 지원을 추가하고 kubernetes_resources의 동작 및 정의 방식에 변경 사항을 도입했습니다. 역할 v8은 Teleport v17 에이전트와 호환되지 않습니다: 사용자에게 v8 역할이 있으면 Teleport Kubernetes Service를 실행하는 v17 에이전트가 v8 역할에 특화된 필드를 해석할 수 없어 사용자 접근을 조용히 거부할 수 있습니다. 역할 v8을 사용하기 전에 모든 에이전트를 v18로 업그레이드하십시오.

버전 간의 차이에 대한 자세한 내용은 Kubernetes 리소스를 참조하십시오.

`kubernetes_resources`의 기본값#

kubernetes_resources의 기본값은 Kubernetes 클러스터에 대한 접근을 허용하는 레이블이 설정된 경우 적용됩니다.

버전	`kubernetes_resources`
`v3`, `v4` 및 `v5`	`[{"kind":"pod","name":"","namespace":"","verbs":["*"]}]`
`v6`	`[]`
`v7`	`[{"kind":"","name":"","namespace":"","verbs":[""]}]`
`v8`	`[{"kind":"","api_group":"","name":"","namespace":"","verbs":[""]},{"kind":"","api_group":"","name":"","namespace":"","verbs":["*"]}]`

SAML IdP 역할 옵션 spec.idp.saml.enabled: true/false는 역할 버전 7 이하에서만 지원됩니다. 역할 v8부터 saml_idp_service_provider 리소스 RBAC에 추가적인 변경 사항이 있습니다. 자세한 내용은 SAML IdP RBAC를 참조하십시오.

인프라 리소스에 대한 RBAC#

Teleport 역할은 사용자가 접근할 수 있는 리소스(애플리케이션, 서버, 데이터베이스 등)를 정의합니다. 이는 리소스에 레이블을 지정하고 역할 정의에서 허용/거부 레이블을 구성하여 작동합니다.

다음 사용 사례를 고려하십시오:

인프라는 environment=production 및 environment=staging과 같은 레이블을 사용하여 스테이징/운영 환경으로 나뉩니다. 하나의 환경에만 접근할 수 있는 역할을 만들 수 있습니다. 예를 들어 레이블 environment=staging에 대한 허용 규칙을 가진 인턴 역할을 만든다고 합시다.

예시#

아래 역할은 "env=stage"로 레이블이 지정된 모든 노드에 대한 접근을 허용하되, "workload=database" 또는 "workload=backup"으로도 레이블이 지정된 노드는 제외합니다.

다른 노드에 대한 접근은 거부됩니다.

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']

Teleport는 여러 레이블 항목을 논리적 "AND" 연산으로 처리합니다. 예를 들어, 다음 항목은 env: prod 레이블 및 us-west-1 또는 eu-central-1의 region 레이블을 가진 데이터베이스와 일치합니다:

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

동적 RBAC

리소스 레이블은 동적일 수 있습니다. 즉, 실행 중인 실행 파일의 출력에 의해 런타임에 결정됩니다. 이 경우 "권한이 워크로드를 따라가는" 정책을 구현할 수 있습니다 (예: PostgreSQL이 실행 중인 서버는 "DBA" 그룹의 구성원만 자동으로 접근 가능하게 됨).

확장 레이블 매칭 구문#

다음은 다양한 정규식을 사용한 더 복잡한 필터링 예시입니다.

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$'

레이블 표현식#

다음이 필요한 경우 Teleport 역할은 술어 표현식을 사용하여 리소스 레이블 매칭도 지원합니다:

OR 및 AND 연산자를 통한 로직 결합
레이블 키에 대한 매칭 수행
부정 매칭 구현

다음 예시 역할은 env=staging으로 레이블이 지정된 노드 또는 team=<team>으로 레이블이 지정된 노드에 대한 접근을 허용하며, 여기서 <team>은 사용자의 teams trait 값 중 하나입니다:

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

<kind>_labels_expression 필드는 <kind>_labels 필드와 동일한 목적을 가지지만, 레이블 매처 대신 술어 표현식을 지원합니다. 역할 spec.allow 및 spec.deny 조건의 다음 필드에서 사용할 수 있습니다:

node_labels_expression
app_labels_expression
cluster_labels_expression
kubernetes_labels_expression
db_labels_expression
db_service_labels_expression
windows_desktop_labels_expression
group_labels_expression
workload_identity_labels_expression

언어에 대한 심층적인 설명은 술어 언어 가이드를 참조하십시오.

일반적으로 단일 역할에서 <kind>_labels 또는 <kind>_labels_expression 중 하나만 사용하는 것이 좋지만, 두 가지를 모두 지정할 수 있습니다. deny 규칙에 둘 다 있으면 매칭이 탐욕적입니다. 즉, 하나라도 일치하면 접근이 거부됩니다. allow 규칙에서는 매칭이 탐욕적이지 않습니다. 즉, 둘 다 설정된 경우 접근이 허용되려면 둘 다 일치해야 합니다.

동적 Teleport 리소스에 대한 RBAC#

RBAC를 통해 팀은 Teleport 사용자가 이용할 수 있는 리소스를 제한할 수 있습니다. 예를 들어 일반 사용자가 SSO(auth_connector)를 편집하거나 새 역할(role)을 만들고 편집하는 것을 원하지 않는 경우에 유용합니다.

RBAC 리소스 수정 규칙은 리소스와 동사 두 부분으로 구성됩니다. 다음은 SSH sessions 리소스에 list 동사를 적용하는 allow 규칙 예시입니다. 이는 "이 역할의 사용자가 활성 SSH 세션 목록을 볼 수 있도록 허용"을 의미합니다.

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

이 규칙이 역할 정의의 deny 섹션에 선언되면, 사용자가 활성 세션 목록을 가져오지 못하도록 금지합니다. 역할이 리소스를 나열할 수 있는 접근을 허용하지 않으면, 사용자는 웹 UI나 tctl로 원격으로 볼 수 없습니다. 단, 사용자는 항상 tctl을 통해 할당된 역할과 자신의 사용자 정보를 볼 수 있습니다. 아래 예시 역할 구성에서 allow 섹션에서 사용 가능한 모든 리소스와 동사를 볼 수 있습니다.

다음은 일반적으로 사용되는 rules를 보여주는 allow 섹션 예시입니다. 각 규칙에는 Teleport 리소스 목록과 사용자가 실행할 수 있는 CRUD 작업이 포함됩니다:

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]

토큰 리소스에 대한 접근 허용#

토큰 생성을 허용하는 역할을 구성하면, 역할이 할당된 사용자는 모든 유형의 Teleport 리소스를 프로비저닝하는 토큰을 생성할 수 있습니다. 예를 들어 할당된 사용자가 서버를 등록할 수 있도록 다음 구성으로 역할을 만들 수 있습니다:

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

이러한 권한으로 역할이 할당된 사용자는 서버, 애플리케이션 또는 데이터베이스를 등록하고, 루트 클러스터와 새 Teleport Proxy Service 간의 신뢰 관계를 설정하거나 새 리프 클러스터를 추가하는 토큰을 생성할 수 있습니다.

토큰 리소스는 노드나 신뢰할 수 있는 클러스터와 같은 특정 컨텍스트로 범위가 지정되지 않으므로, 토큰 권한을 제공하는 역할은 관리 역할로 간주해야 합니다. 특히 클러스터의 구성이나 상태가 예기치 않게 변경되는 것을 방지하기 위해 token 리소스에 대한 create 및 update 권한을 부여하는 allow 규칙을 구성하지 않는 것이 좋습니다.

세션 녹화에 대한 RBAC#

세션 녹화에 대한 접근을 추가로 제한할 수 있습니다.

RBAC 규칙의 where 필드는 강력한 필터링 기능을 제공하여 사용자 traits 및 리소스 메타데이터를 기반으로 세션 녹화에 대한 접근을 제한할 수 있습니다. 이를 통해 컨텍스트 정보를 기반으로 녹화를 볼 수 있는 사람에 대한 세밀한 제어가 가능합니다.

사전 설정 감사자 역할

이러한 역할이 적용되려면, 사용자에게 모든 이벤트, 세션 및 세션 녹화에 대한 접근을 허용하는 사전 설정 auditor 역할과 같은 더 허용적인 역할이 없는지 확인해야 합니다.

`where` 절 이해#

where 절은 접근이 허용되려면 true로 평가되어야 하는 조건으로 작동합니다. 다음을 참조할 수 있는 술어 표현식을 사용합니다:

인증된 사용자의 속성(이름, 역할, traits)
세션 녹화에 대한 메타데이터(참가자, 프로토, 생성자 등)
리소스별 속성(서버 세부 정보, 데이터베이스 정보 등)

기본 구문 예시:

where: contains(session.participants, user.metadata.name)

이 표현식은 현재 사용자가 세션의 참가자 목록에 있을 때만 true로 평가됩니다.

일반적인 접근 제어 레시피#

다음은 일반적인 접근 제어 패턴을 구현하기 위해 where 표현식을 사용하는 실용적인 예시입니다:

세션 참가자로 제한#

사용자가 참여한 세션 녹화만 볼 수 있도록 허용합니다:

version: v8
kind: role
metadata:
  name: only-own-sessions
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants, user.metadata.name)

사용자 역할로 제한#

세션 생성자와 역할을 공유하는 사용자에게만 접근 허용:

version: v8
kind: role
metadata:
  name: sessions-viewer
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains_any(user.spec.roles, session.user_roles)

팀 Trait으로 제한#

같은 팀 구성원이 서로의 세션을 볼 수 있도록 허용합니다:

version: v8
kind: role
metadata:
  name: team-sessions-viewer
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains_any(session.user_traits["team"], user.spec.traits["team"])

세션 참가자로 제한#

사용자가 참여한 세션만 볼 수 있도록 허용합니다:

version: v5
kind: role
metadata:
  name: own-sessions
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants, user.metadata.name)

리소스 유형으로 제한#

SSH 세션 녹화만 볼 수 있도록 허용합니다:

version: v5
kind: role
metadata:
  name: ssh-sessions-only
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: session.proto == "ssh"

여러 조건 결합#

이 규칙은 사용자가 참가자이거나 해당 노드가 팀이 소유하는 경우에만 SSH 세션 녹화를 볼 수 있도록 합니다.

version: v5
kind: role
metadata:
  name: complex-sessions-access
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: >
        (contains(session.participants, user.metadata.name) ||
         contains(user.spec.traits["team"], session.server_labels["team"])) &&
        session.proto == "ssh"

이러한 where 표현식을 활용하면 감사 및 모니터링을 위한 적절한 가시성을 허용하면서 조직의 보안 요구 사항에 맞는 접근 제어 정책을 구현할 수 있습니다.

필터 필드#

규칙의 where 필드를 사용하면 사용자 traits 및 리소스 메타데이터를 기반으로 리소스에 대한 접근을 필터링할 수 있습니다.

사용자 필드#

다음 사용자 필드는 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다. user 객체는 세션 녹화에 접근하기 위해 요청을 하는 인증된 사용자를 나타냅니다.

사용자 필드	설명	유형
`user.metadata.name`	사용자의 이름.	`string`
`user.spec.traits`	사용자에게 할당된 traits.	`dict<string, array<string>>`
`user.spec.roles`	사용자에게 할당된 역할.	`array<string>`

세션 필드#

세션 필드는 변경 불가능합니다

세션 필드는 변경 불가능하며 세션이 생성된 순간의 상태를 캡처합니다.

기본 리소스가 변경되면(예: 서버 레이블), 이러한 필드는 업데이트되지 않으며 세션의 RBAC는 변경 사항을 반영하지 않습니다.

다음 세션 필드는 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다. session 객체는 접근 중인 세션 리소스를 나타냅니다. 이는 참가자, 프로토, 리소스 유형, 세션 생성자(세션을 시작한 사용자)의 역할 및 traits를 포함한 세션 메타데이터를 포함합니다.

세션 필드	설명	유형
`session.id`	세션의 고유 식별자.	`string`
`session.kind`	세션의 종류 (예: "ssh", "kube", "db", "rdp").	`string`
`session.participants`	세션에 참여한 사용자 목록.	`array<string>`
`session.proto`	세션에 사용된 프로토 (예: "ssh", "kube", "db", "rdp").	`string`
`session.user`	세션을 시작한 사용자.	`string`
`session.user_roles`	세션을 시작한 사용자에게 할당된 역할.	`array<string>`
`session.user_traits`	세션을 시작한 사용자에게 할당된 traits.	`dict<string, array<string>>`

세션 종류에 따라 필터링에 사용할 수 있는 추가 세션 필드가 있습니다.

다음 서버 세션 필드도 위의 사용자 및 세션 필드와 함께 SSH 세션에 대한 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다.

서버 세션 필드	설명	유형
`session.server_id`	세션이 이루어진 서버의 고유 식별자.	`string`
`session.server_hostname`	세션이 이루어진 서버의 호스트 이름.	`string`
`session.server_labels`	세션이 이루어진 서버에 할당된 레이블.	`dict<string, string>`
`session.server_addr`	세션이 이루어진 서버의 주소.	`string`
`session.login`	세션 중 서버에 로그인하는 데 사용된 사용자 이름.	`string`

다음 Kubernetes 세션 필드는 위의 사용자 및 세션 필드와 함께 Kubernetes 세션에 대한 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다.

Kubernetes 세션 필드	설명	유형
`session.kubernetes_cluster`	세션이 이루어진 Kubernetes 클러스터의 이름.	`string`
`session.kubernetes_labels`	세션이 이루어진 Kubernetes 클러스터에 할당된 레이블.	`dict<string, string>`
`session.kubernetes_user`	세션에서 사용된 Kubernetes 사용자.	`string`
`session.kubernetes_groups`	세션에서 사용된 Kubernetes 그룹.	`array<string>`
`session.kubernetes_pod_namespace`	세션이 이루어진 Kubernetes 클러스터의 네임스페이스.	`string`
`session.kubernetes_pod_name`	세션이 이루어진 Kubernetes 클러스터의 파드 이름.	`string`
`session.kubernetes_container_name`	세션이 이루어진 Kubernetes 클러스터의 컨테이너 이름.	`string`

다음 데이터베이스 세션 필드는 위의 사용자 및 세션 필드와 함께 데이터베이스 세션에 대한 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다.

데이터베이스 세션 필드	설명	유형
`session.db_service`	세션이 이루어진 데이터베이스 서비스의 이름.	`string`
`session.db_protocol`	데이터베이스 연결에 사용된 프로토콜 (예: "postgres", "mysql").	`string`
`session.db_uri`	세션이 이루어진 데이터베이스의 URI.	`string`
`session.db_name`	세션 중 접근한 데이터베이스의 이름.	`string`
`session.db_user`	세션 중 사용된 데이터베이스 사용자.	`string`
`session.db_labels`	세션이 이루어진 데이터베이스에 할당된 레이블.	`dict<string, string>`
`session.db_type`	데이터베이스의 유형 (예: "postgres", "mysql").	`string`

다음 Windows 데스크톱 세션 필드는 위의 사용자 및 세션 필드와 함께 Windows 데스크톱 세션에 대한 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다.

Windows 데스크톱 세션 필드	설명	유형
`session.windows_desktop_service`	세션이 이루어진 Windows 데스크톱 서비스의 이름.	`string`
`session.desktop_addr`	세션이 이루어진 Windows 데스크톱의 주소.	`string`
`session.desktop_name`	세션이 이루어진 Windows 데스크톱의 이름.	`string`
`session.domain`	세션이 이루어진 Windows 데스크톱의 도메인.	`string`
`session.windows_user`	세션 중 Windows 데스크톱에 로그인하는 데 사용된 사용자 이름.	`string`
`session.desktop_labels`	세션이 이루어진 Windows 데스크톱에 할당된 레이블.	`dict<string, string>`

함수#

세션 녹화에 대한 접근을 필터링하기 위해 where 표현식에서 다음 함수를 사용할 수 있습니다:

함수	시그니처	설명
`contains`	`contains(array<string>, string) -> bool`	배열에 지정된 값이 포함되어 있으면 true 반환.
`contains_any`	`contains_any(array<string>, array<string>) -> bool`	두 배열에 공통 요소가 있으면 true 반환.
`contains_all`	`contains_all(array<string>, array<string>) -> bool`	첫 번째 배열이 두 번째 배열의 모든 요소를 포함하면 true 반환.
`can_view`	`can_view() -> bool`	사용자가 Teleport의 SSH 노드, Kubernetes 클러스터, 데이터베이스 또는 Windows 머신을 볼 수 있으면 true 반환.
`equals`	`equals(array<string>, array<string>) -> bool`	두 문자열 또는 두 배열이 같으면 true 반환.
`set`	`set(string,string...) -> array<string>`	하나 이상의 문자열을 배열로 변환.

활성 세션에 대한 RBAC#

공유 세션에 대한 접근을 추가로 제한할 수 있습니다. 아래 예시는 활성 SSH 세션에 대한 접근을 세션을 만든 사용자로만 제한하는 방법을 보여줍니다.

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)'

접근 요청#

다음 역할 필드는 접근 요청을 구성합니다. 접근 요청 구성 필드 및 상호 관계에 대한 전체 설명은 접근 요청 구성 가이드를 참조하십시오.

접근 요청 생성#

역할 내에서 request 필드는 사용자가 접근 요청을 생성하는 능력을 구성합니다. request 필드는 spec.allow와 spec.deny 모두에 포함될 수 있습니다:

역할 필드	설명	추가 정보
`request.roles`	사용자가 요청하거나 요청할 수 없는 Teleport 역할	역할 요청 제한
`request.claims_to_roles`	사용자가 traits을 기반으로 접근하거나 접근할 수 없는 Teleport 역할.	역할 요청 제한
`request.search_as_roles`	사용자가 접근을 요청할 리소스를 검색하는 동안 가정하거나 가정할 수 없는 Teleport 역할.	리소스 요청 제한
`request.max_duration`	접근 요청이 승인된 경우 상승된 권한의 최대 기간.	접근이 지속되는 기간
`request.reason`	접근 요청 이유의 동작을 구성합니다.	요청 이유 요구
`request.thresholds`	접근 요청이 충족해야 하는 기준을 구성합니다.	검토 임계값
`request.suggested_reviewers`	기본적으로 접근 요청에 추가할 검토자.	제안된 검토자
`request.annotations`	접근 요청에 쓰거나 쓰지 못하도록 하는 임의의 데이터	요청 주석

접근 요청 검토#

review_requests 필드는 역할의 접근 요청 검토 능력을 구성하며, request와 마찬가지로 allow 또는 deny 아래에 올 수 있습니다:

역할 필드	설명	추가 정보
`review_requests.roles`	특정 역할에 대한 요청을 검토할 수 있는 능력을 허용하거나 거부합니다.	특정 역할에 대한 검토
`review_requests.where`	역할을 가진 사용자가 접근 요청을 검토할 수 있는 조건을 구성합니다	`where` 표현식
`review_requests.preview_as_roles`	요청된 역할을 가진 사용자가 접근할 수 있는 리소스를 나열하는 능력을 허용하거나 거부합니다	요청된 리소스 검사
`review_requests.claims_to_roles`	사용자가 traits에 따라 검토할 수 있거나 검토할 수 없는 요청에 대한 Teleport 역할.	특정 역할에 대한 검토

클라이언트 옵션#

spec의 속성인 options 필드는 추가 설정을 적용합니다:

역할 필드	설명	추가 정보
`options.request_access`	접근 요청 생성을 위한 Teleport 클라이언트 동작을 구성합니다	클라이언트가 접근을 요청하는 방법
`options.request_prompt`	사용자가 접근을 요청할 때 Teleport 클라이언트가 표시하는 프롬프트를 구성합니다	클라이언트가 접근을 요청하는 방법

역할 템플릿#

Teleport 역할 리소스에서, 특정 필드는 사용자의 접근을 구성하기 위해 함수와 변수를 사용할 수 있습니다. 필드에 사용 가능한 함수와 변수는 필드가 구성하는 접근 제어에 따라 다릅니다.

인프라 리소스 접근을 위한 템플릿 표현식#

사용자가 데이터베이스나 Kubernetes 클러스터와 같이 Teleport가 프록시하는 인프라 리소스에 인증하려고 할 때, Teleport는 사용자의 역할에서 다음을 결정합니다:

사용자가 리소스에 연결할 권한이 있는지.
인증 시 사용자가 가정할 수 있는 주체(예: Linux 서버 로그인 및 Kubernetes 그룹).

필드#

다음 역할 필드는 인프라 리소스에 대한 사용자의 접근을 제어합니다. 이 모든 필드는 Teleport 역할 리소스의 allow 및 deny 섹션 내의 필드입니다.

Teleport에 등록된 리소스의 레이블:

역할 필드	Teleport 리소스
`app_labels`	애플리케이션
`cluster_labels`	신뢰할 수 있는 클러스터
`db_labels`	데이터베이스
`db_service_labels`	데이터베이스 서비스 인스턴스
`kubernetes_labels`	Kubernetes 클러스터
`node_labels`	SSH 서버
`windows_desktop_labels`	Windows 데스크톱
`workload_identity_labels`	워크로드 ID

인프라 리소스에서 사용자가 가정할 수 있는 주체:

aws_role_arns
azure_identities
db_names
db_roles
db_users
desktop_groups
gcp_service_accounts
host_groups
host_sudoers
kubernetes_groups
kubernetes_users
logins
windows_desktop_logins

사용자가 가장할 수 있는 Teleport 주체:

impersonate.roles
impersonate.users

함수#

인프라 리소스의 주체에 대한 접근을 관리하는 역할 필드에서 다음 함수를 사용할 수 있습니다:

함수	설명
`{{email.local(variable)}}`	이메일 주소의 로컬 부분을 추출합니다.
`{{regexp.replace(variable, expression, replacement)}}`	변수 내에서 표현식의 모든 일치를 찾아 교체로 대체합니다.

Traits#

인프라 리소스에 대한 접근을 구성하는 필드의 경우, Teleport는 인증 중인 사용자의 데이터로 다음 traits를 대체합니다. 로컬 사용자 데이터베이스와 사용자의 외부 single sign-on 제공자에서 가져옵니다.

변수	설명
`{{internal.aws_role_arns}}`	사용자에 대해 허용된 AWS 역할 ARN 목록.
`{{internal.azure_identities}}`	사용자에게 사용 가능한 Teleport에서 정의된 Azure ID를 반환합니다. Azure ID는 특정 사용자에 대해 설정하거나 역할에서 정의할 수 있습니다.
`{{internal.db_names}}`	사용자에 대해 허용된 모든 데이터베이스 이름 목록.
`{{internal.db_roles}}`	사용자에 대해 허용된 모든 데이터베이스 역할 목록.
`{{internal.db_users}}`	사용자에 대해 허용된 모든 데이터베이스 사용자 목록.
`{{internal.gcp_service_accounts}}`	사용자의 GCP 서비스 계정 목록.
`{{internal.jwt}}`	앱 접근에 사용되는 JWT 헤더.
`{{internal.kubernetes_groups}}`	사용자에 대해 허용된 Kubernetes 그룹 목록.
`{{internal.kubernetes_users}}`	사용자에 대해 허용된 Kubernetes 사용자 목록.
`{{internal.logins}}`	Teleport의 로컬 사용자 데이터베이스에 저장된 값과 루트 클러스터의 로그인으로 대체됩니다. 로컬 사용자의 경우, Teleport는 `tctl users add [user] <allowed logins>` 명령어에서 사용된 "허용된 로그인" 매개변수로 대체합니다. 역할이 신뢰할 수 있는 클러스터의 리프 클러스터 내에 있으면, 사용자가 로컬 사용자이든 SSO 제공자에서 온 사용자이든 루트 클러스터의 로그인으로 대체합니다. 예를 들어, 사용자가 루트 클러스터에서 `ubuntu` 로그인을 가지면, 이 변수를 사용하여 리프 클러스터에서 `ubuntu`로 대체됩니다.
`{{internal.windows_logins}}`	사용자에 대해 허용된 Windows 로그인 목록.
`{{external.xyz}}`	외부 SSO 제공자의 값으로 대체됩니다. SAML을 사용하는 경우 "xyz" assertion 값으로 확장됩니다. OIDC의 경우 변수는 "xyz" 클레임의 값으로 확장됩니다. Teleport 역할에서 `external` 변수를 참조하는 방법에 대한 자세한 내용은 다음 섹션을 참조하십시오.

Teleport 역할에서 내부 traits 참조#

internal trait 네임스페이스는 위 표에 포함된 정확한 내부 trait 이름만 포함합니다. 로컬 Teleport 사용자의 경우 이러한 traits는 사용자 리소스의 spec.traits 필드에서 설정할 수 있습니다. 이러한 trait 이름은 IdP의 속성 또는 클레임에 포함된 경우 SSO 사용자에게도 설정할 수 있습니다.

내부 traits는 사전 설정 역할 access 및 require-trusted-device에서 사용자 traits를 기반으로 리소스에 대한 접근을 허용하기 위해 참조됩니다. 외부 traits는 사전 설정 역할에서 참조되지 않습니다(해당 사전 설정 역할을 수동으로 편집하지 않는 한).

역할에서 내부 trait을 참조하려면 다음 형식을 사용할 수 있습니다:

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

Warning

이전 버전과의 호환성을 위해 일부 내부 traits는 리프 클러스터와 루트 클러스터에서 확장될 때 다를 수 있습니다. 리프 클러스터에서 logins, kubernetes_groups, kubernetes_users, db_names, db_users, aws_role_arns traits는 모두 사용자가 Teleport에 로그인할 때 사용자의 인증서에 인코딩된 완전한 값 집합으로 설정됩니다. 예를 들어, 리프 클러스터에 접근할 때 internal.logins trait은 루트 클러스터의 사용자 internal.logins trait 값과 루트 클러스터에서 사용자가 보유한 역할의 spec.allow.logins 필드에만 포함된 로그인을 포함할 수 있는 사용자에 대해 허용된 SSH 로그인의 완전한 목록으로 설정됩니다.

Teleport 역할에서 외부 traits 참조#

로컬 Teleport 사용자의 경우, external trait 네임스페이스는 사용자 리소스의 spec.traits 필드에서 모든 값을 포함합니다. 여기에는 사용자 정의 trait 이름과 위의 internal traits와 일치하는 이름이 포함됩니다. 예를 들어, {{internal.logins}}와 {{external.logins}} 모두 logins trait을 참조하는 유효한 방법이지만, groups라는 사용자 정의 trait은 {{external.groups}}로만 참조할 수 있습니다.

사용자가 single sign-on identity provider(IdP)를 통해 Teleport에 인증하면, Teleport는 IdP에서 받은 속성을 사용하여 external traits를 채웁니다. 예를 들어, 응답에 다음 SAML assertion 속성이 있다고 가정합니다:

<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"]}}'

역할 템플릿에서 이러한 변수를 참조하는 데 다음 두 가지 형식을 사용할 수 있으며, 여기서 trait는 trait의 이름입니다:

점 구문: {{external.trait}}
대괄호 구문: {{external["trait"]}}

Teleport는 위의 템플릿 변수를 trait라는 SAML 속성 또는 OIDC 클레임의 값으로 확장합니다.

외부 trait이 문자로 시작하고 문자, 숫자, 밑줄만 포함하면 점 구문으로 지정할 수 있습니다. 그렇지 않으면 trait을 지정하기 위해 대괄호 구문을 사용해야 합니다.

Microsoft Entra ID 또는 ADFS를 IdP로 사용하는 경우, 이러한 IdP는 다음과 같은 URL에 속성 키를 할당하므로 대괄호 표기법을 사용해야 합니다:

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

identity provider를 통해 사용 가능한 외부 traits의 일반적인 예시는 다음과 같습니다:

{{external.logins}}
{{external.username}}
{{external.env}}

Teleport는 external 변수를 문자열 또는 문자열 목록으로만 확장할 수 있습니다. OIDC 기반 SSO 솔루션을 사용하는 경우, identity provider가 지원되는 데이터 유형의 값을 가진 클레임을 포함하도록 구성되었는지 확인하십시오.

사용 가능한 클레임 및 속성의 전체 목록은 identity provider 문서를 참조하십시오.

기타 템플릿 변수#

사용자 traits 외에도 역할 템플릿에서 다음 변수를 사용할 수 있습니다:

변수	설명
`{{user.metadata.name}}`	사용자의 Teleport 사용자 이름. 사용자가 "소유"하거나 책임지는 리소스를 매칭하는 데 유용합니다.

접근 요청 템플릿 함수#

다음 변수와 함수는 사용자의 접근 요청 제출 및 검토 권한에 대한 더 세밀한 제어를 허용합니다.

필드#

다음 필드에서 접근 요청 템플릿 함수를 사용할 수 있습니다. 이러한 필드는 allow 규칙이나 deny 규칙 내에 포함될 수 있습니다:

request.search_as_roles
request.roles
review_requests.preview_as_roles
review_requests.roles
review_requests.where

함수#

접근 요청은 다음 역할 템플릿 함수를 지원합니다:

함수	설명
`{{regexp.match(regexp)}}`	정규식이 사용자의 역할과 일치하면 `true`를 반환합니다.
`{{regexp.not_match(regexp)}}`	정규식이 사용자의 역할과 일치하지 않으면 `true`를 반환합니다.

정규식은 글로브 스타일 와일드카드(* 문자)와 Go 스타일 정규 표현식 모두 지원합니다. 표현식이 ^ 문자로 시작하고 $ 문자로 끝나면 Teleport는 이를 정규 표현식으로 평가합니다. 그렇지 않으면 와일드카드 표현식으로 평가합니다. 와일드카드는 0개 이상의 문자 시퀀스와 일치합니다.

변수#

Teleport는 위 필드의 값에 대한 변수 확장을 수행하지 않습니다.

필터 필드#

다음은 이 가이드의 where 및 filter 조건에서 사용되는 필드에 대한 설명입니다:

필드	설명
`user.spec.roles`	사용자에게 할당된 역할 목록
`session.participants`	세션 녹화의 참가자 목록
`session_tracker.participants`	세션의 참가자 목록
`user.metadata.name`	사용자의 이름

언어에 대한 심층적인 설명은 술어 언어 가이드를 참조하십시오.

Teleport 역할 참조

원문 보기

번역일: 2026-05-14

요약

이 가이드는 Teleport 역할을 사용하여 Teleport 클러스터에서 역할 기반 접근 제어(RBAC)를 관리하는 방법을 보여줍니다.

Teleport 역할은 두 가지 규칙 목록을 통해 접근을 관리합니다: allow 규칙과 deny 규칙. 접근 규칙을 선언할 때 다음 사항을 염두에 두십시오:

기본적으로 허용되는 것은 없습니다.
Deny 규칙이 먼저 평가되고 우선순위를 갖습니다.
Deny 규칙은 Access Lists를 통해 부여된 역할에서는 사용하지 않는 것이 좋습니다.

다음 중 하나를 사용하여 Teleport 역할 및 기타 동적 리소스를 관리할 수 있습니다:

Teleport 웹 UI
tctl 클라이언트 도구
Teleport Terraform 제공자
Teleport Kubernetes 오퍼레이터
사용자 정의 API 클라이언트

동적 리소스 관리에 대한 자세한 내용은 동적 리소스 가이드를 참조하십시오.

다음 명령어를 실행하여 로컬 워크스테이션에서 클러스터의 모든 역할을 볼 수 있습니다:

# Log in to your cluster with tsh so you can use tctl from your local machine.
$ tsh login --user=myuser --proxy=example.teleport.sh
$ tctl get roles

역할 명세 예시#

전체 역할 명세입니다:

kind: role
version: v8
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
    # ssh_port_forwarding controls which TCP port forwarding modes are allowed over SSH. This replaces
    # the deprecated port_forwarding field, which did not differentiate between remote and local
    # port forwarding modes. If you have any existing roles that allow forwarding by enabling the
    # legacy port_forwarding field then the forwarding controls configured in ssh_port_forwarding will be
    # ignored.
    ssh_port_forwarding:
      # configures remote port forwarding behavior
      remote:
        enabled: true
      # configures local port forwarding behavior
      local:
        enabled: 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: false
    # 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|required-for-humans|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 or Teleport Connect).
    # 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 or Teleport Connect).
    # 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
    # Specify whether this role supports auto-provisioning of local Windows users.
    create_desktop_user: 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: login@github.com
       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

  # 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"
    ]

    # List of local Windows groups the created user will be added to.
    # Any that don't already exist are created. Only applies when
    # create_desktop_user is 'true'.
    desktop_groups:
    - developers
    # to make the newly-created user an administrator
    - Administrators
    # IdP trait templating is also supported
    - '{{external.desktop_groups}}'

    # 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)
        # - <arbitrary string> (Resource plural name, e.g. pods, deployments, cronjobs, mycustomresources)
      - kind: '*'
        # The resource name of the Kubernetes cluster in which to allow access
        # to the resources you specify with 'name' and 'kind'.
        api_group: '*'
        # 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 for namespaced
        # resource. If set, global resources will not match.
        # 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: ['*']

    # Database account names this role can connect as.
    #
    # Supports role templating with traits.
    db_users: ['{{email.local(external.email)}}']
    # Database names this role will be able to connect to. Database names are
    # only enforced for PostgreSQL, MongoDB, and Cloud Spanner databases.
    #
    # Supports role templating with traits.
    db_names: ['{{external.db_names}}']
    # Label selectors for database instances this role has access to.
    #
    # Supports role templating with traits.
    db_labels:
      'env': '{{regexp.replace(external.env, "^(staging)$", "$1")}}'

    # List of database roles to grant to the auto-provisioned user. Mutually
    # exclusive with 'db_permissions'.
    #
    # Supports role templating with traits.
    db_roles: ['{{external.db_roles}}']

    # List of database permissions to grant to the auto-provisioned user.
    # 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'

    # workload_identity_labels: a user/bot with this role will be allowed to
    # issue Workload Identities with labels matching below.
    #
    # Supports role templating with traits.
    workload_identity_labels:
      'env': 'prod'
      'team': '{{external.team}}'

    # 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"'
    workload_identity_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'

    # AWS account and permission set bindings for the Identity Center integration
    account_assignments:
    - # AWS identity center account ID
      account: "<account_id>"
      # name of the permission set in AWS
      name: AdministratorAccess
      # permission set ARN
      permission_set: arn:aws:sso:::permissionSet/ssoins-1234/ps-5678 # permission set ARN

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

      # '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"

      # 'reason' defines settings for the reason for the access provided by the user.
      reason:
        # 'mode' can be either "required" or "optional". Empty string is treated as
        # "optional". If a role has the request reason mode set to "required", then reason
        # is required for all Access Requests requesting roles or resources allowed by
        # this role. It applies only to users who have this role assigned.
        mode: "optional"
        # 'prompt' is a custom message prompted to the user for the requested roles or resources searchable
	      # as other roles. This is only applied to the requested roles and resources specifying the prompt.
        prompt: I am a reason prompt specific to a requested role or resource

      # 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"]

    # GitHub-related permissions used for proxying Git commands.
    github_permissions:
      # List of GitHub organizations the user has access to.
    - orgs:
      - my-org

    # mcp: defines MCP servers related permissions.
    mcp:
      # tools: list of tools allowed for this role.
      #
      # No tools are allowed if not specified.
      # Each entry can be a literal string, a glob pattern, or a regular
      # expression (must start with '^' and end with '$'). A wildcard '*' allows
      # all tools.
      # This value field also supports variable interpolation.
      tools:
      - search-files
      - slack_*
      - ^(get|list|read).*$
      - "{{internal.mcp_tools}}"
      - "{{external.mcp_tools}}"

    # 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
    # instance           - a Teleport instance
    # event              - structured audit logging event
    #
    # workload_identity     - config for Machine & Workload Identity SVIDS
    # bot                   - config for Machine & Workload Identity bots
    #
    # 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
    # git_server            - Git server 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: {}

역할 옵션#

역할은 사용자가 시작한 세션에 특정 제한을 정의할 수 있습니다. 아래 표는 여러 역할이 사용자에게 할당된 경우 각 옵션의 동작을 문서화합니다:

옵션	설명	다중 역할 동작
`max_session_ttl`	사용자의 SSH 인증서의 최대 유효 시간(TTL)	가장 짧은 TTL이 적용됨
`forward_agent`	SSH 에이전트 포워딩 허용	논리적 "OR" 즉 어느 역할이라도 에이전트 포워딩을 허용하면 허용됨
`ssh_port_forwarding`	TCP 포트 포워딩 허용	논리적 "AND" 즉 어느 역할이라도 포트 포워딩을 거부하면 거부됨
`ssh_file_copy`	SCP/SFTP 허용	논리적 "AND" 즉 모든 역할이 파일 복사를 허용하면 허용됨
`client_idle_timeout`	유휴 간격 후 활성 세션을 강제 종료	가장 짧은 타임아웃 값이 적용됨 즉 가장 제한적인 값이 선택됨
`disconnect_expired_cert`	클라이언트 인증서 만료 시 활성 세션을 강제 종료	논리적 "OR" 즉 하나의 역할이라도 세션 종료를 요구하면 "yes"로 평가됨
`max_sessions`	Teleport를 통해 단일 SSH 연결에서 설정할 수 있는 총 세션 채널 수	가장 낮은 값이 우선됨.
`enhanced_recording`	BFP 기반 세션 레코더가 기록해야 할 이벤트 표시
`permit_x11_forwarding`	OpenSSH 클라이언트 및 서버에서 사용자가 X11 포워딩을 활성화할 수 있도록 허용
`device_trust_mode`	이 역할이 할당된 사용자에 대한 인증된 장치 접근 강제 (`required`, `required-for-humans`, `optional`, `off`). 역할의 allow 필드 리소스에만 적용됨.
`require_session_mfa`	사용자 로그인 세션에 세션별 MFA 또는 PIV 하드웨어 키 제한 강제 (`no`, `yes`, `hardware_key`, `hardware_key_touch`). 역할의 allow 필드 리소스에만 적용됨.	세션별 MFA의 경우 논리적 "OR" 즉 하나의 역할이라도 세션 MFA를 요구하면 "yes"로 평가됨
`mfa_verification_interval`	연속적인 MFA 인증 사이에 경과할 수 있는 최대 기간 정의	가장 짧은 간격이 적용됨
`lock`	잠금 모드 (`strict` 또는 `best_effort`)	충돌 시 `strict`가 우선됨
`request_access`	Enterprise 전용 접근 요청 전략 (`optional`, `always` 또는 `reason`)
`request_prompt`	접근 요청 "reason" 필드에 대한 프롬프트
`max_connections`	Enterprise 전용 Teleport를 통해 시작할 수 있는 동시 세션 제한	가장 낮은 값이 우선됨.
`max_kubernetes_connections`	사용자당 최대 동시 Kubernetes 세션 수 정의
`record_session`	세션 녹화 모드를 정의합니다.	가장 엄격한 값이 우선됩니다.
`desktop_clipboard`	데스크톱 세션에서 클립보드 공유 허용	논리적 "AND" 즉 모든 역할이 클립보드 공유를 활성화하면 "yes"로 평가됨
`desktop_directory_sharing`	로컬 워크스테이션 디렉터리를 원격 데스크톱에 공유하는 것을 허용	논리적 "AND" 즉 모든 역할이 디렉터리 공유를 활성화하면 "yes"로 평가됨
`create_desktop_user`	로컬 Windows 데스크톱에서 데스크톱 자동 사용자 생성 허용.	논리적 "AND" 즉 데스크톱 리소스와 일치하는 모든 역할에 대해. 리소스에 대한 접근을 허용하는 모든 역할이 `true`로 설정되면 사용자 생성이 허용됨. 하나라도 `false`로 설정되면 자동 사용자 생성이 거부됨.
`pin_source_ip`	SSH 인증서에 대한 소스 IP 고정 활성화.	논리적 "OR" 즉 하나의 역할이라도 세션 종료를 요구하면 "yes"로 평가됨
`cert_extensions`	SSH 인증서에 포함할 확장 지정
`create_host_user_mode`	호스트에서 사용자가 자동으로 생성되도록 허용	논리적 "AND" 즉 서버와 일치하는 모든 역할이 호스트 사용자 생성을 지정하는 경우 (`off`, `keep`, `insecure-drop`), 모든 역할에서 지정한 옵션으로 평가됨. 일부 역할이 `insecure-drop` 또는 `keep`을 모두 지정하면 `keep`으로 평가됨
`create_db_user_mode`	데이터베이스 사용자 자동 프로비저닝 허용. 옵션: `off` (데이터베이스 사용자 자동 프로비저닝 비활성화), `keep` (세션 종료 시 사용자 비활성화, 역할 제거 및 잠금), `best_effort_drop` (세션 종료 시 사용자 삭제 시도, 실패 시 비활성화로 폴백).	논리적 "OR" 즉 어느 역할이라도 데이터베이스 사용자 자동 프로비저닝을 허용하면 허용됨

사전 설정 역할#

Teleport는 여러 사전 설정 역할을 제공합니다:

Role	Description	Enterprise-only
`access`	Allows access to cluster resources.
`editor`	Allows editing of cluster configuration settings.
`auditor`	Allows reading cluster events, audit logs, and playing back session records.
`access-plugin`	Enables self-hosted Access Request plugin features.
`list-access-request-resources`	Allows reading Access Request resources.
`requester`	Allows a user to create Access Requests.	✔
`reviewer`	Allows review of Access Requests.	✔
`group-access`	Allows access to all user groups.	✔
`device-admin`	Used to manage trusted devices.	✔
`device-enroll`	Used to grant device enrollment powers to users.	✔
`require-trusted-device`	Requires trusted device access to resources.	✔
`terraform-provider`	Allows the Teleport Terraform provider to configure all of its supported Teleport resources.

역할 버전#

현재 지원되는 역할 버전은 v3, v4, v5, v6, v7, v8 총 여섯 가지입니다.

레이블	`v3` 기본값	`v4` 이상 기본값
`node_labels`	역할에 로그인이 있으면 `[{"": ""}]`, 없으면 `[]`	`[]`
`app_labels`	`[{"": ""}]`	`[]`
`kubernetes_labels`	`[{"": ""}]`	`[]`
`db_labels`	`[{"": ""}]`	`[]`

역할 v6은 Kubernetes 리소스에 대한 세밀한 제어를 허용하는 새 필드 kubernetes_resources를 도입했습니다. 자세한 내용은 Kubernetes RBAC를 참조하십시오.

역할 v7은 kubernetes_resources 필드에 더 많은 kind 값을 지원합니다.

버전 간의 차이에 대한 자세한 내용은 Kubernetes 리소스를 참조하십시오.

`kubernetes_resources`의 기본값#

kubernetes_resources의 기본값은 Kubernetes 클러스터에 대한 접근을 허용하는 레이블이 설정된 경우 적용됩니다.

버전	`kubernetes_resources`
`v3`, `v4` 및 `v5`	`[{"kind":"pod","name":"","namespace":"","verbs":["*"]}]`
`v6`	`[]`
`v7`	`[{"kind":"","name":"","namespace":"","verbs":[""]}]`
`v8`	`[{"kind":"","api_group":"","name":"","namespace":"","verbs":[""]},{"kind":"","api_group":"","name":"","namespace":"","verbs":["*"]}]`

인프라 리소스에 대한 RBAC#

다음 사용 사례를 고려하십시오:

예시#

다른 노드에 대한 접근은 거부됩니다.

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']

동적 RBAC

확장 레이블 매칭 구문#

다음은 다양한 정규식을 사용한 더 복잡한 필터링 예시입니다.

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$'

레이블 표현식#

다음이 필요한 경우 Teleport 역할은 술어 표현식을 사용하여 리소스 레이블 매칭도 지원합니다:

OR 및 AND 연산자를 통한 로직 결합
레이블 키에 대한 매칭 수행
부정 매칭 구현

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

node_labels_expression
app_labels_expression
cluster_labels_expression
kubernetes_labels_expression
db_labels_expression
db_service_labels_expression
windows_desktop_labels_expression
group_labels_expression
workload_identity_labels_expression

언어에 대한 심층적인 설명은 술어 언어 가이드를 참조하십시오.

동적 Teleport 리소스에 대한 RBAC#

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

세션 녹화에 대한 RBAC#

세션 녹화에 대한 접근을 추가로 제한할 수 있습니다.

사전 설정 감사자 역할

`where` 절 이해#

where 절은 접근이 허용되려면 true로 평가되어야 하는 조건으로 작동합니다. 다음을 참조할 수 있는 술어 표현식을 사용합니다:

인증된 사용자의 속성(이름, 역할, traits)
세션 녹화에 대한 메타데이터(참가자, 프로토, 생성자 등)
리소스별 속성(서버 세부 정보, 데이터베이스 정보 등)

기본 구문 예시:

where: contains(session.participants, user.metadata.name)

이 표현식은 현재 사용자가 세션의 참가자 목록에 있을 때만 true로 평가됩니다.

일반적인 접근 제어 레시피#

다음은 일반적인 접근 제어 패턴을 구현하기 위해 where 표현식을 사용하는 실용적인 예시입니다:

세션 참가자로 제한#

사용자가 참여한 세션 녹화만 볼 수 있도록 허용합니다:

version: v8
kind: role
metadata:
  name: only-own-sessions
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants, user.metadata.name)

사용자 역할로 제한#

세션 생성자와 역할을 공유하는 사용자에게만 접근 허용:

version: v8
kind: role
metadata:
  name: sessions-viewer
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains_any(user.spec.roles, session.user_roles)

팀 Trait으로 제한#

같은 팀 구성원이 서로의 세션을 볼 수 있도록 허용합니다:

version: v8
kind: role
metadata:
  name: team-sessions-viewer
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains_any(session.user_traits["team"], user.spec.traits["team"])

세션 참가자로 제한#

사용자가 참여한 세션만 볼 수 있도록 허용합니다:

version: v5
kind: role
metadata:
  name: own-sessions
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants, user.metadata.name)

리소스 유형으로 제한#

SSH 세션 녹화만 볼 수 있도록 허용합니다:

version: v5
kind: role
metadata:
  name: ssh-sessions-only
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: session.proto == "ssh"

여러 조건 결합#

이 규칙은 사용자가 참가자이거나 해당 노드가 팀이 소유하는 경우에만 SSH 세션 녹화를 볼 수 있도록 합니다.

version: v5
kind: role
metadata:
  name: complex-sessions-access
spec:
  allow:
    rules:
    - resources: [session]
      verbs: [list, read]
      where: >
        (contains(session.participants, user.metadata.name) ||
         contains(user.spec.traits["team"], session.server_labels["team"])) &&
        session.proto == "ssh"

필터 필드#

규칙의 where 필드를 사용하면 사용자 traits 및 리소스 메타데이터를 기반으로 리소스에 대한 접근을 필터링할 수 있습니다.

사용자 필드#

사용자 필드	설명	유형
`user.metadata.name`	사용자의 이름.	`string`
`user.spec.traits`	사용자에게 할당된 traits.	`dict<string, array<string>>`
`user.spec.roles`	사용자에게 할당된 역할.	`array<string>`

세션 필드#

세션 필드는 변경 불가능합니다

세션 필드는 변경 불가능하며 세션이 생성된 순간의 상태를 캡처합니다.

기본 리소스가 변경되면(예: 서버 레이블), 이러한 필드는 업데이트되지 않으며 세션의 RBAC는 변경 사항을 반영하지 않습니다.

세션 필드	설명	유형
`session.id`	세션의 고유 식별자.	`string`
`session.kind`	세션의 종류 (예: "ssh", "kube", "db", "rdp").	`string`
`session.participants`	세션에 참여한 사용자 목록.	`array<string>`
`session.proto`	세션에 사용된 프로토 (예: "ssh", "kube", "db", "rdp").	`string`
`session.user`	세션을 시작한 사용자.	`string`
`session.user_roles`	세션을 시작한 사용자에게 할당된 역할.	`array<string>`
`session.user_traits`	세션을 시작한 사용자에게 할당된 traits.	`dict<string, array<string>>`

세션 종류에 따라 필터링에 사용할 수 있는 추가 세션 필드가 있습니다.

다음 서버 세션 필드도 위의 사용자 및 세션 필드와 함께 SSH 세션에 대한 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다.

서버 세션 필드	설명	유형
`session.server_id`	세션이 이루어진 서버의 고유 식별자.	`string`
`session.server_hostname`	세션이 이루어진 서버의 호스트 이름.	`string`
`session.server_labels`	세션이 이루어진 서버에 할당된 레이블.	`dict<string, string>`
`session.server_addr`	세션이 이루어진 서버의 주소.	`string`
`session.login`	세션 중 서버에 로그인하는 데 사용된 사용자 이름.	`string`

다음 Kubernetes 세션 필드는 위의 사용자 및 세션 필드와 함께 Kubernetes 세션에 대한 접근을 필터링하기 위해 where 표현식에서 사용할 수 있습니다.

Kubernetes 세션 필드	설명	유형
`session.kubernetes_cluster`	세션이 이루어진 Kubernetes 클러스터의 이름.	`string`
`session.kubernetes_labels`	세션이 이루어진 Kubernetes 클러스터에 할당된 레이블.	`dict<string, string>`
`session.kubernetes_user`	세션에서 사용된 Kubernetes 사용자.	`string`
`session.kubernetes_groups`	세션에서 사용된 Kubernetes 그룹.	`array<string>`
`session.kubernetes_pod_namespace`	세션이 이루어진 Kubernetes 클러스터의 네임스페이스.	`string`
`session.kubernetes_pod_name`	세션이 이루어진 Kubernetes 클러스터의 파드 이름.	`string`
`session.kubernetes_container_name`	세션이 이루어진 Kubernetes 클러스터의 컨테이너 이름.	`string`

데이터베이스 세션 필드	설명	유형
`session.db_service`	세션이 이루어진 데이터베이스 서비스의 이름.	`string`
`session.db_protocol`	데이터베이스 연결에 사용된 프로토콜 (예: "postgres", "mysql").	`string`
`session.db_uri`	세션이 이루어진 데이터베이스의 URI.	`string`
`session.db_name`	세션 중 접근한 데이터베이스의 이름.	`string`
`session.db_user`	세션 중 사용된 데이터베이스 사용자.	`string`
`session.db_labels`	세션이 이루어진 데이터베이스에 할당된 레이블.	`dict<string, string>`
`session.db_type`	데이터베이스의 유형 (예: "postgres", "mysql").	`string`

Windows 데스크톱 세션 필드	설명	유형
`session.windows_desktop_service`	세션이 이루어진 Windows 데스크톱 서비스의 이름.	`string`
`session.desktop_addr`	세션이 이루어진 Windows 데스크톱의 주소.	`string`
`session.desktop_name`	세션이 이루어진 Windows 데스크톱의 이름.	`string`
`session.domain`	세션이 이루어진 Windows 데스크톱의 도메인.	`string`
`session.windows_user`	세션 중 Windows 데스크톱에 로그인하는 데 사용된 사용자 이름.	`string`
`session.desktop_labels`	세션이 이루어진 Windows 데스크톱에 할당된 레이블.	`dict<string, string>`

함수#

세션 녹화에 대한 접근을 필터링하기 위해 where 표현식에서 다음 함수를 사용할 수 있습니다:

함수	시그니처	설명
`contains`	`contains(array<string>, string) -> bool`	배열에 지정된 값이 포함되어 있으면 true 반환.
`contains_any`	`contains_any(array<string>, array<string>) -> bool`	두 배열에 공통 요소가 있으면 true 반환.
`contains_all`	`contains_all(array<string>, array<string>) -> bool`	첫 번째 배열이 두 번째 배열의 모든 요소를 포함하면 true 반환.
`can_view`	`can_view() -> bool`	사용자가 Teleport의 SSH 노드, Kubernetes 클러스터, 데이터베이스 또는 Windows 머신을 볼 수 있으면 true 반환.
`equals`	`equals(array<string>, array<string>) -> bool`	두 문자열 또는 두 배열이 같으면 true 반환.
`set`	`set(string,string...) -> array<string>`	하나 이상의 문자열을 배열로 변환.

활성 세션에 대한 RBAC#

공유 세션에 대한 접근을 추가로 제한할 수 있습니다. 아래 예시는 활성 SSH 세션에 대한 접근을 세션을 만든 사용자로만 제한하는 방법을 보여줍니다.

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)'

접근 요청#

다음 역할 필드는 접근 요청을 구성합니다. 접근 요청 구성 필드 및 상호 관계에 대한 전체 설명은 접근 요청 구성 가이드를 참조하십시오.

접근 요청 생성#

역할 내에서 request 필드는 사용자가 접근 요청을 생성하는 능력을 구성합니다. request 필드는 spec.allow와 spec.deny 모두에 포함될 수 있습니다:

역할 필드	설명	추가 정보
`request.roles`	사용자가 요청하거나 요청할 수 없는 Teleport 역할	역할 요청 제한
`request.claims_to_roles`	사용자가 traits을 기반으로 접근하거나 접근할 수 없는 Teleport 역할.	역할 요청 제한
`request.search_as_roles`	사용자가 접근을 요청할 리소스를 검색하는 동안 가정하거나 가정할 수 없는 Teleport 역할.	리소스 요청 제한
`request.max_duration`	접근 요청이 승인된 경우 상승된 권한의 최대 기간.	접근이 지속되는 기간
`request.reason`	접근 요청 이유의 동작을 구성합니다.	요청 이유 요구
`request.thresholds`	접근 요청이 충족해야 하는 기준을 구성합니다.	검토 임계값
`request.suggested_reviewers`	기본적으로 접근 요청에 추가할 검토자.	제안된 검토자
`request.annotations`	접근 요청에 쓰거나 쓰지 못하도록 하는 임의의 데이터	요청 주석

접근 요청 검토#

review_requests 필드는 역할의 접근 요청 검토 능력을 구성하며, request와 마찬가지로 allow 또는 deny 아래에 올 수 있습니다:

역할 필드	설명	추가 정보
`review_requests.roles`	특정 역할에 대한 요청을 검토할 수 있는 능력을 허용하거나 거부합니다.	특정 역할에 대한 검토
`review_requests.where`	역할을 가진 사용자가 접근 요청을 검토할 수 있는 조건을 구성합니다	`where` 표현식
`review_requests.preview_as_roles`	요청된 역할을 가진 사용자가 접근할 수 있는 리소스를 나열하는 능력을 허용하거나 거부합니다	요청된 리소스 검사
`review_requests.claims_to_roles`	사용자가 traits에 따라 검토할 수 있거나 검토할 수 없는 요청에 대한 Teleport 역할.	특정 역할에 대한 검토

클라이언트 옵션#

spec의 속성인 options 필드는 추가 설정을 적용합니다:

역할 필드	설명	추가 정보
`options.request_access`	접근 요청 생성을 위한 Teleport 클라이언트 동작을 구성합니다	클라이언트가 접근을 요청하는 방법
`options.request_prompt`	사용자가 접근을 요청할 때 Teleport 클라이언트가 표시하는 프롬프트를 구성합니다	클라이언트가 접근을 요청하는 방법

역할 템플릿#

인프라 리소스 접근을 위한 템플릿 표현식#

사용자가 리소스에 연결할 권한이 있는지.
인증 시 사용자가 가정할 수 있는 주체(예: Linux 서버 로그인 및 Kubernetes 그룹).

필드#

다음 역할 필드는 인프라 리소스에 대한 사용자의 접근을 제어합니다. 이 모든 필드는 Teleport 역할 리소스의 allow 및 deny 섹션 내의 필드입니다.

Teleport에 등록된 리소스의 레이블:

역할 필드	Teleport 리소스
`app_labels`	애플리케이션
`cluster_labels`	신뢰할 수 있는 클러스터
`db_labels`	데이터베이스
`db_service_labels`	데이터베이스 서비스 인스턴스
`kubernetes_labels`	Kubernetes 클러스터
`node_labels`	SSH 서버
`windows_desktop_labels`	Windows 데스크톱
`workload_identity_labels`	워크로드 ID

인프라 리소스에서 사용자가 가정할 수 있는 주체:

aws_role_arns
azure_identities
db_names
db_roles
db_users
desktop_groups
gcp_service_accounts
host_groups
host_sudoers
kubernetes_groups
kubernetes_users
logins
windows_desktop_logins

사용자가 가장할 수 있는 Teleport 주체:

impersonate.roles
impersonate.users

함수#

인프라 리소스의 주체에 대한 접근을 관리하는 역할 필드에서 다음 함수를 사용할 수 있습니다:

함수	설명
`{{email.local(variable)}}`	이메일 주소의 로컬 부분을 추출합니다.
`{{regexp.replace(variable, expression, replacement)}}`	변수 내에서 표현식의 모든 일치를 찾아 교체로 대체합니다.

Traits#

변수	설명
`{{internal.aws_role_arns}}`	사용자에 대해 허용된 AWS 역할 ARN 목록.
`{{internal.azure_identities}}`	사용자에게 사용 가능한 Teleport에서 정의된 Azure ID를 반환합니다. Azure ID는 특정 사용자에 대해 설정하거나 역할에서 정의할 수 있습니다.
`{{internal.db_names}}`	사용자에 대해 허용된 모든 데이터베이스 이름 목록.
`{{internal.db_roles}}`	사용자에 대해 허용된 모든 데이터베이스 역할 목록.
`{{internal.db_users}}`	사용자에 대해 허용된 모든 데이터베이스 사용자 목록.
`{{internal.gcp_service_accounts}}`	사용자의 GCP 서비스 계정 목록.
`{{internal.jwt}}`	앱 접근에 사용되는 JWT 헤더.
`{{internal.kubernetes_groups}}`	사용자에 대해 허용된 Kubernetes 그룹 목록.
`{{internal.kubernetes_users}}`	사용자에 대해 허용된 Kubernetes 사용자 목록.
`{{internal.logins}}`	Teleport의 로컬 사용자 데이터베이스에 저장된 값과 루트 클러스터의 로그인으로 대체됩니다. 로컬 사용자의 경우, Teleport는 `tctl users add [user] <allowed logins>` 명령어에서 사용된 "허용된 로그인" 매개변수로 대체합니다. 역할이 신뢰할 수 있는 클러스터의 리프 클러스터 내에 있으면, 사용자가 로컬 사용자이든 SSO 제공자에서 온 사용자이든 루트 클러스터의 로그인으로 대체합니다. 예를 들어, 사용자가 루트 클러스터에서 `ubuntu` 로그인을 가지면, 이 변수를 사용하여 리프 클러스터에서 `ubuntu`로 대체됩니다.
`{{internal.windows_logins}}`	사용자에 대해 허용된 Windows 로그인 목록.
`{{external.xyz}}`	외부 SSO 제공자의 값으로 대체됩니다. SAML을 사용하는 경우 "xyz" assertion 값으로 확장됩니다. OIDC의 경우 변수는 "xyz" 클레임의 값으로 확장됩니다. Teleport 역할에서 `external` 변수를 참조하는 방법에 대한 자세한 내용은 다음 섹션을 참조하십시오.

Teleport 역할에서 내부 traits 참조#

역할에서 내부 trait을 참조하려면 다음 형식을 사용할 수 있습니다:

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

Warning

Teleport 역할에서 외부 traits 참조#

<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"]}}'

역할 템플릿에서 이러한 변수를 참조하는 데 다음 두 가지 형식을 사용할 수 있으며, 여기서 trait는 trait의 이름입니다:

점 구문: {{external.trait}}
대괄호 구문: {{external["trait"]}}

Teleport는 위의 템플릿 변수를 trait라는 SAML 속성 또는 OIDC 클레임의 값으로 확장합니다.

Microsoft Entra ID 또는 ADFS를 IdP로 사용하는 경우, 이러한 IdP는 다음과 같은 URL에 속성 키를 할당하므로 대괄호 표기법을 사용해야 합니다:

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

identity provider를 통해 사용 가능한 외부 traits의 일반적인 예시는 다음과 같습니다:

{{external.logins}}
{{external.username}}
{{external.env}}

사용 가능한 클레임 및 속성의 전체 목록은 identity provider 문서를 참조하십시오.

기타 템플릿 변수#

사용자 traits 외에도 역할 템플릿에서 다음 변수를 사용할 수 있습니다:

변수	설명
`{{user.metadata.name}}`	사용자의 Teleport 사용자 이름. 사용자가 "소유"하거나 책임지는 리소스를 매칭하는 데 유용합니다.

접근 요청 템플릿 함수#

다음 변수와 함수는 사용자의 접근 요청 제출 및 검토 권한에 대한 더 세밀한 제어를 허용합니다.

필드#

다음 필드에서 접근 요청 템플릿 함수를 사용할 수 있습니다. 이러한 필드는 allow 규칙이나 deny 규칙 내에 포함될 수 있습니다:

request.search_as_roles
request.roles
review_requests.preview_as_roles
review_requests.roles
review_requests.where

함수#

접근 요청은 다음 역할 템플릿 함수를 지원합니다:

함수	설명
`{{regexp.match(regexp)}}`	정규식이 사용자의 역할과 일치하면 `true`를 반환합니다.
`{{regexp.not_match(regexp)}}`	정규식이 사용자의 역할과 일치하지 않으면 `true`를 반환합니다.

변수#

Teleport는 위 필드의 값에 대한 변수 확장을 수행하지 않습니다.

필터 필드#

다음은 이 가이드의 where 및 filter 조건에서 사용되는 필드에 대한 설명입니다:

필드	설명
`user.spec.roles`	사용자에게 할당된 역할 목록
`session.participants`	세션 녹화의 참가자 목록
`session_tracker.participants`	세션의 참가자 목록
`user.metadata.name`	사용자의 이름

언어에 대한 심층적인 설명은 술어 언어 가이드를 참조하십시오.

Teleport 역할 참조

역할 명세 예시#

역할 옵션#

사전 설정 역할#

역할 버전#

kubernetes_resources의 기본값#

인프라 리소스에 대한 RBAC#

예시#

확장 레이블 매칭 구문#

레이블 표현식#

동적 Teleport 리소스에 대한 RBAC#

토큰 리소스에 대한 접근 허용#

세션 녹화에 대한 RBAC#

where 절 이해#

일반적인 접근 제어 레시피#

세션 참가자로 제한#

사용자 역할로 제한#

팀 Trait으로 제한#

세션 참가자로 제한#

리소스 유형으로 제한#

여러 조건 결합#

필터 필드#

사용자 필드#

세션 필드#

함수#

활성 세션에 대한 RBAC#

접근 요청#

접근 요청 생성#

접근 요청 검토#

클라이언트 옵션#

역할 템플릿#

인프라 리소스 접근을 위한 템플릿 표현식#

필드#

함수#

Traits#

Teleport 역할에서 내부 traits 참조#

Teleport 역할에서 외부 traits 참조#

기타 템플릿 변수#

접근 요청 템플릿 함수#

필드#

함수#

변수#

필터 필드#

역할 명세 예시#

역할 옵션#

사전 설정 역할#

역할 버전#

kubernetes_resources의 기본값#

인프라 리소스에 대한 RBAC#

예시#

확장 레이블 매칭 구문#

레이블 표현식#

동적 Teleport 리소스에 대한 RBAC#

토큰 리소스에 대한 접근 허용#

세션 녹화에 대한 RBAC#

where 절 이해#

일반적인 접근 제어 레시피#

세션 참가자로 제한#

사용자 역할로 제한#

팀 Trait으로 제한#

세션 참가자로 제한#

리소스 유형으로 제한#

여러 조건 결합#

필터 필드#

사용자 필드#

세션 필드#

함수#

활성 세션에 대한 RBAC#

접근 요청#

접근 요청 생성#

접근 요청 검토#

클라이언트 옵션#

역할 템플릿#

인프라 리소스 접근을 위한 템플릿 표현식#

필드#

함수#

Traits#

Teleport 역할에서 내부 traits 참조#

Teleport 역할에서 외부 traits 참조#

기타 템플릿 변수#

`kubernetes_resources`의 기본값#

`where` 절 이해#

`kubernetes_resources`의 기본값#

`where` 절 이해#