TeleportScopedRoleV1

Report an Issue

Is this page helpful?

How can we improve this page?

View as Markdown

This guide lists the fields in the TeleportScopedRoleV1 resource, which you can apply after installing the Teleport Kubernetes operator.

resources.teleport.dev/v1

apiVersion: resources.teleport.dev/v1

Field	Type	Description
apiVersion	string	APIVersion 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
kind	string	Kind 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
metadata	object
scope	string	Scope is the scope of the role resource.
spec	object	ScopedRole resource definition v1 from Teleport

spec

Field	Type	Description
app	object	The App Access specific configuration for a scoped role.
assignable_scopes	[]string	AssignableScopes is a list of scopes to which this role can be assigned. If empty, defaults to being assignable at resource scope and all descendants. Root scoped roles have no default and must specify assignable scopes explicitly.
defaults	object	Defaults specifies default values for controls common across multiple protocols. If the same control specified in defaults is also specified in a protocol block, the value in the protocol block takes precedence.
evaluation	object	Evaluation groups role-level settings that govern how a role is evaluated.
kube	object	The kubernetes specific configuration for a scoped role.
rules	[]object	Rules describes basic resource:verb permissions (e.g. scoped_role:read).
ssh	object	Ssh specifies controls that govern SSH access.
workload_identity	object	WorkloadIdentity specifies controls that govern issuance using WorkloadIdentity resources.

spec.app

Field	Type	Description
aws	object	AWS contains the AWS configuration for the scoped role.
client_idle_timeout	string	Overrides the defaults block idle timeout specifically for app sessions. Must be a valid Go duration string (e.g. "30m", "1h"). If empty, the defaults block value (or global default) applies.
disconnect_expired_cert	boolean	DisconnectExpiredCert controls whether App sessions are disconnected when the user certificate expires. If empty, the defaults block value (or global default) applies.
label_expression	string	LabelExpression is an optional predicate expression evaluated against an application's labels.
labels	[]object	The set of application labels used for RBAC.
lock	object	Lock configures the role's locking behavior for app sessions. If empty, the defaults block value (or global default) applies.
resources	[]object	Resources is a list of rules controlling access to an app's resources on each HTTP request. This version does not implement app.resources on scoped roles and rejects a scoped role that sets it to a non-empty list. An empty list is the same as leaving the field unset. The field is declared so that version skew or a rollback cannot silently drop it and widen a role's access.
resources_expressions	[]string	ResourcesExpressions is a list of predicates controlling access to an app's resources on each HTTP request. Every AppResource rule can be written as an expression, but not the reverse. This version does not implement app.resources_expressions on scoped roles and rejects a scoped role that sets it to a non-empty list. An empty list is the same as leaving the field unset. The field is declared so that version skew or a rollback cannot silently drop it and widen a role's access.

spec.app.aws

Field	Type	Description
role_arns	[]string	RoleArns specifies the AWS role ARNs to allow for this scoped app.

spec.app.labels items

Field	Type	Description
name	string	The name of the label.
values	[]string	The values associated with the label.

spec.app.lock

Field	Type	Description
mode	string	Allowed values: strict or best_effort. Defaults to value cluster wide auth preference if not set.

spec.app.resources items

Field	Type	Description
allow_all	boolean	AllowAll grants unrestricted access to every path and method. It cannot be combined with any other field.
allow_code	string	AllowCode is the code recorded on the allow audit event when the rule matches. If it is not set, no allow audit event is recorded. A code may not start with the reserved "teleport_" prefix.
allow_reason	string	AllowReason is the explanation recorded alongside AllowCode. A rule sets it only together with AllowCode.
allow_unsafe	object	AllowUnsafe lists options that can extend what the rule allows. They can be unsafe, so use them with care. For example: paths: ["/api/v4/projects/{project}/**"] allow_unsafe: {encoded: {project: "/"}} Set encoded only for an application that reads the encoded slash (%2F) as part of one path segment's content and does not auto-decode it to a literal /.
deny_code_hint	string	DenyCodeHint is the code added to the deny decision when the rule's path and method match but the Where predicate does not. A denied request collects a code from every such rule, so one decision can record several codes. A code may not start with the reserved "teleport_" prefix.
deny_reason_hint	string	DenyReasonHint is the explanation recorded alongside DenyCodeHint. A rule sets it only together with DenyCodeHint.
methods	[]string	Methods are the HTTP methods the rule matches, compared case-insensitively. A rule may list only GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS. An empty list matches any of them.
paths	[]string	Paths are the path patterns the rule matches, for example: paths: ["/api/projects/{project}/**"] The {project} segment is captured, and the rule's Where reads it as vars.project. A rule sets either Paths or AllowAll.
where	string	Where is a predicate over the caller identity and the rule's path captures, for example matching a captured project against a user's traits: where: contains(user.traits["projects"], vars.project)

spec.app.resources items.allow_unsafe

Field	Type	Description
encoded	object	Encoded maps a capture name to the characters a request path may contain in percent-encoded form inside that captured segment. The only supported value is "/", which allows the encoded slash (%2F or %2f).

spec.app.resources items.allow_unsafe.encoded

Field	Type	Description
key	string
value	string

spec.defaults

Field	Type	Description
client_idle_timeout	string	ClientIdleTimeout sets the default idle timeout for access sessions across all protocols that do not specify their own value. Must be a valid Go duration string (e.g. "30m", "1h"). The cluster-wide default is used only when neither this nor the protocol's equivalent control is set.
disconnect_expired_cert	boolean	DisconnectExpiredCert defines the default behavior of all protocols when certs expire for a session. The cluster-wide default is used only when neither this nor the protocol's equivalent control is set.
lock	object	Lock specifies the default locking mode for access sessions across all protocols that do not specify their own value. The cluster-wide default is used only when neither this nor the protocol's equivalent control is set.
session_recording	object	SessionRecording configures the session recording strategy for all protocols that don't explicitly set their session recording mode. If neither this nor the protocol's equivalent control is set, best_effort is used.

spec.defaults.lock

Field	Type	Description
mode	string	Allowed values: strict or best_effort. Defaults to value cluster wide auth preference if not set.

spec.defaults.session_recording

Field	Type	Description
mode	string	Mode sets the session recording mode. Allowed values: strict or best_effort.

spec.evaluation

Field	Type	Description
mode	string	Mode determines the evaluation mode of the role. Allowed values are 'inclusive' (default) and 'exclusive'. The default inclusive mode allows permissions from multiple matching roles to be combined. When a role is set to exclusive, the first matching role fully determines all permissions and controls for the access attempt. Inclusive is easier to manage day to day, but exclusive offers tighter control.

spec.kube

Field	Type	Description
client_idle_timeout	string	Overrides the defaults block idle timeout specifically for kube sessions. Must be a valid Go duration string (e.g. "30m", "1h"). If empty, the defaults block value (or global default) applies.
disconnect_expired_cert	boolean	DisconnectExpiredCert controls whether Kube sessions are disconnected when the user certificate expires. If empty, the defaults block value (or global default) applies.
groups	[]string	The list of kubernetes groups this role allows.
label_expression	string	LabelExpression is an optional predicate expression evaluated against a kubernetes server's labels.
labels	[]object	The map of kubernetes cluster labels used for RBAC.
lock	object	Lock configures the role's locking behavior for kubernetes sessions. If empty, the defaults block value (or global default) applies.
resources	[]object	The kubernetes resources this role grants access to.
users	[]string	An optional list of impersonatable kubernetes users this role allows.

spec.kube.labels items

Field	Type	Description
name	string	The name of the label.
values	[]string	The values associated with the label.

spec.kube.lock

Field	Type	Description
mode	string	Allowed values: strict or best_effort. Defaults to value cluster wide auth preference if not set.

spec.kube.resources items

Field	Type	Description
api_group	string	The kube API group of the kube resource. It supports wildcards.
kind	string	The kube resource type.
name	string	The kube resource name. It supports wildcards.
namespace	string	The kube resource namespace. It supports wildcards.
verbs	[]string	The allowed kube verbs for interacting with the kube resource.

spec.rules items

Field	Type	Description
resources	[]string	Resources is a list of resource kinds (e.g. 'scoped_token') that the below verbs apply to.
verbs	[]string	Verbs is the list of action verbs (e.g. 'read') that apply to the above resources.

spec.ssh

Field	Type	Description
client_idle_timeout	string	ClientIdleTimeout overrides the defaults block idle timeout specifically for SSH sessions. Must be a valid Go duration string (e.g. "30m", "1h"). If empty, the defaults block value (or global default) applies.
disconnect_expired_cert	boolean	DisconnectExpiredCert controls whether SSH sessions are disconnected when the user certificate expires. If empty, the defaults block value (or global default) applies.
enhanced_recording	object	EnhancedRecording is the set of BPF events to record for enhanced session recording.
file_copy	boolean	FileCopy indicates whether remote file operations via SCP or SFTP are allowed over an SSH session. If not set, remote file operations are not permitted.
forward_agent	boolean	ForwardAgent enables SSH agent forwarding.
host_sudoers	[]string	Sudoers is a list of entries to include in a users sudoer file
host_user_creation	object	HostUserCreation configures the creation of host users.
label_expression	string	LabelExpression is an optional predicate expression evaluated against an ssh node's labels.
labels	[]object	Labels is the set of node labels used to dynamically select which nodes this role applies to.
lock	object	Lock configures the role's locking behavior for SSH sessions. If empty, the defaults block value (or global default) applies.
logins	[]string	Logins is the list of OS logins this role permits on matching nodes.
max_sessions	integer	MaxSessions defines the maximum number of concurrent sessions per connection.
permit_x11_forwarding	boolean	PermitX11Forwarding, when true, authorizes use of X11 forwarding over SSH sessions. If not set, X11 forwarding is not permitted.
port_forwarding	object	SSHPortForwarding configures what types of SSH port forwarding are allowed by a role.
session_recording	object	SessionRecording configures the session recording strategy for SSH sessions.

spec.ssh.enhanced_recording

Field	Type	Description
command	boolean	Command enables session.command in audit logs
disk	boolean	Disk enables session.disk in audit logs
network	boolean	Network enables session.network in audit logs

spec.ssh.host_user_creation

Field	Type	Description
groups	[]string	Groups is a list of host groups to add the user to.
mode	string	Mode specifies how the host user should be created.
shell	string	Shell is the shell to set for the user.

spec.ssh.labels items

Field	Type	Description
name	string	The name of the label.
values	[]string	The values associated with the label.

spec.ssh.lock

Field	Type	Description
mode	string	Allowed values: strict or best_effort. Defaults to value cluster wide auth preference if not set.

spec.ssh.port_forwarding

Field	Type	Description
local	object	Allow for local port forwarding.
remote	object	Allow for remote port forwarding.

spec.ssh.port_forwarding.local

Field	Type	Description
enabled	boolean	Enabled, when true, authorizes local port forwarding. If not set, local port forwarding is not permitted.

spec.ssh.port_forwarding.remote

Field	Type	Description
enabled	boolean	Enabled, when true, authorizes remote port forwarding. If not set, remote port forwarding is not permitted.

spec.ssh.session_recording

Field	Type	Description
mode	string	Mode sets the session recording mode. Allowed values: strict or best_effort.

spec.workload_identity

Field	Type	Description
labels	[]object	Labels is the set of WorkloadIdentity labels used to dynamically select which WorkloadIdentity resources this role permits issuance with. Issuance additionally requires the caller to hold read_no_secrets (and, for the multi-issue RPC, list) rules for the workload_identity kind in the relevant scope.

spec.workload_identity.labels items

Field	Type	Description
name	string	The name of the label.
values	[]string	The values associated with the label.