mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-02 23:31:08 +08:00
Alex McGrath
65459e872e
* dont allow disabling second factor * update docs for 2fa change * add environmental variable to work around disabled 2fa * check if its cloud * update todos * add a test * introduce insecure test mode * fixes for tests
312 lines
15 KiB
Plaintext
312 lines
15 KiB
Plaintext
---
|
|
title: Teleport Resource Reference
|
|
description: Reference documentation for Teleport resources
|
|
---
|
|
|
|
This reference guide lists dynamic resources you can manage with Teleport. For
|
|
more information on dynamic resources, see our guide to [Using Dynamic
|
|
Resources](../management/dynamic-resources.mdx).
|
|
|
|
Examples of applying dynamic resources with `tctl`:
|
|
|
|
```code
|
|
# List all connectors:
|
|
$ tctl get connectors
|
|
|
|
# Dump a SAML connector called "okta":
|
|
$ tctl get saml/okta
|
|
|
|
# Delete a SAML connector called "okta":
|
|
$ tctl rm saml/okta
|
|
|
|
# Delete an OIDC connector called "gworkspace":
|
|
$ tctl rm oidc/gworkspace
|
|
|
|
# Delete a github connector called "myteam":
|
|
$ tctl rm github/myteam
|
|
|
|
# Delete a local user called "admin":
|
|
$ tctl rm users/admin
|
|
|
|
# Show all devices:
|
|
$ tctl get devices
|
|
|
|
# Fetch a specific device:
|
|
$ tctl get devices/<asset-tag>
|
|
|
|
# Fetch the cluster auth preferences
|
|
$ tctl get cluster_auth_preference
|
|
```
|
|
|
|
<Admonition type="note">
|
|
Although `tctl get connectors` will show you every connector, when working with an individual connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each connector's `kind` at the top of its YAML output from `tctl get connectors`.
|
|
</Admonition>
|
|
|
|
## List of dynamic resources
|
|
|
|
Here's the list of resources currently exposed via [`tctl`](./cli/tctl.mdx):
|
|
|
|
| Resource Kind | Description |
|
|
| - | - |
|
|
| [user](#user) | A user record in the internal Teleport user DB. |
|
|
| [role](#role) | A role assumed by interactive and non-interactive users. |
|
|
| connector | Authentication connectors for [Single Sign-On](../access-controls/sso.mdx) (SSO) for SAML, OIDC and GitHub. |
|
|
| node | A registered SSH node. The same record is displayed via `tctl nodes ls` |
|
|
| windows_desktop | A registered Windows desktop. |
|
|
| cluster | A trusted cluster. See [here](../management/admin/trustedclusters.mdx) for more details on connecting clusters together. |
|
|
| [login_rule](#login-rules) | A Login Rule, see the [Login Rules guide](../access-controls/login-rules.mdx) for more info. |
|
|
| [device](#device) | A Teleport Trusted Device, see the [Device Trust guide](../access-controls/device-trust/guide.mdx) for more info. |
|
|
| [ui_config](#ui-config) | Configuration for the Web UI served by the Proxy Service |
|
|
| [cluster_auth_preference](#cluster-auth-preferences) | Configuration for the cluster's auth preferences. |
|
|
| [database_object_import_rule](#database-object-import-rule) | Database object import rules. |
|
|
|
|
## User
|
|
|
|
Teleport supports interactive local users, non-interactive local users (bots)
|
|
and single-sign on users that are represented as a resource.
|
|
|
|
```yaml
|
|
kind: user
|
|
version: v2
|
|
metadata:
|
|
name: joe
|
|
spec:
|
|
# roles is a list of roles assigned to this user
|
|
roles:
|
|
- admin
|
|
# status sets user temporarily locked in a Teleport system, for example
|
|
# when users exceed predefined amount of failed login attempts
|
|
status:
|
|
is_locked: false
|
|
lock_expires: 0001-01-01T00:00:00Z
|
|
locked_time: 0001-01-01T00:00:00Z
|
|
# traits are key, list of values pairs assigned to a user resource.
|
|
# Traits can be used in role templates as variables.
|
|
traits:
|
|
logins:
|
|
- joe
|
|
- root
|
|
# expires, if not empty, sets automatic expiry of the resource
|
|
expires: 0001-01-01T00:00:00Z
|
|
# created_by is a system property that tracks
|
|
# identity of the author of this user resource.
|
|
created_by:
|
|
time: 0001-01-01T00:00:00Z
|
|
user:
|
|
name: builtin-Admin
|
|
```
|
|
|
|
## Role
|
|
|
|
Interactive and non-interactive users (bots) assume one or many roles.
|
|
|
|
Roles govern access to databases, SSH servers, Kubernetes clusters, web services and applications and Windows Desktops.
|
|
|
|
(!docs/pages/includes/role-spec.mdx!)
|
|
|
|
### Role versions
|
|
|
|
Versions 5, 6 and 7 of the Teleport role resource have different behaviors when
|
|
accessing Kubernetes resources.
|
|
{/*lint ignore messaging*/}
|
|
Roles not [granting Kubernetes access](../kubernetes-access/introduction.mdx) are
|
|
equivalent in the three versions.
|
|
|
|
Roles v5 and v6 can only restrict actions on pods (e.g. executing in them).
|
|
Role v7 supports restricting all common resource kinds (
|
|
see [the `kubernetes_resource` documentation](../kubernetes-access/controls.mdx#kubernetes_resources)
|
|
for a complete list).
|
|
|
|
When no `kubernetes_resource` is set:
|
|
- Roles v5 and v7 grant all access by default
|
|
- Roles v6 blocks pod execution by default, this was reverted by roles v7 to improve the user experience.
|
|
|
|
{/* This table is cursed. Our current docs engine doesn't support HTML tables
|
|
(due to SSR and the rehydration process). We have dto do everything inlined in
|
|
markdown. Some HTML character codes are used to render specific chars like {}
|
|
or to avoid line breaks in the middle fo the YAML. Whitespaces before br tags
|
|
are required.*/}
|
|
|
|
| Allow rule | Role v5 | Role v6 | Role v7 |
|
|
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| <pre>kubernetes_groups: <br/> - "system:masters" <br/>kubernetes_labels: {} <br/>kubernetes_resources: []<br/></pre> | ❌ no access | ❌ no access | ❌ no access |
|
|
| <pre>kubernetes_groups: <br/> - "system:masters" <br/>kubernetes_labels: <br/> env: ["dev"] <br/>kubernetes_resources: []<br/></pre> | ✅ full access to `dev` clusters | ❌ cannot exec in pods <br/> ✅ can access other <br/>resources like `secrets` | ✅ full access to `dev` clusters |
|
|
| <pre>kubernetes_groups: <br/> - "system:masters" <br/>kubernetes_labels: <br/> env: ["dev"] <br/>kubernetes_resources: <br/> - name: "*" <br/> kind: pod <br/> namespace: "foo"</pre> | ✅ can exec in pods in `foo` <br/>✅ can access `secrets` in all namespaces. <br/>❌ cannot exec in other namespaces | ✅ can exec in pods in `foo` <br/>✅ can access `secrets` in all namespaces. <br/>❌ cannot exec in other namespaces | ✅ can exec in pods in `foo` <br/>❌ cannot access `secrets` in all namespaces <br/>❌ cannot exec in other namespaces |
|
|
| <pre>kubernetes_groups: <br/> - "system:masters" <br/>kubernetes_labels: <br/> env: ["dev"] <br/>kubernetes_resources: <br/> - name: "*" <br/> kind: pod <br/> namespace: "foo" <br/> - name: "*" <br/> kind: secret <br/> namespace: "foo"</pre> | ⚠️ not supported | ⚠️ not supported | ✅ can exec in pods in `foo` <br/>✅ can access `secrets` in `foo` <br/>❌ cannot exec in other namespaces <br/>❌ cannot access `secrets` in other namespaces <br/>❌ cannot access `configmaps` in `foo` |
|
|
| <pre>kubernetes_groups: <br/> - "system:masters" <br/>kubernetes_labels: <br/> env: ["dev"] <br/>kubernetes_resources: <br/> - kind: "namespace" <br/> name: "foo"</pre> | ⚠️ not supported | ⚠️ not supported | ✅ full access in namespace `foo` <br/>❌ cannot access other namespaces |
|
|
|
|
|
|
## Windows desktop
|
|
|
|
In most cases, Teleport will register `windows_desktop` resources automatically
|
|
based on static hosts in your configuration file or via LDAP-based discovery.
|
|
|
|
However, you can also manage `windows_desktop` resources manually with `tctl`.
|
|
This can be useful for managing inventories of hosts that are not joined to
|
|
an Active Directory domain.
|
|
|
|
There are a few important considerations to keep in mind when registering
|
|
desktops this way:
|
|
|
|
1. The desktop's `addr` can be a hostname or IP address, and should include
|
|
the RDP port (typically 3389).
|
|
1. The desktop's `host_id` should be set to the name of a
|
|
`windows_desktop_service` that is capable of proxying remote desktop
|
|
connections to the host. If you have multiple such services, you can create
|
|
multiple `windows_desktop` resources with different `host_id` values.
|
|
1. If you intend to log in to the desktop with local Windows users you must set
|
|
`non_ad: true`. If you intend to log in with Active Directory users, leave
|
|
`non_ad` unset (or false), and specify the Active Directory domain in the
|
|
`domain` field.
|
|
|
|
```yaml
|
|
kind: windows_desktop
|
|
metadata:
|
|
name: desktop-without-ad
|
|
labels:
|
|
foo: bar
|
|
baz: quux
|
|
spec:
|
|
host_id: 307e091b-7f6b-42e0-b78d-3362ad10b55d
|
|
addr: 192.168.1.153:3389
|
|
domain: ""
|
|
non_ad: true
|
|
|
|
# Optional - ensures that all sessions use the same screen size,
|
|
# no matter what the size of the browser window is.
|
|
# Leave blank to use the size of the browser window.
|
|
screen_size:
|
|
width: 1024
|
|
height: 768
|
|
version: v3
|
|
```
|
|
|
|
## Login Rules
|
|
|
|
Login rules contain logic to transform SSO user traits during login.
|
|
|
|
(!docs/pages/includes/login-rule-spec.mdx!)
|
|
|
|
## Database object import rule
|
|
|
|
Database object import rule define the labels to be applied to database objects imported into Teleport.
|
|
|
|
See [Database Access Controls](../database-access/auto-user-provisioning/database-access-controls.mdx) for more details.
|
|
|
|
(!docs/pages/includes/database-access/auto-user-provisioning/database-object-import-rule-spec.mdx!)
|
|
|
|
## Device
|
|
|
|
Device contains information identifying a trusted device.
|
|
|
|
(!docs/pages/includes/device-spec.mdx!)
|
|
|
|
## UI config
|
|
|
|
Global configuration options for the Web UI served by the Proxy Service. This resource is not set by default, which means a `tctl get ui` will result in an error if used before this resource has been set.
|
|
|
|
(!docs/pages/includes/ui-config-spec.mdx!)
|
|
|
|
## Cluster maintenance config
|
|
|
|
Global configuration options for the agents enrolled into automatic updates.
|
|
|
|
(!docs/pages/includes/cluster-maintenance-config-spec.mdx!)
|
|
|
|
## Cluster auth preferences
|
|
|
|
Global cluster configuration options for authentication.
|
|
|
|
```yaml
|
|
metadata:
|
|
name: cluster-auth-preference
|
|
spec:
|
|
# Sets the type of second factor to use.
|
|
# Possible values: "on", "otp" and "webauthn"
|
|
# If "on" is set, all MFA protocols are supported.
|
|
second_factor: "otp"
|
|
|
|
# The name of the OIDC or SAML connector. if this is not set, the first connector in the backend is used.
|
|
connector_name: ""
|
|
|
|
# webauthn is the settings for server-side Web authentication support.
|
|
webauthn:
|
|
# rp_id is the ID of the Relying Party.
|
|
# It should be set to the domain name of the Teleport installation.
|
|
#
|
|
# IMPORTANT: rp_id must never change in the lifetime of the cluster, because
|
|
# it's recorded in the registration data on the WebAuthn device. If the
|
|
# ri_id changes, all existing WebAuthn key registrations will become invalid
|
|
# and all users who use WebAuthn as the second factor will need to
|
|
# re-register.
|
|
rp_id: teleport.example.com
|
|
# Allow list of device attestation CAs in PEM format.
|
|
# If present, only devices whose attestation certificates match the
|
|
# certificates specified here may be registered (existing registrations are
|
|
# unchanged).
|
|
# If supplied in conjunction with `attestation_denied_cas`, then both
|
|
# conditions need to be true for registration to be allowed (the device
|
|
# MUST match an allowed CA and MUST NOT match a denied CA).
|
|
# By default all devices are allowed.
|
|
attestation_allowed_cas: []
|
|
# Deny list of device attestation CAs in PEM format.
|
|
# If present, only devices whose attestation certificates don't match the
|
|
# certificates specified here may be registered (existing registrations are
|
|
# unchanged).
|
|
attestation_denied_cas: []
|
|
|
|
# Enforce per-session MFA or PIV-hardware key restrictions on user login sessions.
|
|
# Possible values: true, false, "hardware_key", "hardware_key_touch".
|
|
# Defaults to false.
|
|
require_session_mfa: false
|
|
|
|
# Sets whether connections with expired client certificates will be disconnected.
|
|
disconnect_expired_cert: false
|
|
|
|
# Sets whether headless authentication is allowed.
|
|
# Headless authentication requires WebAuthn.
|
|
# Defaults to true if webauthn is configured.
|
|
allow_headless: false
|
|
|
|
# Sets whether local auth is enabled alongside any other authentication
|
|
# type.
|
|
allow_local_auth: true
|
|
|
|
# Sets whether passwordless authentication is allowed.
|
|
# Requires Webauthn to work.
|
|
allow_passwordless: false
|
|
|
|
# Sets the message of the day for the cluster.
|
|
message_of_the_day: ""
|
|
|
|
# idp is a set of options related to accessing IdPs within Teleport. Requires Teleport Enterprise
|
|
idp:
|
|
# options related to the Teleport SAML IdP.
|
|
saml:
|
|
# enables access to the Teleport SAML IdP.
|
|
enabled: true
|
|
|
|
# locking_mode is the cluster-wide locking mode default.
|
|
# Possible values: "strict" or "best_effort"
|
|
locking_mode: best_effort
|
|
|
|
# default_session_ttl defines the default TTL (time to live) of certificates
|
|
# issued to the users on this cluster.
|
|
default_session_ttl: "12h"
|
|
|
|
# The type of authentication to use for this cluster.
|
|
# Possible values: "local", "oidc", "saml" and "github"
|
|
type: local
|
|
|
|
version: v2
|
|
```
|
|
|
|
## Bot
|
|
|
|
Bot resources define a Machine ID Bot identity and its access.
|
|
|
|
Find out more on the
|
|
[Machine ID configuration reference](../machine-id/reference/configuration.mdx).
|
|
|
|
(!docs/pages/includes/machine-id/bot-spec.mdx!)
|