2024 Secure Infrastructure Access Report: Key Insights and Trends
Oct 30
Virtual
Register Today
Teleport logoTry For Free
Fork me on GitHub

Teleport

TeleportRoleV7

This guide is a comprehensive reference to the fields in the TeleportRoleV7 resource, which you can apply after installing the Teleport Kubernetes operator.

resources.teleport.dev/v1

apiVersion: resources.teleport.dev/v1

FieldTypeDescription
apiVersionstringAPIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kindstringKind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadataobject
specobjectRole resource definition v7 from Teleport

spec

FieldTypeDescription
allowobjectAllow is the set of conditions evaluated to grant access.
denyobjectDeny is the set of conditions evaluated to deny access. Deny takes priority over allow.
optionsobjectOptions is for OpenSSH options like agent forwarding.

spec.allow

FieldTypeDescription
app_labelsobjectAppLabels is a map of labels used as part of the RBAC system.
app_labels_expressionstringAppLabelsExpression is a predicate expression used to allow/deny access to Apps.
aws_role_arns[]stringAWSRoleARNs is a list of AWS role ARNs this role is allowed to assume.
azure_identities[]stringAzureIdentities is a list of Azure identities this role is allowed to assume.
cluster_labelsobjectClusterLabels is a map of node labels (used to dynamically grant access to clusters).
cluster_labels_expressionstringClusterLabelsExpression is a predicate expression used to allow/deny access to remote Teleport clusters.
db_labelsobjectDatabaseLabels are used in RBAC system to allow/deny access to databases.
db_labels_expressionstringDatabaseLabelsExpression is a predicate expression used to allow/deny access to Databases.
db_names[]stringDatabaseNames is a list of database names this role is allowed to connect to.
db_permissions[]objectDatabasePermissions specifies a set of permissions that will be granted to the database user when using automatic database user provisioning.
db_roles[]stringDatabaseRoles is a list of databases roles for automatic user creation.
db_service_labelsobjectDatabaseServiceLabels are used in RBAC system to allow/deny access to Database Services.
db_service_labels_expressionstringDatabaseServiceLabelsExpression is a predicate expression used to allow/deny access to Database Services.
db_users[]stringDatabaseUsers is a list of databases users this role is allowed to connect as.
desktop_groups[]stringDesktopGroups is a list of groups for created desktop users to be added to
gcp_service_accounts[]stringGCPServiceAccounts is a list of GCP service accounts this role is allowed to assume.
group_labelsobjectGroupLabels is a map of labels used as part of the RBAC system.
group_labels_expressionstringGroupLabelsExpression is a predicate expression used to allow/deny access to user groups.
host_groups[]stringHostGroups is a list of groups for created users to be added to
host_sudoers[]stringHostSudoers is a list of entries to include in a users sudoer file
impersonateobjectImpersonate specifies what users and roles this role is allowed to impersonate by issuing certificates or other possible means.
join_sessions[]objectJoinSessions specifies policies to allow users to join other sessions.
kubernetes_groups[]stringKubeGroups is a list of kubernetes groups
kubernetes_labelsobjectKubernetesLabels is a map of kubernetes cluster labels used for RBAC.
kubernetes_labels_expressionstringKubernetesLabelsExpression is a predicate expression used to allow/deny access to kubernetes clusters.
kubernetes_resources[]objectKubernetesResources is the Kubernetes Resources this Role grants access to.
kubernetes_users[]stringKubeUsers is an optional kubernetes users to impersonate
logins[]stringLogins is a list of *nix system logins.
node_labelsobjectNodeLabels is a map of node labels (used to dynamically grant access to nodes).
node_labels_expressionstringNodeLabelsExpression is a predicate expression used to allow/deny access to SSH nodes.
requestobject
require_session_join[]objectRequireSessionJoin specifies policies for required users to start a session.
review_requestsobjectReviewRequests defines conditions for submitting access reviews.
rules[]objectRules is a list of rules and their access levels. Rules are a high level construct used for access control.
spiffe[]objectSPIFFE is used to allow or deny access to a role holder to generating a SPIFFE SVID.
windows_desktop_labelsobjectWindowsDesktopLabels are used in the RBAC system to allow/deny access to Windows desktops.
windows_desktop_labels_expressionstringWindowsDesktopLabelsExpression is a predicate expression used to allow/deny access to Windows desktops.
windows_desktop_logins[]stringWindowsDesktopLogins is a list of desktop login names allowed/denied for Windows desktops.

spec.allow.db_permissions items

FieldTypeDescription
matchobjectMatch is a list of object labels that must be matched for the permission to be granted.
permissions[]stringPermission is the list of string representations of the permission to be given, e.g. SELECT, INSERT, UPDATE, ...

spec.allow.impersonate

FieldTypeDescription
roles[]stringRoles is a list of resources this role is allowed to impersonate
users[]stringUsers is a list of resources this role is allowed to impersonate, could be an empty list or a Wildcard pattern
wherestringWhere specifies optional advanced matcher

spec.allow.join_sessions items

FieldTypeDescription
kinds[]stringKinds are the session kinds this policy applies to.
modes[]stringModes is a list of permitted participant modes for this policy.
namestringName is the name of the policy.
roles[]stringRoles is a list of roles that you can join the session of.

spec.allow.kubernetes_resources items

FieldTypeDescription
kindstringKind specifies the Kubernetes Resource type. At the moment only "pod" is supported.
namestringName is the resource name. It supports wildcards.
namespacestringNamespace is the resource namespace. It supports wildcards.
verbs[]stringVerbs are the allowed Kubernetes verbs for the following resource.

spec.allow.request

FieldTypeDescription
annotationsobjectAnnotations is a collection of annotations to be programmatically appended to pending Access Requests at the time of their creation. These annotations serve as a mechanism to propagate extra information to plugins. Since these annotations support variable interpolation syntax, they also offer a mechanism for forwarding claims from an external identity provider, to a plugin via {{external.trait_name}} style substitutions.
claims_to_roles[]objectClaimsToRoles specifies a mapping from claims (traits) to teleport roles.
max_durationstringMaxDuration is the amount of time the access will be granted for. If this is zero, the default duration is used.
roles[]stringRoles is the name of roles which will match the request rule.
search_as_roles[]stringSearchAsRoles is a list of extra roles which should apply to a user while they are searching for resources as part of a Resource Access Request, and defines the underlying roles which will be requested as part of any Resource Access Request.
suggested_reviewers[]stringSuggestedReviewers is a list of reviewer suggestions. These can be teleport usernames, but that is not a requirement.
thresholds[]objectThresholds is a list of thresholds, one of which must be met in order for reviews to trigger a state-transition. If no thresholds are provided, a default threshold of 1 for approval and denial is used.

spec.allow.request.claims_to_roles items

FieldTypeDescription
claimstringClaim is a claim name.
roles[]stringRoles is a list of static teleport roles to match.
valuestringValue is a claim value to match.

spec.allow.request.thresholds items

FieldTypeDescription
approveintegerApprove is the number of matching approvals needed for state-transition.
denyintegerDeny is the number of denials needed for state-transition.
filterstringFilter is an optional predicate used to determine which reviews count toward this threshold.
namestringName is the optional human-readable name of the threshold.

spec.allow.require_session_join items

FieldTypeDescription
countintegerCount is the amount of people that need to be matched for this policy to be fulfilled.
filterstringFilter is a predicate that determines what users count towards this policy.
kinds[]stringKinds are the session kinds this policy applies to.
modes[]stringModes is the list of modes that may be used to fulfill this policy.
namestringName is the name of the policy.
on_leavestringOnLeave is the behaviour that's used when the policy is no longer fulfilled for a live session.

spec.allow.review_requests

FieldTypeDescription
claims_to_roles[]objectClaimsToRoles specifies a mapping from claims (traits) to teleport roles.
preview_as_roles[]stringPreviewAsRoles is a list of extra roles which should apply to a reviewer while they are viewing a Resource Access Request for the purposes of viewing details such as the hostname and labels of requested resources.
roles[]stringRoles is the name of roles which may be reviewed.
wherestringWhere is an optional predicate which further limits which requests are reviewable.

spec.allow.review_requests.claims_to_roles items

FieldTypeDescription
claimstringClaim is a claim name.
roles[]stringRoles is a list of static teleport roles to match.
valuestringValue is a claim value to match.

spec.allow.rules items

FieldTypeDescription
actions[]stringActions specifies optional actions taken when this rule matches
resources[]stringResources is a list of resources
verbs[]stringVerbs is a list of verbs
wherestringWhere specifies optional advanced matcher

spec.allow.spiffe items

FieldTypeDescription
dns_sans[]stringDNSSANs specifies matchers for the SPIFFE ID DNS SANs. Each requested DNS SAN is compared against all matchers configured and if any match, the condition is considered to be met. The matcher by default allows '*' to be used to indicate zero or more of any character. Prepend '^' and append '$' to instead switch to matching using the Go regex syntax. Example: *.example.com would match foo.example.com
ip_sans[]stringIPSANs specifies matchers for the SPIFFE ID IP SANs. Each requested IP SAN is compared against all matchers configured and if any match, the condition is considered to be met. The matchers should be specified using CIDR notation, it supports IPv4 and IPv6. Examples: - 10.0.0.0/24 would match 10.0.0.0 to 10.255.255.255 - 10.0.0.42/32 would match only 10.0.0.42
pathstringPath specifies a matcher for the SPIFFE ID path. It should not include the trust domain and should start with a leading slash. The matcher by default allows '' to be used to indicate zero or more of any character. Prepend '^' and append '$' to instead switch to matching using the Go regex syntax. Example: - /svc/foo//bar would match /svc/foo/baz/bar - ^/svc/foo/.*/bar$ would match /svc/foo/baz/bar

spec.deny

FieldTypeDescription
app_labelsobjectAppLabels is a map of labels used as part of the RBAC system.
app_labels_expressionstringAppLabelsExpression is a predicate expression used to allow/deny access to Apps.
aws_role_arns[]stringAWSRoleARNs is a list of AWS role ARNs this role is allowed to assume.
azure_identities[]stringAzureIdentities is a list of Azure identities this role is allowed to assume.
cluster_labelsobjectClusterLabels is a map of node labels (used to dynamically grant access to clusters).
cluster_labels_expressionstringClusterLabelsExpression is a predicate expression used to allow/deny access to remote Teleport clusters.
db_labelsobjectDatabaseLabels are used in RBAC system to allow/deny access to databases.
db_labels_expressionstringDatabaseLabelsExpression is a predicate expression used to allow/deny access to Databases.
db_names[]stringDatabaseNames is a list of database names this role is allowed to connect to.
db_permissions[]objectDatabasePermissions specifies a set of permissions that will be granted to the database user when using automatic database user provisioning.
db_roles[]stringDatabaseRoles is a list of databases roles for automatic user creation.
db_service_labelsobjectDatabaseServiceLabels are used in RBAC system to allow/deny access to Database Services.
db_service_labels_expressionstringDatabaseServiceLabelsExpression is a predicate expression used to allow/deny access to Database Services.
db_users[]stringDatabaseUsers is a list of databases users this role is allowed to connect as.
desktop_groups[]stringDesktopGroups is a list of groups for created desktop users to be added to
gcp_service_accounts[]stringGCPServiceAccounts is a list of GCP service accounts this role is allowed to assume.
group_labelsobjectGroupLabels is a map of labels used as part of the RBAC system.
group_labels_expressionstringGroupLabelsExpression is a predicate expression used to allow/deny access to user groups.
host_groups[]stringHostGroups is a list of groups for created users to be added to
host_sudoers[]stringHostSudoers is a list of entries to include in a users sudoer file
impersonateobjectImpersonate specifies what users and roles this role is allowed to impersonate by issuing certificates or other possible means.
join_sessions[]objectJoinSessions specifies policies to allow users to join other sessions.
kubernetes_groups[]stringKubeGroups is a list of kubernetes groups
kubernetes_labelsobjectKubernetesLabels is a map of kubernetes cluster labels used for RBAC.
kubernetes_labels_expressionstringKubernetesLabelsExpression is a predicate expression used to allow/deny access to kubernetes clusters.
kubernetes_resources[]objectKubernetesResources is the Kubernetes Resources this Role grants access to.
kubernetes_users[]stringKubeUsers is an optional kubernetes users to impersonate
logins[]stringLogins is a list of *nix system logins.
node_labelsobjectNodeLabels is a map of node labels (used to dynamically grant access to nodes).
node_labels_expressionstringNodeLabelsExpression is a predicate expression used to allow/deny access to SSH nodes.
requestobject
require_session_join[]objectRequireSessionJoin specifies policies for required users to start a session.
review_requestsobjectReviewRequests defines conditions for submitting access reviews.
rules[]objectRules is a list of rules and their access levels. Rules are a high level construct used for access control.
spiffe[]objectSPIFFE is used to allow or deny access to a role holder to generating a SPIFFE SVID.
windows_desktop_labelsobjectWindowsDesktopLabels are used in the RBAC system to allow/deny access to Windows desktops.
windows_desktop_labels_expressionstringWindowsDesktopLabelsExpression is a predicate expression used to allow/deny access to Windows desktops.
windows_desktop_logins[]stringWindowsDesktopLogins is a list of desktop login names allowed/denied for Windows desktops.

spec.deny.db_permissions items

FieldTypeDescription
matchobjectMatch is a list of object labels that must be matched for the permission to be granted.
permissions[]stringPermission is the list of string representations of the permission to be given, e.g. SELECT, INSERT, UPDATE, ...

spec.deny.impersonate

FieldTypeDescription
roles[]stringRoles is a list of resources this role is allowed to impersonate
users[]stringUsers is a list of resources this role is allowed to impersonate, could be an empty list or a Wildcard pattern
wherestringWhere specifies optional advanced matcher

spec.deny.join_sessions items

FieldTypeDescription
kinds[]stringKinds are the session kinds this policy applies to.
modes[]stringModes is a list of permitted participant modes for this policy.
namestringName is the name of the policy.
roles[]stringRoles is a list of roles that you can join the session of.

spec.deny.kubernetes_resources items

FieldTypeDescription
kindstringKind specifies the Kubernetes Resource type. At the moment only "pod" is supported.
namestringName is the resource name. It supports wildcards.
namespacestringNamespace is the resource namespace. It supports wildcards.
verbs[]stringVerbs are the allowed Kubernetes verbs for the following resource.

spec.deny.request

FieldTypeDescription
annotationsobjectAnnotations is a collection of annotations to be programmatically appended to pending Access Requests at the time of their creation. These annotations serve as a mechanism to propagate extra information to plugins. Since these annotations support variable interpolation syntax, they also offer a mechanism for forwarding claims from an external identity provider, to a plugin via {{external.trait_name}} style substitutions.
claims_to_roles[]objectClaimsToRoles specifies a mapping from claims (traits) to teleport roles.
max_durationstringMaxDuration is the amount of time the access will be granted for. If this is zero, the default duration is used.
roles[]stringRoles is the name of roles which will match the request rule.
search_as_roles[]stringSearchAsRoles is a list of extra roles which should apply to a user while they are searching for resources as part of a Resource Access Request, and defines the underlying roles which will be requested as part of any Resource Access Request.
suggested_reviewers[]stringSuggestedReviewers is a list of reviewer suggestions. These can be teleport usernames, but that is not a requirement.
thresholds[]objectThresholds is a list of thresholds, one of which must be met in order for reviews to trigger a state-transition. If no thresholds are provided, a default threshold of 1 for approval and denial is used.

spec.deny.request.claims_to_roles items

FieldTypeDescription
claimstringClaim is a claim name.
roles[]stringRoles is a list of static teleport roles to match.
valuestringValue is a claim value to match.

spec.deny.request.thresholds items

FieldTypeDescription
approveintegerApprove is the number of matching approvals needed for state-transition.
denyintegerDeny is the number of denials needed for state-transition.
filterstringFilter is an optional predicate used to determine which reviews count toward this threshold.
namestringName is the optional human-readable name of the threshold.

spec.deny.require_session_join items

FieldTypeDescription
countintegerCount is the amount of people that need to be matched for this policy to be fulfilled.
filterstringFilter is a predicate that determines what users count towards this policy.
kinds[]stringKinds are the session kinds this policy applies to.
modes[]stringModes is the list of modes that may be used to fulfill this policy.
namestringName is the name of the policy.
on_leavestringOnLeave is the behaviour that's used when the policy is no longer fulfilled for a live session.

spec.deny.review_requests

FieldTypeDescription
claims_to_roles[]objectClaimsToRoles specifies a mapping from claims (traits) to teleport roles.
preview_as_roles[]stringPreviewAsRoles is a list of extra roles which should apply to a reviewer while they are viewing a Resource Access Request for the purposes of viewing details such as the hostname and labels of requested resources.
roles[]stringRoles is the name of roles which may be reviewed.
wherestringWhere is an optional predicate which further limits which requests are reviewable.

spec.deny.review_requests.claims_to_roles items

FieldTypeDescription
claimstringClaim is a claim name.
roles[]stringRoles is a list of static teleport roles to match.
valuestringValue is a claim value to match.

spec.deny.rules items

FieldTypeDescription
actions[]stringActions specifies optional actions taken when this rule matches
resources[]stringResources is a list of resources
verbs[]stringVerbs is a list of verbs
wherestringWhere specifies optional advanced matcher

spec.deny.spiffe items

FieldTypeDescription
dns_sans[]stringDNSSANs specifies matchers for the SPIFFE ID DNS SANs. Each requested DNS SAN is compared against all matchers configured and if any match, the condition is considered to be met. The matcher by default allows '*' to be used to indicate zero or more of any character. Prepend '^' and append '$' to instead switch to matching using the Go regex syntax. Example: *.example.com would match foo.example.com
ip_sans[]stringIPSANs specifies matchers for the SPIFFE ID IP SANs. Each requested IP SAN is compared against all matchers configured and if any match, the condition is considered to be met. The matchers should be specified using CIDR notation, it supports IPv4 and IPv6. Examples: - 10.0.0.0/24 would match 10.0.0.0 to 10.255.255.255 - 10.0.0.42/32 would match only 10.0.0.42
pathstringPath specifies a matcher for the SPIFFE ID path. It should not include the trust domain and should start with a leading slash. The matcher by default allows '' to be used to indicate zero or more of any character. Prepend '^' and append '$' to instead switch to matching using the Go regex syntax. Example: - /svc/foo//bar would match /svc/foo/baz/bar - ^/svc/foo/.*/bar$ would match /svc/foo/baz/bar

spec.options

FieldTypeDescription
cert_extensions[]objectCertExtensions specifies the key/values
cert_formatstringCertificateFormat defines the format of the user certificate to allow compatibility with older versions of OpenSSH.
client_idle_timeoutstringClientIdleTimeout sets disconnect clients on idle timeout behavior, if set to 0 means do not disconnect, otherwise is set to the idle duration.
create_db_userbooleanCreateDatabaseUser enabled automatic database user creation.
create_db_user_modestring or integerCreateDatabaseUserMode allows users to be automatically created on a database when not set to off. 0 is "unspecified", 1 is "off", 2 is "keep", 3 is "best_effort_drop". Can be either the string or the integer representation of each option.
create_desktop_userbooleanCreateDesktopUser allows users to be automatically created on a Windows desktop
create_host_userbooleanCreateHostUser allows users to be automatically created on a host
create_host_user_default_shellstringCreateHostUserDefaultShell is used to configure the default shell for newly provisioned host users.
create_host_user_modestring or integerCreateHostUserMode allows users to be automatically created on a host when not set to off. 0 is "unspecified"; 1 is "off"; 2 is "drop" (removed for v15 and above), 3 is "keep"; 4 is "insecure-drop". Can be either the string or the integer representation of each option.
desktop_clipboardbooleanDesktopClipboard indicates whether clipboard sharing is allowed between the user's workstation and the remote desktop. It defaults to true unless explicitly set to false.
desktop_directory_sharingbooleanDesktopDirectorySharing indicates whether directory sharing is allowed between the user's workstation and the remote desktop. It defaults to false unless explicitly set to true.
device_trust_modestringDeviceTrustMode is the device authorization mode used for the resources associated with the role. See DeviceTrust.Mode.
disconnect_expired_certbooleanDisconnectExpiredCert sets disconnect clients on expired certificates.
enhanced_recording[]stringBPF defines what events to record for the BPF-based session recorder.
forward_agentbooleanForwardAgent is SSH agent forwarding.
idpobjectIDP is a set of options related to accessing IdPs within Teleport. Requires Teleport Enterprise.
lockstringLock specifies the locking mode (strict
max_connectionsintegerMaxConnections defines the maximum number of concurrent connections a user may hold.
max_kubernetes_connectionsintegerMaxKubernetesConnections defines the maximum number of concurrent Kubernetes sessions a user may hold.
max_session_ttlstringMaxSessionTTL defines how long a SSH session can last for.
max_sessionsintegerMaxSessions defines the maximum number of concurrent sessions per connection.
mfa_verification_intervalstringMFAVerificationInterval 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. It's only effective if the session requires MFA. If not set, defaults to max_session_ttl.
permit_x11_forwardingbooleanPermitX11Forwarding authorizes use of X11 forwarding.
pin_source_ipbooleanPinSourceIP forces the same client IP for certificate generation and usage
port_forwardingbooleanPortForwarding defines if the certificate will have "permit-port-forwarding" in the certificate. PortForwarding is "yes" if not set, that's why this is a pointer
record_sessionobjectRecordDesktopSession indicates whether desktop access sessions should be recorded. It defaults to true unless explicitly set to false.
request_accessstringRequestAccess defines the request strategy (optional
request_promptstringRequestPrompt is an optional message which tells users what they aught to request.
require_session_mfastring or integerRequireMFAType is the type of MFA requirement enforced for this user. 0 is "OFF", 1 is "SESSION", 2 is "SESSION_AND_HARDWARE_KEY", 3 is "HARDWARE_KEY_TOUCH", 4 is "HARDWARE_KEY_PIN", 5 is "HARDWARE_KEY_TOUCH_AND_PIN". Can be either the string or the integer representation of each option.
ssh_file_copybooleanSSHFileCopy indicates whether remote file operations via SCP or SFTP are allowed over an SSH session. It defaults to true unless explicitly set to false.

spec.options.cert_extensions items

FieldTypeDescription
modestring or integerMode is the type of extension to be used -- currently critical-option is not supported. 0 is "extension". Can be either the string or the integer representation of each option.
namestringName specifies the key to be used in the cert extension.
typestring or integerType represents the certificate type being extended, only ssh is supported at this time. 0 is "ssh". Can be either the string or the integer representation of each option.
valuestringValue specifies the value to be used in the cert extension.

spec.options.idp

FieldTypeDescription
samlobjectSAML are options related to the Teleport SAML IdP.

spec.options.idp.saml

FieldTypeDescription
enabledbooleanEnabled is set to true if this option allows access to the Teleport SAML IdP.

spec.options.record_session

FieldTypeDescription
defaultstringDefault indicates the default value for the services.
desktopbooleanDesktop indicates whether desktop sessions should be recorded. It defaults to true unless explicitly set to false.
sshstringSSH indicates the session mode used on SSH sessions.