diff --git a/docs/config.json b/docs/config.json index f3c30ec8ec388..25f53a4460447 100644 --- a/docs/config.json +++ b/docs/config.json @@ -365,7 +365,8 @@ "first": "abcd123-insecure-do-not-use-this", "second": "efgh456-insecure-do-not-use-this", "third": "ijkl789-insecure-do-not-use-this" - } + }, + "ca_pin": "sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678" }, "fedramp": { "control_url": "https://csrc.nist.gov/Projects/risk-management/sp800-53-controls/release-search#!/control?version=5.1&number=" diff --git a/docs/img/github-sso-auth-screen.jpg b/docs/img/github-sso-auth-screen.jpg new file mode 100644 index 0000000000000..091ef5387e726 Binary files /dev/null and b/docs/img/github-sso-auth-screen.jpg differ diff --git a/docs/img/login-success.jpg b/docs/img/login-success.jpg new file mode 100644 index 0000000000000..906e0ccbfd83e Binary files /dev/null and b/docs/img/login-success.jpg differ diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx index 10b8d7c3e6bf2..1010e125dfb43 100644 --- a/docs/pages/access-controls/getting-started.mdx +++ b/docs/pages/access-controls/getting-started.mdx @@ -3,13 +3,12 @@ title: Getting Started With Access Controls description: Get started using Teleport Access Controls. --- -# Getting Started +In Teleport, any local, SSO, or robot user can assigned one or several roles. +Roles govern access to databases, SSH servers, Kubernetes clusters, Windows +desktops, and web apps. -In Teleport, any local, SSO, or robot user can be a member of one or several -roles. Roles govern access to databases, SSH servers, kubernetes clusters, and web apps. - -We will start with local users and preset roles, map SSO users to roles and wrap up -with creating your own role. +We will start with local users and preset roles, assign roles to SSO users, and +wrap up with creating your own role. ## Prerequisites @@ -26,7 +25,7 @@ Members of the `editor` role can modify cluster configuration, members of `audit role can view audit logs, and `access` members can access cluster resources. Members of `admin`, are full cluster administrators. -Invite a local user Alice as cluster `editor`: +Invite the local user Alice as cluster `editor`: ```code $ tctl users add alice --roles=editor @@ -44,27 +43,28 @@ $ tctl users ls # admin@example.com admin ``` -{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */} - -You can update user's roles using `tctl users update` command: +You can update the user's roles using the `tctl users update` command: ```code # Once Alice logs back in, she will be able to view audit logs $ tctl users update alice --set-roles=editor,auditor ``` -Because Alice has two roles, permissions from those roles create a union - -she will be able to act as a system administrator and auditor at the same time. +Because Alice has two roles, permissions from those roles create a union. She +will be able to act as a system administrator and auditor at the same time. ## Step 2/3. Map SSO users to roles -We're now going to set up a GitHub connector for Teleport Open Source Edition and Okta for Teleport Enterprise Edition. +Next, follow the instructions to set up an authentication connector that maps +users within your SSO solution to Teleport roles. - - - Save the file below as `github.yaml` and update the fields. You will need to set up - [Github OAuth 2.0 Connector](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) app. - Any member belonging to the Github organization `octocats` and on team `admin` will be able to assume a built-in role `access`. + + + Save the file below as `github.yaml` and update the fields. You will need to + set up a + [GitHub OAuth 2.0 Connector](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) + app. Any member belonging to the GitHub organization `octocats` and on team + `admin` will be able to assume the built-in role `access`. ```yaml kind: github @@ -73,44 +73,88 @@ We're now going to set up a GitHub connector for Teleport Open Source Edition an # connector name that will be used with `tsh --auth=github login` name: github spec: - # client ID of Github OAuth app + # client ID of GitHub OAuth app client_id: client-id - # client secret of Github OAuth app + # client secret of GitHub OAuth app client_secret: client-secret # This name will be shown on UI login screen - display: Github + display: GitHub # Change tele.example.com to your domain name redirect_url: https://tele.example.com:443/v1/webapi/github/callback # Map github teams to teleport roles teams_to_logins: - - organization: octocats # Github organization name - team: admin # Github team name within that organization + - organization: octocats # GitHub organization name + team: admin # GitHub team name within that organization # map github admin team to Teleport's "access" role logins: ["access"] ``` - - - Follow [SAML Okta Guide](../enterprise/sso/okta.mdx#configure-okta) to create a SAML app. - Check out [OIDC guides](../enterprise/sso/oidc.mdx#identity-providers) for OpenID Connect apps. - Save the file below as `okta.yaml` and update the `acs` field. - Any member in Okta group `okta-admin` will assume a built-in role `admin`. + Create the `github` resource: - ```yaml - kind: saml - version: v2 - metadata: - name: okta - spec: - acs: https://tele.example.com/v1/webapi/saml/acs - attributes_to_roles: - - {name: "groups", value: "okta-admin", roles: ["access"]} - entity_descriptor: | - + + + + Create a SAML or OIDC application that Teleport can integrate with, then + create an authentication connector that maps users within your application to + Teleport roles. + + + + + Follow our [SAML Okta Guide](../enterprise/sso/okta.mdx#configure-okta) to + create a SAML application. + + Save the file below as `okta.yaml` and update the `acs` field. + Any member in Okta group `okta-admin` will assume a built-in role `admin`. + + ```yaml + kind: saml + version: v2 + metadata: + name: okta + spec: + acs: https://tele.example.com/v1/webapi/saml/acs + attributes_to_roles: + - {name: "groups", value: "okta-admin", roles: ["access"]} + entity_descriptor: | + - + + + Follow our [OIDC guides](../enterprise/sso/oidc.mdx#identity-providers) to + create an OIDC application. + + Copy the YAML below to a file called `oidc.yaml` and edit the information to + include the details of your OIDC application. + + ```yaml + (!examples/resources/oidc-connector.yaml!) + ``` + + Create the `oidc` resource: + + ```code + $ tctl create okta.yaml + ``` + + + + + ## Step 3/3. Create a custom role @@ -129,9 +173,10 @@ spec: allow: # Logins configures SSH login principals logins: ['readonly'] - # Assigns members of this role to built-in kubernetes group view + # Assigns users with this role to the built-in Kubernetes group "view" kubernetes_groups: ["view"] - # Allow access to SSH nodes, kubernetes clusters, apps or databases labeled with staging or test + # Allow access to SSH nodes, Kubernetes clusters, apps or databases + # labeled with "staging" or "test" node_labels: 'env': ['staging', 'test'] kubernetes_labels: @@ -140,7 +185,7 @@ spec: 'type': ['monitoring'] # The deny rules always override allow rules. deny: - # deny access to any node, database, app or kubernetes cluster labeled + # deny access to any Node, database, app or Kubernetes cluster labeled # as prod as any user. node_labels: 'env': 'prod' @@ -152,7 +197,7 @@ spec: 'env': 'prod' ``` -Create a role using `tctl create -f` command: +Create a role using the `tctl create -f` command: ```code $ tctl create -f /tmp/interns.yaml diff --git a/docs/pages/access-controls/guides/locking.mdx b/docs/pages/access-controls/guides/locking.mdx index 9e7ff205fb339..1f16ccd76aa3e 100644 --- a/docs/pages/access-controls/guides/locking.mdx +++ b/docs/pages/access-controls/guides/locking.mdx @@ -26,6 +26,25 @@ A lock can target the following objects or attributes: deployment. +System administrators can disable a compromised user or node—or +prevent access during cluster maintenance—by placing a lock +on a session, user or host identity. + +Teleport will reject new API requests and terminate active +connections to SSH, database, desktop, and Kubernetes sessions +matching the lock's target. + +A lock can target the following objects or attributes: + +- a Teleport user by the user's name +- a Teleport [RBAC](../reference.mdx) role by the role's name +- an MFA device by the device's UUID +- an OS/UNIX login +- a Teleport node by the node's UUID (effectively unregistering it from the + cluster) +- a Windows desktop by the desktop's name +- an [Access Request](../../enterprise/workflow/index.mdx) by UUID + ## Prerequisites (!docs/pages/includes/edition-prereqs-tabs.mdx!) @@ -34,15 +53,109 @@ A lock can target the following objects or attributes: ## Creating a new lock -Locks are modeled as [resources](../../setup/reference/resources.mdx) with `kind: -lock`. To create a new lock, one can run the `tctl lock` command: +You can create a new lock with the `tctl lock` command. Specify the lock target +with one of the following options: + + + + ```code + $ tctl lock --user=foo@example.com --message="Suspicious activity." --ttl=10h + # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". + ``` + + + All users with assigned roles matching the target role will be locked. + ```code + $ tctl lock --role=contractor --message="All contractor access is disabled for 10h." --ttl=10h + # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". + ``` + + + All connections initated with per-session MFA matching the device ID will be locked. + ```code + $ tctl lock --mfa-device=d6c06a18-e147-4232-9dfe-6f83a28d5850 --message="All contractor access is disabled for 10h." --ttl=10h + # Created a lock with name "d6c06a18-e147-4232-9dfe-6f83a28d5850". + ``` + + + All connections to the specified node will be locked. + ```code + $ tctl lock --node=363256df-f78a-4d99-803c-bae19da9ede4 --message="The node is under investigation." --ttl=10h + # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". + ``` + + + All connections to the specified Windows Desktop will be locked. + ```code + $ tctl lock --windows-desktop=WIN-FMPFM5UF1SS-teleport-example-com --ttl=10h + # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". + ``` + + + All connections using elevated privileges from the matching access request will be locked. + ```code + $ tctl lock --access-request=261e80c5-357b-4c43-9b67-40a6bc4c6e4d --ttl=24h + # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". + ``` + + + +
+ +If your user is missing a lock permission, you will get error when creating +a role: + +```txt +ERROR: access denied to perform action "create" on "lock" +``` + +Create a role `locksmith`: + +```yaml +kind: role +version: v5 +metadata: + name: locksmith +spec: + allow: + rules: + - resources: [lock] + verbs: [list, create, read, update, delete] +``` ```code $ tctl lock --user=foo@example.com --message="Suspicious activity." --ttl=10h # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". ``` -Note that without specifying `--ttl` or `--expires` the created lock remains in +And assign this role to a user. The user must log in again for this role to take +effect. + +
+ +With a lock in force, all established connections involving the lock's target +get terminated while any new requests are rejected. + +Errors returned and warnings logged in this situation feature a message of the +form: +``` +lock targeting User:"foo@example.com" is in force: Suspicious activity. +``` + + +You can tweak the message returned to a user with `--message` parameter: + +```code +$ tctl lock --user=foo@example.com --message="Please come back tomorrow." --ttl=24h +``` + + +
+ +Note that without specifying `--ttl` or `--expires`, the created lock remains in force until explicitly removed with `tctl rm`. Refer to `tctl lock --help` for the list of all supported parameters. @@ -61,9 +174,11 @@ spec: ``` The `kind: lock` resources can also be created and updated using `tctl create` -as per usual, see the [Admin Guide](../../setup/reference/resources.mdx) for more +as per usual. See the [Admin Guide](../../setup/reference/resources.mdx) for more details. +
+ ## Lock in force With a lock in force, all established connections involving the lock's target @@ -77,21 +192,25 @@ lock targeting User:"foo@example.com" is in force: Suspicious activity. ## Locking mode -If a Teleport node or proxy cannot properly synchronize its local lock view -with the backend, there is a decision to be made about whether to rely on the -last known locks. This decision strategy is encoded as one of the two modes: +If a Teleport node or Proxy Service cannot properly synchronize its local lock +view with the backend, there is a decision to be made about whether to rely on +the last known locks. This decision strategy is encoded as one of the two modes: - `strict` mode causes all interactions to be terminated when the locks are not guaranteed to be up to date; - `best_effort` mode keeps relying on the most recent locks. -The cluster-wide mode defaults to `best_effort`. -You can set up default locking mode via API or CLI using resource `cluster_auth_preference` -or static configuration file: + + +The cluster-wide mode defaults to `best_effort`. You can set up the default +locking mode via API or CLI using a `cluster_auth_preference` resource or static +configuration file: - Create a YAML file `cap.yaml` or get the existing file using `tctl get cap` - + + Create a YAML file called `cap.yaml` or get the existing file using + `tctl get cap`. + ```yaml kind: cluster_auth_preference metadata: @@ -109,7 +228,7 @@ or static configuration file: ``` - Edit the `teleport.yaml` of the Auth server: + Edit `/etc/teleport.yaml` on the Auth Server: ```yaml auth_service: @@ -117,10 +236,37 @@ or static configuration file: locking_mode: best_effort ``` - Restart the auth server for the change to take effect. + Restart the Auth Server for the change to take effect. + + + +The cluster-wide mode defaults to `best_effort`. You can set up the default +locking mode via API or CLI using a `cluster_auth_preference` resource: + +Create a YAML file called `cap.yaml` or get the existing file using +`tctl get cap`. + +```yaml +kind: cluster_auth_preference +metadata: + name: cluster-auth-preference +spec: + locking_mode: best_effort +version: v2 +``` + +Create a resource: + +```code +$ tctl create -f cap.yaml +# cluster auth preference has been updated +``` + + + It is also possible to configure the locking mode for a particular role: ```yaml diff --git a/docs/pages/access-controls/guides/role-templates.mdx b/docs/pages/access-controls/guides/role-templates.mdx index 66f56a9488224..2959c14ea065d 100644 --- a/docs/pages/access-controls/guides/role-templates.mdx +++ b/docs/pages/access-controls/guides/role-templates.mdx @@ -3,19 +3,18 @@ title: Teleport Role Templates description: Mapping SSO and Local Users Traits to Roles with Template. --- -# Role Templates - -As organizations grow, infrastructure teams have to figure out -how to define access control policies that don't require manual configuration -every time people join, leave and form new teams. +As organizations grow, infrastructure teams have to figure out how to define +access control policies that don't require manual configuration every time +people join, leave, and form new teams. Here are some common examples of such policies: - Grant every single sign-on user an SSH login generated from their email. - Assign each team member to their team's Kubernetes group. -- Limit dev team to read-only replica of a database. +- Limit the dev team to a read-only replica of a database. -Let's explore how Teleport's role templates provide a way to describe these and other policies. +Let's explore how Teleport's role templates provide a way to describe these and +other policies. ## Prerequisites @@ -28,8 +27,8 @@ Let's explore how Teleport's role templates provide a way to describe these and Imagine you have two users, Alice and Bob. We would like to set the following access policies: -- Alice to login as SSH user `admin` and Kubernetes group `edit` -- Bob to login as `ubuntu` and Kubernetes group `view` +- Alice can log in as SSH user `admin` and Kubernetes group `edit` +- Bob can log in as `ubuntu` and Kubernetes group `view` We can create two roles, one for each user in file `roles.yaml`: @@ -73,7 +72,7 @@ Having one role per user is not going to scale well. Because the roles are so similar, we can assign variables to each user, and use just one role template for both Alice and Bob. -Let's create a role template `devs.yaml`: +Let's create a role template called `devs.yaml`: ```yaml kind: role @@ -91,9 +90,11 @@ spec: ``` Any role becomes a template once it starts using template variables. -Just like roles, role templates are a valid YAML and validate both the structure and types. -Role template `devs` is using `internal` notation referring to local user's +Just like roles, role templates are valid YAML and validate both the structure +and types. + +The role template `devs` is using the `internal` notation to refer to the local user's traits `logins` and `kubernetes_groups`. Use `tctl` to create a role template: @@ -102,8 +103,8 @@ Use `tctl` to create a role template: $ tctl create -f devs.yaml ``` -The last step is to update Alice's and Bob's users with traits. Here is an example -of user resources in a file `traits.yaml`: +The last step is to update Alice's and Bob's users with traits. Here is an +example of user resources in a file called `traits.yaml`: ```yaml kind: user @@ -127,7 +128,7 @@ spec: kubernetes_groups: ['view'] ``` -Update both user's entries with `tctl create -f` command: +Update both users' entries with the `tctl create -f` command: ```code $ tctl create -f traits.yaml @@ -135,7 +136,9 @@ $ tctl create -f traits.yaml ``` Once Alice logs in, she will receive SSH and X.509 certificates with -a new role and SSH logins and Kubernetes groups set: +a new role. SSH logins and Kubernetes groups will also be set: + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -151,15 +154,36 @@ $ tsh login --proxy=teleport.example.com --user=alice # Extensions: permit-port-forwarding, permit-pty ``` + + + +```code +$ tsh login --proxy=mytenant.teleport.sh --user=alice + +# > Profile URL: https://mytenant.teleport.sh:443 +# Logged in as: alice +# Cluster: mytenant.teleport.sh +# Roles: devs* +# Logins: admin +# Kubernetes: enabled +# Kubernetes groups: edit +# Valid until: 2021-03-26 07:13:57 -0700 PDT [valid for 12h0m0s] +# Extensions: permit-port-forwarding, permit-pty +``` + + + + ## SSO users -Identity provider admins can assign metadata to a user, such as -group membership or access permissions. Administrators configure what metadata -is shared with Teleport. Teleport receives user metadata keys and values as OIDC claims or SAML -attributes during [single sign-on redirect flow](https://goteleport.com/blog/how-oidc-authentication-works/): +Identity provider admins can assign metadata to a user such as group membership +or access permissions. Administrators configure what metadata is shared with +Teleport. Teleport receives user metadata keys and values as OIDC claims or SAML +attributes during the +[single sign-on redirect flow](https://goteleport.com/blog/how-oidc-authentication-works/): ```yaml -# Alice has an email alice@example.com. Email is a standard OIDC claim. +# Alice has email alice@example.com. Email is a standard OIDC claim. email: "alice@example.com" # Alice is a member of groups admins and devs groups: ["admins", "devs"] @@ -167,8 +191,8 @@ groups: ["admins", "devs"] access: {"env": ["prod", "staging"]} ``` -Let's create role template `sso-users` that expects external attribute `logins` -to be set by identity provider. Save this role as `sso-users.yaml`: +Let's create a role template called `sso-users` that expects external attribute +`logins` to be set by an identity provider. Save this role as `sso-users.yaml`: ```yaml kind: role @@ -184,8 +208,8 @@ spec: '*': '*' ``` -A GitHub connector `github.yaml` maps every `cyber` team's member of organization `octocats` to -the role `sso-logins`: +A GitHub connector called `github.yaml` maps every member of team `cyber` in +organization `octocats` to the role `sso-users`: ```yaml kind: github @@ -193,18 +217,18 @@ version: v3 metadata: name: github spec: - # Client ID of Github OAuth app + # Client ID of GitHub OAuth app client_id: client-id - # Client secret of Github OAuth app + # Client secret of GitHub OAuth app client_secret: secret-data-here - # Connector display name that will be shown on web UI login screen - display: Github + # Connector display name that will be shown on the Web UI login screen + display: GitHub # Callback URL that will be called after successful authentication redirect_url: https://teleport.example.com/v1/webapi/github/callback - # Mapping of org/team memberships onto allowed logins and roles + # Mapping of org/team memberships onto allowed Teleport roles teams_to_logins: - - organization: octocats # Github organization name - team: cyber # Github team name within that organization + - organization: octocats # GitHub organization name + team: cyber # GitHub team name within that organization # Role names to map to logins: - sso-users @@ -217,7 +241,9 @@ $ tctl create -f github.yaml ``` Once Bob logs in using SSO, he will receive SSH and X.509 certificates with -a new role and SSH logins generated using `sso-users` role template: +a new role and SSH logins generated using the `sso-users` role template: + + ```code $ tsh login --proxy=teleport.example.com --auth=github @@ -233,6 +259,25 @@ $ tsh login --proxy=teleport.example.com --auth=github # Extensions: permit-port-forwarding, permit-pty ``` + + + +```code +$ tsh login --proxy=mytenant.teleport.sh --auth=github + +#> Profile URL: https://mytenant.teleport.sh:443 +# Logged in as: bob +# Cluster: mytenant.teleport.sh +# Roles: sso-users* +# Logins: bob +# Kubernetes: enabled +# Kubernetes groups: edit +# Valid until: 2021-03-26 07:13:57 -0700 PDT [valid for 12h0m0s] +# Extensions: permit-port-forwarding, permit-pty +``` + + + ## Interpolation rules Administrators can configure what attributes identity providers return @@ -324,3 +369,48 @@ Function | Description --- | --- `email.local(variable)` | Extracts the local part of an email field, like `Alice ` or `bob@example.com`. `regexp.replace(variable, expression, replacement)` | Finds all matches of `expression` and replaces them with `replacement`. This supports expansion, e.g. `regexp.replace(external.email, "^(.*)@example.com$", "$1")`. Values which do not match the expression will be filtered out. + +## Templating in Access Requests + +Access and Reviewer Request specifications do not use the same interpolation +system as logins, labels etc. Instead, you can use the `claims_to_roles` clause +in the `request` and `review` rules to specify one or more patterns to match. + +For example, given the following rule template: + +```yaml +kind: role +version: v3 +metadata: + name: product-admin +spec: + allow: + request: + # `roles` is a static list of roles a user with the `product-admin` role may + # request temporary access to + roles: [access] + + claims_to_roles: + - claim: 'projects' + value: '^product-(.*)$' # matches all group names with a leading 'product-' + roles: ['$1-admin'] # generates a role name from the value capture +``` + +For example, we could grant Alice the `product-admin` role and add some entries to +the `projects` trait: + +```yaml +kind: user +version: v2 +metadata: + name: alice +spec: + roles: ['dev', 'product-admin'] + traits: + projects: ['internal-tooling', 'product-alpha', 'product-beta'] +``` + +In this case, Alice would be allowed to request access to the RBAC roles `access` (from the static +role list) and `alpha-admin` and `beta-admin` (from the `claims_to_roles` mapping). + +The same syntax applies for Review Requests. diff --git a/docs/pages/includes/tctl.mdx b/docs/pages/includes/tctl.mdx index f6bce202772b2..8b99565035382 100644 --- a/docs/pages/includes/tctl.mdx +++ b/docs/pages/includes/tctl.mdx @@ -34,6 +34,6 @@ $ tctl status # CA pin sha256:sha-hash-here ``` -You can run subsequent `tctl` commands in this guide on your local machine. +You must run subsequent `tctl` commands in this guide on your local machine. diff --git a/docs/pages/server-access/guides/ssh-pam.mdx b/docs/pages/server-access/guides/ssh-pam.mdx index 4f614c9e8ab2d..2c605a153fee8 100644 --- a/docs/pages/server-access/guides/ssh-pam.mdx +++ b/docs/pages/server-access/guides/ssh-pam.mdx @@ -5,7 +5,8 @@ h1: Pluggable Authentication Modules (PAM) videoBanner: VrZXZtxjNes --- -Teleport's node service can be configured to integrate with [PAM](https://en.wikipedia.org/wiki/Linux_PAM). +Teleport's SSH Service can be configured to integrate with +Pluggable Authentication Modules (PAM). Teleport currently supports the `auth`, `account`, and `session` PAM modules. The `auth` stack is optional and not used by default. @@ -13,11 +14,13 @@ stack is optional and not used by default. These are a few things leverage PAM for: - Create a custom Message of the Day (MOTD) -- Create local (UNIX) users on login -- Add additional authentication steps using PAM +- Create local Unix users on login +- Add authentication steps ## Introduction to Pluggable Authentication Modules +### Background + Pluggable Authentication Modules (PAM) date back to 1995 when Sun Microsystems implemented a generic authentication framework for Solaris. Since then most GNU/Linux distributions have adopted PAM. @@ -30,23 +33,22 @@ The Pluggable Authentication Modules (PAM) library abstracts several common authentication-related operations and provides a framework for dynamically loaded modules that implement these operations in various ways. -**Terminology** +### Terminology -In PAM parlance, the application that uses PAM to authenticate a user is the server, +In PAM parlance, the application that uses PAM to authenticate a user is the **server**, and is identified for configuration purposes by a service name, which is often (but not necessarily) the program name. -The user requesting authentication is called the applicant, while the user (usually, root) +The user requesting authentication is called the **applicant**, while the user (usually, root) charged with verifying their identity and granting them the requested credentials is -called the arbitrator. +called the **arbitrator**. The sequence of operations the server goes through to authenticate a user and perform -whatever task they requested is a PAM transaction; the context within which the server -performs the requested task is called a session. +whatever task they requested is a PAM **transaction**. The context within which the server +performs the requested task is called a **session**. -The functionality embodied by PAM is divided into six primitives grouped into four -facilities: authentication, account management, session management, and password -management. +The functionality embodied by PAM is divided into four facilities: +authentication, account management, session management, and password management. Teleport currently supports account management and session management. @@ -56,7 +58,7 @@ Teleport currently supports account management and session management. (!docs/pages/includes/backup-warning.mdx!) -To enable PAM on a given Linux machine, update `/etc/teleport.yaml` with: +To enable PAM on a Linux machine, update `/etc/teleport.yaml` with: ```yaml ssh_service: @@ -74,42 +76,16 @@ ssh_service: ``` Please note that most Linux distributions come with several PAM services in -`/etc/pam.d` and Teleport will try to use `sshd` by default, which will be -removed if you uninstall the `openssh-server` package. We recommend creating your -own PAM service file like `/etc/pam.d/teleport` and specifying it as -`service_name` above. - -## Set Message of the Day (motd) with Teleport - -A cluster-wide Message of the Day can be set in the `auth_service` configuration. - -```yaml -auth_service: - message_of_the_day: "Welcome to the cluster. All activity will be logged." -``` - -This will be shown during the `tsh login` process, and must be positively acknowledged -before the user is allowed to log into the cluster. - -```code -$ tsh login --proxy teleport.example.com -# Welcome to the cluster. All activity will be logged. -# Press [ENTER] to continue. -``` - -Alternatively, a per-node Message of the Day can be set using the traditional unix -`/etc/motd` file. The `/etc/motd` file is normally displayed by login(1) after a user -has logged in but before the shell is run. It is generally used for important system-wide -announcements. - -This feature can help you inform users that activity on the node is being audited -and recorded. +`/etc/pam.d`, and Teleport will try to use `/etc/pam.d/sshd` by default. This +file will be removed if you uninstall the `openssh-server` package. We recommend +creating your own PAM service file like `/etc/pam.d/teleport` and specifying it +as `service_name` above. -## Custom environment variables +## Get and set environment variables for PAM modules -Teleport supports setting arbitrary environment variables for PAM modules as of version 6.1. -These variables can also be role-style SSO claims in the form `{{ external.email }}` -where `email` is a claim made by the configured SSO IdP. +Teleport supports setting arbitrary environment variables for PAM modules as of +version 6.1. These variables can also be role-style SSO claims in the form +`{{ external.email }}`, where `email` is a claim made by the configured SSO IdP. To set custom environment variables, update `/etc/teleport.yaml` with: @@ -125,84 +101,67 @@ ssh_service: # "false" by default use_pam_auth: true # sets custom environment variables for PAM modules - # no environment variables except the standard `TELEPORT_USERNAME`, `TELEPORT_LOGIN`, and `TELEPORT_ROLES` environment: FOO: "bar" EMAIL: "{{ external.email }}" ``` -### Example node with PAM turned off +Teleport can also read PAM environment variables from the PAM **handle**, an +opaque data structure that is used by PAM to store state. These variables +include: -```yaml -teleport: - nodename: graviton-node-1 - auth_token: hello - auth_servers: - - 10.2.1.230:5070 - data_dir: /var/lib/teleport -proxy_service: - enabled: false -auth_service: - enabled: false -ssh_service: - enabled: true - # configures PAM integration. see below for more details. - pam: - enabled: false -``` +- `TELEPORT_USERNAME`: The Teleport username of the user who is logging into a Node. This is usually an email address (such as `user@example.com`) if using SAML/OIDC identities with Teleport Enterprise, or a more standard `exampleuser` if using local Teleport users. +- `TELEPORT_LOGIN`: The name of the Linux/Unix username that the Teleport user assumes when logging into the Teleport Node, e.g., `root`, `developer`, `ubuntu`, `ec2-user`,or similar. +- `TELEPORT_ROLES`: A space-separated list of Teleport roles which the Teleport user has, e.g., `developer tester access`. -
- ![Teleport SSH without MOTD](../../../img/motd/teleport-no-MOTD.png) -
+## Display a Message of the Day (MOTD) with Teleport -### Example node with PAM enabled + + +A cluster-wide Message of the Day can be set in the `auth_service` configuration. ```yaml -teleport: - nodename: graviton-node-1 - auth_token: hello - auth_servers: - - 10.2.1.230:5070 - data_dir: /var/lib/teleport -proxy_service: - enabled: false auth_service: - enabled: false -ssh_service: - enabled: true - # configures PAM integration. see below for more details. - pam: - enabled: true + message_of_the_day: "Welcome to the cluster. All activity will be logged." ``` -
- ![Teleport SSH with MOTD](../../../img/motd/teleport-with-MOTD.png) -
- -When PAM is enabled it will use the default `sshd` config file. This can differ per -distro. +This will be shown during the `tsh login` process, and must be positively acknowledged +before the user is allowed to log in to the cluster. ```code -$ cat /etc/pam.d/sshd +$ tsh login --proxy teleport.example.com +# Welcome to the cluster. All activity will be logged. +# Press [ENTER] to continue. ``` -The default `sshd` will call two `pam_motd` files, one dynamic MOTD that prints the machine -info, and a static MOTD that can be set by an admin. +Alternatively, a per-Node Message of the Day can be set using +the traditional Unix `/etc/motd` file. The `/etc/motd` file is normally +displayed by login(1) after a user has logged in but before the shell is run. It +is generally used for important system-wide announcements. + + + + +You can set a per-Node Message of the Day using the traditional Unix `/etc/motd` +file. The `/etc/motd` file is normally displayed by login(1) after a user has +logged in but before the shell is run. It is generally used for important +system-wide announcements. + + + +This feature can help you inform users that activity on the Node is being audited +and recorded. + +The default `sshd` PAM configuration will call two `pam_motd` files, one dynamic +MOTD that prints the machine info, and a static MOTD that can be set by an +admin. ```txt session optional pam_motd.so motd=/run/motd.dynamic session optional pam_motd.so noupdate ``` -By updating `/etc/motd` you can provide a message to users accessing nodes via Teleport. +By updating `/etc/motd` you can provide a message to users accessing Nodes via Teleport. ```code $ cat /etc/motd @@ -217,28 +176,13 @@ $ cat /etc/motd ![Teleport SSH with updated MOTD](../../../img/motd/teleport-with-updated-MOTD.png) -## Create local (UNIX) users on login -Teleport has the ability to create local (UNIX) users on login. This is +## Create local Unix users on login + +Teleport has the ability to create local Unix users on login. This is very helpful if you're a large organization and want to provision local users and home directories on the fly. -Teleport added the ability to read in PAM environment variables from PAM handle and pass -environment variables to PAM modules: `TELEPORT_USERNAME`, `TELEPORT_LOGIN`, and `TELEPORT_ROLES`. - -Here are some details on the contents of these environment variables which will be set by Teleport: - -- `TELEPORT_USERNAME`: The Teleport username of the user who is logging into the node. This is usually an email address (such as `user@example.com`) if using SAML/OIDC identities with Teleport Enterprise, or a more standard `exampleuser` if using local Teleport users. -- `TELEPORT_LOGIN`: The name of the Linux/UNIX principal which the Teleport user is logging into the Teleport node as - for example, `root`, `developer`, `ubuntu`, `ec2-user` or similar. -- `TELEPORT_ROLES`: A space-separated list of Teleport roles which the Teleport user has - for example: `developer tester admin`. - -This PAM module creates the user and home directory before attempting to launch -a shell for said user. - -### Examples - -**Using pam_exec.so** - Using `pam_exec.so` is the easiest way to use the PAM stack to create a user if the user does not already exist. `pam_exec.so` usually ships with the operating system. @@ -247,7 +191,7 @@ You can either add `pam_exec.so` to the existing PAM stack for your application write a new one for Teleport. In this example, we'll write a new one to simplify how to use `pam_exec.so` with Teleport. -Start by creating a file `/etc/pam.d/teleport` with the following contents: +Start by creating a file called `/etc/pam.d/teleport` with the following contents: ```txt account required pam_exec.so /etc/pam-exec.d/teleport_acct @@ -256,21 +200,16 @@ session required pam_permit.so ``` - Pay attention to the inclusion of `pam_motd.so` under the `session` facility. While `pam_motd.so` is not required for user creation, Teleport requires at least one module to be set under both the `account` and `session` facilities for it to work. - -Next, create the script that will be run by `pam_exec.so` like below. This -script will check if the user passed in `TELEPORT_LOGIN` exists and if it does -not, it will create it. Any error from `useradd` will be written to -`/tmp/pam.error`. Note the additional environment variables -`TELEPORT_USERNAME`, `TELEPORT_ROLES`, and `TELEPORT_LOGIN`. These can be used -to write richer scripts that may change the system in other ways based on -identity information. + Pay attention to the inclusion of `pam_motd.so` under the `session` facility. + While `pam_motd.so` is not required for user creation, Teleport requires at + least one module to be set under both the `account` and `session` facilities + for it to work. - - The `useradd` location can have a different path than the example below depending on your linux flavor. Adjust to your particular system as needed from `which useradd` (Ex: `/usr/sbin/useradd` instead of the below example). +Next, create a script that will be run by `pam_exec.so`. + ```bash mkdir -p /etc/pam-exec.d cat > /etc/pam-exec.d/teleport_acct < + + The `useradd` command can have a different path than the example above + depending on your Linux distribution. Adjust to your particular system as needed + depending on the result of the following command: + + ```code + $ which useradd + ``` + + + + Next, update `/etc/teleport.yaml` to call the above PAM stack by both enabling PAM and setting the service_name. @@ -300,11 +260,11 @@ The `/etc/pam-exec.d/teleport_acct` script can set the user's groups as an optio the user's permissions. The user's roles are populated as space-delimited `TELEPORT_ROLES` variables. These could be used to map to a particular `sudo` group with additional scripting. -## Add additional authentication steps +## Add authentication steps -By using the PAM `auth` modules, it is possible to add additional authentication -steps during user login. These can include passwords, 2nd factor, or even -biometrics. +By using the PAM `auth` modules, it is possible to add authentication steps +during user login. These can include passwords, second authentication factor, or +even biometrics. Note that Teleport enables strong SSH authentication out of the box using certificates. For most users, hardening [the initial Teleport diff --git a/docs/pages/server-access/guides/tsh.mdx b/docs/pages/server-access/guides/tsh.mdx index 9320e2adcb0b1..fb1c081fb3387 100644 --- a/docs/pages/server-access/guides/tsh.mdx +++ b/docs/pages/server-access/guides/tsh.mdx @@ -1,42 +1,43 @@ --- -title: Using TSH -description: Using TSH command line tool -h1: TSH command line tool +title: Using the tsh Command Line Tool +description: Using the tsh command line tool --- -This User Manual covers usage of the Teleport client tool, `tsh` and Teleport's Web interface. +This guide will show you how to use the Teleport client tool, `tsh`. -In this document you will learn how to: +You will learn how to: -- Log into an interactive shell on remote cluster nodes. +- Log in to an interactive shell on remote cluster nodes. - Copy files to and from cluster nodes. -- Connect to SSH clusters behind firewalls without any open ports, using SSH +- Connect to SSH clusters behind firewalls without any open ports using SSH reverse tunnels. -- Explore a cluster and execute commands on specific nodes in a cluster. +- Explore a cluster and execute commands on specific nodes in the cluster. - Share interactive shell sessions with colleagues or join someone else's session. - Replay recorded interactive sessions. In addition to this document, you can always simply type `tsh` into your -terminal for the [CLI reference](../../setup/reference/cli.mdx). +terminal for the CLI reference. ## Introduction For the impatient, here's an example of how a user would typically use [`tsh`](../../setup/reference/cli.mdx#tsh): + + ```code -# Login into a Teleport cluster. This command retrieves user's certificates +# Log into a Teleport cluster. This command retrieves the user's certificates # and saves them into ~/.tsh/teleport.example.com $ tsh login --proxy=teleport.example.com -# SSH into a node, as usual: +# SSH into a Node as usual $ tsh ssh user@node -# `tsh ssh` takes the same arguments as OpenSSH client: +# `tsh ssh` takes the same arguments as the OpenSSH client: $ tsh ssh -o ForwardAgent=yes user@node $ tsh ssh -o AddKeysToAgent=yes user@node -# you can even create a convenient symlink: +# You can even create a convenient symlink: $ ln -s /path/to/tsh /path/to/ssh # ... and now your 'ssh' command is calling Teleport's `tsh ssh` @@ -46,6 +47,33 @@ $ ssh user@host $ tsh logout ``` + + + +```code +# Login into a Teleport cluster. This command retrieves the user's certificates +# and saves them into ~/.tsh/mytenant.teleport.sh +$ tsh login --proxy=mytenant.teleport.sh + +# SSH into a Node as usual +$ tsh ssh user@node + +# `tsh ssh` takes the same arguments as the OpenSSH client: +$ tsh ssh -o ForwardAgent=yes user@node +$ tsh ssh -o AddKeysToAgent=yes user@node + +# You can even create a convenient symlink: +$ ln -s /path/to/tsh /path/to/ssh + +# ... and now your 'ssh' command is calling Teleport's `tsh ssh` +$ ssh user@host + +# This command removes SSH certificates from a user's machine: +$ tsh logout +``` + + + In other words, Teleport was designed to be fully compatible with existing SSH-based workflows and does not require users to learn anything new, other than to call [`tsh login`](../../setup/reference/cli.mdx#tsh-login) in the beginning. @@ -62,9 +90,12 @@ A user identity in Teleport exists in the scope of a cluster. The member nodes of a cluster may have multiple OS users on them. A Teleport administrator assigns allowed logins to every Teleport user account. -When logging into a remote node, you will have to specify both logins. Teleport -identity will have to be passed as `--user` flag, while the node login will be -passed as `login@host`, using syntax compatible with traditional `ssh`. +When logging into a remote node, you will have to specify both the Teleport +login and the OS login. A Teleport identity will have to be passed via the +`--user` flag while the OS login will be passed as `login@host` using syntax +compatible with the traditional `ssh` command. + + ```code # Authenticate against the "work" cluster as joe and then @@ -72,12 +103,25 @@ passed as `login@host`, using syntax compatible with traditional `ssh`. $ tsh ssh --proxy=work.example.com --user=joe root@node ``` + + + +```code +# Authenticate against the "work" cluster as joe and then +# log into the node as root: +$ tsh ssh --proxy=mytenant.teleport.sh --user=joe root@node +``` + + + [CLI Docs - tsh ssh](../../setup/reference/cli.mdx#tsh-ssh) ## Logging in To retrieve a user's certificate, execute: + + ```code # Full form: $ tsh login --proxy=proxy_host:, @@ -88,10 +132,22 @@ $ tsh login --proxy=work.example.com # Using custom HTTPS port: $ tsh login --proxy=work.example.com:5000 -# Using custom SSH proxy port, which is set on the Auth Server: +# Using a custom SSH proxy port, which is set on the Auth Server: $ tsh login --proxy=work.example.com:2002 ``` + + + +```code +# Full form: +$ tsh login --proxy=proxy_host:, + +$ tsh login --proxy=mytenant.teleport.sh +``` + + + [CLI Docs - tsh login](../../setup/reference/cli.mdx#tsh-login) | Port | Description | @@ -111,35 +167,65 @@ This allows you to authenticate just once, maybe at the beginning of the day. Su It is recommended to always use [`tsh login`](../../setup/reference/cli.mdx#tsh-login) before using any other `tsh` commands. This allows users to omit `--proxy` flag in subsequent tsh commands. For example `tsh ssh user@host` will work. -A Teleport cluster can be configured for multiple user identity sources. For example, a cluster may have a local user called `admin` while regular users should [authenticate via Github](../../setup/admin/github-sso.mdx). In this case, you have to pass `--auth` flag to `tsh login` to specify which identity storage to use: +A Teleport cluster can be configured for multiple user identity sources. For example, a cluster may have a local user called `admin` while regular users should [authenticate via GitHub](../../setup/admin/github-sso.mdx). In this case, you have to pass `--auth` flag to `tsh login` to specify which identity storage to use: + + ```code -# Login using the local Teleport 'admin' user: +# Log in using the local Teleport 'admin' user: $ tsh --proxy=proxy.example.com --auth=local --user=admin login -# Login using Github as an SSO provider, assuming the Github connector is called "github" +# Log in using GitHub as an SSO provider, assuming the GitHub connector is called "github" $ tsh --proxy=proxy.example.com --auth=github --user=admin login ``` -When using an external identity provider to log in, `tsh` will need to open a web browser to -complete the authentication flow. By default, `tsh` will use your system's default browser to open -such links. If you wish to suppress this behavior, you can use the `--browser=none` flag: + + + +```code +# Log in using the local Teleport 'admin' user: +$ tsh --proxy=mytenant.teleport.sh --auth=local --user=admin login + +# Log in using GitHub as an SSO provider, assuming the GitHub connector is called "github" +$ tsh --proxy=mytenant.teleport.sh --auth=github --user=admin login +``` + + + +When using an external identity provider to log in, `tsh` will need to open a +web browser to complete the authentication flow. By default, `tsh` will use your +system's default browser. If you wish to suppress this behavior, you can use the +`--browser=none` flag: + + ```code # Don't open the system default browser when logging in $ tsh login --proxy=work.example.com --browser=none ``` + + + +```code +# Don't open the system default browser when logging in +$ tsh login --proxy=mytenant.teleport.sh --browser=none +``` + + + In this situation, a link will be printed on the screen. You can copy and paste this link into a browser of your choice to continue the login flow. [CLI Docs - tsh login](../../setup/reference/cli.mdx#tsh-login) -### Inspecting SSH certificate +### Inspecting an SSH certificate To inspect the SSH certificates in `~/.tsh`, a user may execute the following command: + + ```code $ tsh status @@ -153,6 +239,24 @@ $ tsh status # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` + + + +```code +$ tsh status + +# > Profile URL: https://mytenant.teleport.sh:3080 +# Logged in as: johndoe +# Cluster: mytenant.teleport.sh +# Roles: admin* +# Logins: root, admin, guest +# Kubernetes: disabled +# Valid until: 2017-04-25 15:02:30 -0700 PDT [valid for 1h0m0s] +# Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty +``` + + + [CLI Docs - tsh status](../../setup/reference/cli.mdx#tsh-status) ### SSH agent support @@ -165,8 +269,8 @@ via: $ ssh-add -L ``` -SSH agent can be used to feed the certificate to other SSH clients, for example -to OpenSSH `ssh`. +The SSH agent can be used to feed the certificate to other SSH clients, for example +to OpenSSH (`ssh`). If you wish to disable SSH agent integration, pass `--no-use-local-ssh-agent` to `tsh`. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment @@ -177,20 +281,38 @@ variable to `false` in your shell profile to make this permanent. [`tsh login`](../../setup/reference/cli.mdx#tsh-login) can also save the user certificate into a file: + + ```code -# Authenticate user against proxy.example.com and save the user -# certificate into joe.pem file +# Authenticate the user against proxy.example.com and save the user +# certificate to joe.pem $ tsh login --proxy=proxy.example.com --out=joe -# Use joe.pem to login into a server 'db' +# Use joe.pem to log in to the server 'db' $ tsh ssh --proxy=proxy.example.com -i joe joe@db ``` -By default, `--out` flag will create an identity file suitable for `tsh -i` but -if compatibility with OpenSSH is needed, `--format=openssh` must be specified. -In this case, the identity will be saved into two files: `joe` and + + + +```code +# Authenticate the user against mytenant.teleport.sh and save the user +# certificate to joe.pem +$ tsh login --proxy=mytenant.teleport.sh --out=joe + +# Use joe.pem to log in to the server 'db' +$ tsh ssh --proxy=mytenant.teleport.sh -i joe joe@db +``` + + + +By default, the `--out` flag will create an identity file suitable for `tsh -i`. +If compatibility with OpenSSH is needed, `--format=openssh` must be specified. +In this case, the identity will be saved into two files, `joe` and `joe-cert.pub`: + + ```code $ tsh login --proxy=proxy.example.com --out=joe --format=openssh $ ls -lh @@ -200,43 +322,67 @@ $ ls -lh # -rw------- 1 joe staff 1.5K Aug 10 16:16 joe-cert.pub ``` -### SSH certificates for automation + + -{ - /* This seems more like an admin task */ -} +```code +$ tsh login --proxy=mytenant.teleport.sh --out=joe --format=openssh +$ ls -lh + +# total 8.0K +# -rw------- 1 joe staff 1.7K Aug 10 16:16 joe +# -rw------- 1 joe staff 1.5K Aug 10 16:16 joe-cert.pub +``` + + + +### SSH certificates for automation Regular users of Teleport must request an auto-expiring SSH certificate, usually -every day. This doesn't work for non-interactive scripts, like cron jobs or +every day. This doesn't work for non-interactive scripts, like cron jobs or a CI/CD pipeline. -For such automation, it is recommended to create a separate Teleport user for -bots and request a certificate for them with a long time to live (TTL). +For this kind of automation, it is recommended to create a separate Teleport +user for bots and request a certificate for them with a long time to live (TTL). -In this example, we're creating a certificate with a TTL of 1-hour for the -jenkins user and storing it in a `jenkins.pem` file, which can be later used with +In this example, we're creating a certificate with a TTL of one hour for the +`jenkins` user and storing it in a `jenkins.pem` file, which can be later used with `-i` (identity) flag for `tsh`. + + ```code -# To be executed on a Teleport auth server +# To be executed on a Teleport Auth Server $ tctl auth sign --ttl=1h--user=jenkins --out=jenkins.pem ``` + + + +```code +# Log in to your Teleport Cloud cluster so you can use tctl locally. +$ tsh login --proxy=myinstance.teleport.sh --user=email@example.com +$ tctl auth sign --ttl=1h--user=jenkins --out=jenkins.pem +``` + + + [CLI Docs - tctl auth sign](../../setup/reference/cli.mdx#tctl-auth-sign) -Now `jenkins.pem` can be copied to the jenkins server and passed to `-i` -(identity file) flag of `tsh`. Essentially `tctl auth sign` is an admin's -equivalent of `tsh login --out` and allows for unrestricted certificate TTL -values. +Now `jenkins.pem` can be copied to the Jenkins server and passed to the `-i` +(identity file) flag of `tsh`. + +`tctl auth sign` is an admin's equivalent of `tsh login --out` and allows for +unrestricted certificate TTL values. ## Exploring the cluster -In a Teleport cluster, all nodes periodically ping the cluster's auth server and -update their status. This allows Teleport users to see which nodes are online -with the `tsh ls` command: +In a Teleport cluster, all Nodes periodically ping the cluster's Auth Service +and update their status. This allows Teleport users to see which Nodes are +online with the `tsh ls` command: ```code -# This command lists all nodes in the cluster which you previously logged in via "tsh login": +# This command lists all Nodes in the cluster you logged into via "tsh login": $ tsh ls # Node Name Address Labels @@ -251,7 +397,7 @@ $ tsh ls `tsh ls` can apply a filter based on the node labels. ```code -# Only show nodes with os label set to 'osx': +# Only show Nodes with os label set to 'osx': $ tsh ls os=osx # Nodename UUID Address Labels @@ -263,7 +409,7 @@ $ tsh ls os=osx ## Interactive shell -To launch an interactive shell on a remote node or to execute a command, use +To launch an interactive shell on a remote Node or to execute a command, use `tsh ssh`. `tsh` tries to mimic the `ssh` experience as much as possible, so it supports @@ -271,11 +417,13 @@ the most popular `ssh` flags like `-p`, `-l` or `-L`. For example, if you have the following alias defined in your `~/.bashrc`: `alias ssh="tsh ssh"` then you can continue using familiar SSH syntax: + + ```code # Have this alias configured, perhaps via ~/.bashrc $ alias ssh="/usr/local/bin/tsh ssh" -# Login into a cluster and retrieve your SSH certificate: +# Login in to a cluster and retrieve your SSH certificate: $ tsh --proxy=proxy.example.com login # These commands execute `tsh ssh` under the hood: @@ -285,20 +433,41 @@ $ ssh -o ForwardAgent=yes user@node $ ssh -o AddKeysToAgent=yes user@node ``` + + + +```code +# Have this alias configured, perhaps via ~/.bashrc +$ alias ssh="/usr/local/bin/tsh ssh" + +# Login in to a cluster and retrieve your SSH certificate: +$ tsh --proxy=mytenant.teleport.sh login + +# These commands execute `tsh ssh` under the hood: +$ ssh user@node +$ ssh -p 6122 user@node ls +$ ssh -o ForwardAgent=yes user@node +$ ssh -o AddKeysToAgent=yes user@node +``` + + + + + ### Proxy ports -A Teleport proxy uses two ports: `3080` for HTTPS and `3023` for proxying SSH -connections. The HTTPS port is used to serve Web UI and also to implement 2nd -factor auth for the `tsh` client. +By default, the Teleport Proxy Service listens on port `3080`. -If a Teleport proxy is configured to listen on non-default ports, they must be -specified via `--proxy` flag as shown: +If a Teleport Proxy Service instance is configured to listen on non-default +ports, they must be specified via `--proxy` flag as shown: ```code -$ tsh --proxy=proxy.example.com:5000,5001 +$ tsh --proxy=proxy.example.com:5000 ``` -This means *use port `5000` for HTTPS and `5001` for SSH*. +This `tsh` command will use port `5000` of the Proxy Service. + + ### Port forwarding @@ -316,8 +485,8 @@ Example: $ tsh ssh -L 5000:web.remote:80 node ``` -This will connect to remote server `node` via `proxy.example.com`, then it will -open a listening socket on `localhost:5000` and will forward all incoming +This will connect to remote server `node` via the Proxy Service, then open a +listening socket on `localhost:5000`. Finally, it will forward all incoming connections to `web.remote:80` via this SSH tunnel. It is often convenient to establish port forwarding, execute a local command @@ -336,36 +505,47 @@ This command: 2. Binds the local port `5000` to port `80` on `google.com`. 3. Executes `curl` command locally, which results in `curl` hitting `google.com:80` via `node`. -### SSH jumphost +### SSH jump host + +While implementing `ProxyJump` for Teleport, we have extended the feature to `tsh`. -While implementing ProxyJump for Teleport, we have extended the feature to `tsh`. + ```code $ tsh ssh -J proxy.example.com telenode ``` + + + +```code +$ tsh ssh -J mytenant.teleport.sh telenode +``` + + + Known limitations: -- Only one jump host is supported (`-J` supports chaining that Teleport does not utilize) and `tsh` will return with error in the case of two jumphosts, i.e. `-J proxy-1.example.com,proxy-2.example.com` will not work. +- Only one jump host is supported (`-J` supports chaining that Teleport does not utilize) and `tsh` will return with error in the case of two jump hosts, i.e. `-J proxy-1.example.com,proxy-2.example.com` will not work. - When `tsh ssh -J user@proxy` is used, it overrides the SSH proxy defined in the tsh profile, and port forwarding is used instead of the existing Teleport proxy subsystem. ### Resolving Node names -`tsh` supports multiple methods to resolve remote node names. +`tsh` supports multiple methods to resolve remote Node names. 1. **Traditional**: by IP address or via DNS. -2. **Nodename setting**: teleport daemon supports the` nodename` flag, which allows Teleport administrators to assign alternative node names. -3. **Labels**: you can address a node by `name=value` pair. +2. **Nodename setting**: the `teleport` daemon supports the` nodename` flag, which allows Teleport administrators to assign alternative Node names. +3. **Labels**: you can address a Node by `name=value` pair. -If we have two nodes, one with `os:linux` label and one node with `os:osx`, we -can log into the OSX node with: +If we have two Node, one with `os:linux` label and one Node with `os:osx`, we +can log in to the OSX Node with: ```code $ tsh ssh os=osx ``` This only works if there is only one remote node with the `os:osx` label, but -you can still execute commands via SSH on multiple nodes using labels as a +you can still execute commands via SSH on multiple Nodes using labels as a selector. This command will update all system packages on machines that run Linux: @@ -384,7 +564,7 @@ $ tsh --ttl=1 login ``` You will be logged out after one minute, but if you want to log out immediately, -you can always do: +you can always run: ```code $ tsh logout @@ -392,7 +572,7 @@ $ tsh logout ## Copying files -To securely copy files to and from cluster nodes, use the `tsh scp` command. It +To securely copy files to and from cluster Nodes, use the `tsh scp` command. It is designed to mimic traditional `scp` as much as possible: ```code @@ -410,10 +590,10 @@ $ scp -P 61122 -r files root@node:/path/to/dest Suppose you are trying to troubleshoot a problem on a remote server. Sometimes it makes sense to ask another team member for help. Traditionally, this could be -done by letting them know which node you're on, having them SSH in, start a +done by letting them know which host you're on, having them SSH in, start a terminal multiplexer like `screen`, and join a session there. -Teleport makes this more convenient. Let's log into a server named `luna` +Teleport makes this more convenient. Let's log in to a server named `luna` and ask Teleport for our current session status: ```code @@ -425,30 +605,32 @@ $ teleport status # Session ID : 7645d523-60cb-436d-b732-99c5df14b7c4 Session URL: https://work:3080/web/sessions/7645d523-60cb-436d-b732-99c5df14b7c4 ``` -{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */} Now you can invite another user account to the `work` cluster. You can share the -URL for access through a web browser, or you can share the session ID, and she can join you through her terminal by typing: +URL for access through a web browser, or you can share the session ID, and the +other user can join you through their terminal by typing: ```code $ tsh join ``` - + Joining sessions is not supported in recording proxy mode (where `session_recording` is set to `proxy`). - + ## Connecting to SSH clusters behind firewalls Teleport supports creating clusters of servers located behind firewalls **without any open listening TCP ports**. This works by creating reverse SSH -tunnels from behind-firewall environments into a Teleport proxy you have access to. +tunnels from behind-firewall environments into a Teleport Proxy Service you have access to. + +These features are called **Trusted Clusters**. Refer to [the Trusted Clusters guide](../../setup/admin/trustedclusters.mdx) +to learn how a Trusted Cluster can be configured. -These features are called *Trusted Clusters*. Refer to [the trusted clusters guide](../../setup/admin/trustedclusters.mdx) -to learn how a trusted cluster can be configured. + -Assuming the `work` Teleport proxy server is configured with a few trusted -clusters, a user may use the `tsh clusters` command to see a list of all clusters on the server: +Assuming the Teleport Proxy Server called `work` is configured with a few Trusted +Clusters, a user may use the `tsh clusters` command to see a list of all Trusted Clusters on the server: ```code $ tsh --proxy=work clusters @@ -459,9 +641,28 @@ $ tsh --proxy=work clusters # production offline ``` + + + +Assuming the Teleport Cloud tenant called `mytenant.teleport.sh` is configured with a few trusted +clusters, a user may use the `tsh clusters` command to see a list of all Trusted Clusters on the server: + +```code +$ tsh --proxy=mytenant.teleport.sh clusters + +# Cluster Name Status +# ------------ ------ +# staging online +# production offline +``` + + + [CLI Docs - tsh clusters](../../setup/reference/cli.mdx#tsh-clusters) -Now you can use the `--cluster` flag with any `tsh` command. For example, to list SSH nodes that are members of the `production` cluster, simply do: +Now you can use the `--cluster` flag with any `tsh` command. For example, to list SSH nodes that are members of the `production` cluster, simply run: + + ```code $ tsh --proxy=work ls --cluster=production @@ -472,13 +673,46 @@ $ tsh --proxy=work ls --cluster=production # db-2 xxxxxxxxx 10.0.20.41:3022 kernel:4.2 ``` + + + +```code +$ tsh --proxy=mytenant.teleport.sh ls --cluster=production + +# Node Name Node ID Address Labels +# --------- ------- ------- ------ +# db-1 xxxxxxxxx 10.0.20.31:3022 kernel:4.4 +# db-2 xxxxxxxxx 10.0.20.41:3022 kernel:4.2 +``` + + + Similarly, if you want to SSH into `db-1` inside the `production` cluster: + + ```code $ tsh --proxy=work ssh --cluster=production db-1 ``` -This is possible even if nodes in the `production` cluster are located behind a +This is possible even if Nodes in the `production` cluster are located behind a firewall without open ports. This works because the `production` cluster -establishes a reverse SSH tunnel back into `work` proxy, and this tunnel is used -to establish inbound SSH connections. +establishes a reverse SSH tunnel back into the Proxy Service called `work`, and +this tunnel is used to establish inbound SSH connections. + + + + +```code +$ tsh --proxy=mytenant.teleport.sh ssh --cluster=production db-1 +``` + +This is possible even if Nodes in the `production` cluster are located behind a +firewall without open ports. This works because the `production` cluster +establishes a reverse SSH tunnel back into your Teleport Cloud tenant's Proxy +Service, and this tunnel is used to establish inbound SSH connections. + + + +## Further reading +- [CLI Reference](../../setup/reference/cli.mdx). \ No newline at end of file diff --git a/docs/pages/setup/admin.mdx b/docs/pages/setup/admin.mdx index 161e95bac35be..d6ce320f7cfdc 100644 --- a/docs/pages/setup/admin.mdx +++ b/docs/pages/setup/admin.mdx @@ -4,29 +4,51 @@ description: Teleport Cluster Administration Guides. layout: tocless-doc --- -
    -
  • - [Github SSO](./admin/github-sso.mdx). Setup single sign-on with Github. -
    • -
  • - [Adding nodes](./admin/adding-nodes.mdx). How to add new nodes to the cluster. -
    • -
  • - [Trusted Clusters](./admin/trustedclusters.mdx). Connect multiple Teleport clusters using Trusted Clusters. -
    • -
  • - [Labels](./admin/labels.mdx). Manage nodes metadata with resource labels. -
    • -
  • - [Local Users](./admin/users.mdx). Manage local user accounts. -
    • -
  • - [Troubleshooting](./admin/troubleshooting.mdx). Collect metrics and diagnostic information from Teleport. -
    • -
  • - [Signals and Graceful Restarts](./admin/graceful-restarts.mdx). Send signals to configure and restart Teleport without loosing connections. -
    • -
  • - [Teleport Daemon](./admin/daemon.mdx). Setup and configure Teleport Linux Daemon as as Systemd unit. -
    • -
+The guides in this section show you the fundamentals of setting up and running a +Teleport cluster. You will learn how to run the `teleport` daemon, manage users +and resources, and troubleshoot any issues that arise. + +If you already understand how to set up a Teleport cluster, consult the +[Operations](./operations.mdx) section so you can start conducting periodic +cluster maintenance tasks. + +## Run Teleport + + + + Set up Teleport as a systemd unit. + + + Send signals to configure and restart Teleport without losing connections. + + + +## Manage users and resources + + + + Set up single sign-on with GitHub. + + + Add Nodes to your Teleport cluster. + + + Connect multiple Teleport clusters using Trusted Clusters. + + + Manage resource metadata with labels. + + + Manage local user accounts. + + + +## Troubleshoot issues + + + + Collect metrics and diagnostic information from Teleport. + + + + diff --git a/docs/pages/setup/admin/adding-nodes.mdx b/docs/pages/setup/admin/adding-nodes.mdx index 6c159309f7aa1..55ee1bc8ab3c6 100644 --- a/docs/pages/setup/admin/adding-nodes.mdx +++ b/docs/pages/setup/admin/adding-nodes.mdx @@ -9,31 +9,79 @@ This guide explains how to add Teleport Nodes to your cluster. (!docs/pages/includes/edition-prereqs-tabs.mdx!) +- A Linux server that you will use to host your Teleport Node + (!docs/pages/includes/tctl.mdx!) -## Adding Nodes to the cluster +## Step 1/3. Install Teleport on your Node + +On the Linux server that you will use for your Teleport Node, run the appropriate installation commands for your platform: + +(!docs/pages/includes/install-linux.mdx!) + +## Step 2/3. Join your Node to the cluster + +In this section, we will join your Node to the Teleport cluster by: + +- Obtaining information stored on the Auth Service +- Starting Teleport on your Node with the information we obtained + +### Obtain a CA pin + +In a zero-trust environment, you must assume that an attacker can hijack the IP +address of the Auth Service. + +To prevent this from happening, you need to supply every new Node with +information about the Auth Service. This technique is called **CA pinning**. It +works by asking the Auth Service to produce a CA pin, a hash value of the SPKI +header in a certificate. This way, an attacker cannot easily forge a matching +private key. + +If a CA pin is not provided, the Teleport Node will join a cluster but it will +print a warning message. + + + +The CA pin becomes invalid if a Teleport administrator performs the CA rotation +by executing [`tctl auth rotate`](../reference/cli.mdx#tctl-auth-rotate). + + + +Retrieve the CA pin of the Auth Service by running the following +command on your local machine: + +```code +$ export CA_PIN=$(tctl status | awk '/CA pin/{print $3}') + +# Cluster staging.example.com +# User CA never updated +# Host CA never updated +# CA pin (=presets.ca_pin=) +``` + +### Generate a token Teleport only allows access to Nodes that have joined the cluster. -Once a Node joins, it receives its own host certificate signed by the cluster's +Once a Node joins, it receives a host certificate signed by the cluster's Auth Service. To receive a host certificate upon joining a cluster, a new Teleport host must present an **invite token**. An invite token also defines which role a new host can assume within a cluster: `auth`, `proxy`, `node`, `app`, `kube`, or `db`. -### Generate a token - Administrators can generate tokens as they are needed. A token can be used multiple times until its time to live (TTL) expires. -Use the `tctl` tool to generate a new token. In the following example, a new +Use the `tctl` tool on your local +machine to generate a new token. In the following example, a new token is created with a TTL of five minutes: ```code -# Generate a short-lived invitation token for a new node: -$ tctl nodes add --ttl=5m --roles=node,app -# The invite token: abcdefgh-do-not-use-this-token-123 +# Generate a short-lived invite token for a new node: +$ export INVITE_TOKEN=$(tctl nodes add --ttl=5m --roles=node | grep "invite token:" | grep -Eo "[0-9a-z]{32}") +$ echo ${INVITE_TOKEN} +# (=presets.tokens.first=) # You can also list all generated non-expired tokens: $ tctl tokens ls @@ -41,7 +89,7 @@ $ tctl tokens ls # ------------------------ ----------- --------------- # (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC -# ... or revoke an invitation before it's used: +# ... or revoke an invite token before it's used: $ tctl tokens rm (=presets.tokens.first=) ``` @@ -74,36 +122,39 @@ auth_service: ``` -### Using Node invitation tokens +### Start your Node with the invite token and CA pin -Execute one of the following commands on a new Node to add it to a cluster: - -```code -# Adding an SSH Node to the cluster: -$ sudo teleport start --roles=node --token=(=presets.tokens.first=) --auth-server=10.0.10.5 -# Adding a new regular SSH Node using Teleport Node Tunneling: -$ sudo teleport start --roles=node --token=(=presets.tokens.first=) --auth-server=teleport-proxy.example.com:3080 +Execute one of the following commands on a new Node to add it to a cluster. +Supply the invite token and CA pin you retrieved earlier: -# Adding a new Proxy Service to the cluster: -$ sudo teleport start --roles=proxy --token=(=presets.tokens.first=) --auth-server=10.0.10.5 +```code +$ sudo teleport start \ + --roles=node \ + --token=(=presets.tokens.first=) \ + --ca-pin=(=presets.ca_pin=) \ + --auth-server=10.12.0.6:3025 ``` + Execute the following command on a new Node to add it to a cluster. Replace `mytenant.teleport.sh` with the domain name of your Teleport Cloud tenant. +Supply the invite token and CA pin you retrieved earlier: ```code -# Adding an SSH Node to the cluster: -$ sudo teleport start --roles=node --token=(=presets.tokens.first=) --auth-server=mytenant.teleport.sh +$ sudo teleport start \ + --roles=node \ + --token=(=presets.tokens.first=) \ + --ca-pin=(=presets.ca_pin=) \ + --auth-server=https://mytenant.teleport.sh:443 ``` - As new Nodes come online, they start sending ping requests every few seconds to the Auth Service. This allows users to explore cluster membership and size: @@ -120,7 +171,10 @@ dijkstra c9s93fd9-3333-91d3-9999-c9s93fd98f43 10.1.0.6:3022 distro as a workaround until we have a way to control the visibility of subsections using the scope switcher */} -
+ + +### Teleport Node Tunneling + Teleport Node Tunneling lets you add a remote Node to an existing Teleport Cluster through a tunnel. This can be useful for IoT applications or for managing a couple of servers in a different network. @@ -178,14 +232,36 @@ DEBU [PROC:1] Setup Proxy: Reverse tunnel proxy and web proxy listen on the s uses a round-robin or a similar balancing algorithm. Do not use sticky load balancing algorithms (a.k.a. "session affinity") with Teleport Proxy Service instances. -
+ -## Revoking invitations +## Step 3/3. Revoke an invitation Tokens used for joining Nodes to a cluster can be revoked before they are used. -To see a list of outstanding tokens, run this command: + +Run the following command to create a token for a new Proxy Service. ```code +$ tctl nodes add --ttl=5m --roles=proxy +# The invite token: (=presets.tokens.first=). +# This token will expire in 5 minutes. +# +# Run this on the new node to join the cluster: +# +# > teleport start \ +# --roles=proxy \ +# --token=(=presets.tokens.first=) \ +# --ca-pin=(=presets.ca_pin=) \ +# --auth-server=123.123.123.123:3025 +# +# Please note: +# +# - This invitation token will expire in 5 minutes +# - 123.123.123.123 must be reachable from the new node +``` + +Next, run the following command to see a list of outstanding tokens: + +``` $ tctl tokens ls # Token Role Expiry Time (UTC) @@ -208,67 +284,10 @@ static token configured via a config file. The token with the `Node` role was generated to invite a new Node to this cluster. And the third token was generated to invite a new user to sign up. -The latter two tokens can be deleted (revoked) via the `tctl tokens -del` command: +Tokens created via `tctl` can be deleted (revoked) via the `tctl tokens del` +command. Run the following command to delete a token: ```code $ tctl tokens del (=presets.tokens.first=) # Token (=presets.tokens.first=) has been deleted -``` - -## Untrusted Auth Servers - -Teleport Nodes use the HTTPS protocol to offer an invite token to the Auth Service. -In a zero-trust environment, you must assume that an attacker can hijack the IP -address of the Auth Service. - -To prevent this from happening, you need to supply every new Node with an -additional bit of information about the Auth Service. This technique is called -**CA pinning**. It works by asking the Auth Service to produce a CA pin, a hash -value of the SPKI header in a certificate. This way, an attacker cannot easily -forge a matching private key. - -Retrieve the CA pin of the Auth Service: - -```code -$ tctl status - -# Cluster staging.example.com -# User CA never updated -# Host CA never updated -# CA pin sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1 -``` - -The CA pin at the bottom needs to be passed to new Nodes when they're -starting for the first time, i.e. when they join a cluster. Here is an -example of running `teleport start` on a Node with a CA pin: - -```code -$ sudo teleport start \ - --roles=node \ - --token=(=presets.tokens.first=) \ - --ca-pin=sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1 \ - --auth-server=10.12.0.6:3025 -``` - -You can also supply a CA pin by modifying `/etc/teleport.yaml` on a Node: - -```yaml -teleport: - auth_token: "(=presets.tokens.first=)" - ca_pin: "sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1" - auth_servers: - - "10.12.0.6:3025" -``` - - - - If a CA pin is not provided, the Teleport Node will join a cluster but it will - print a `WARN` message (warning). - - The CA pin becomes invalid if a Teleport administrator - performs the CA rotation by executing - [`tctl auth rotate`](../reference/cli.mdx#tctl-auth-rotate) . - - +``` \ No newline at end of file diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index cb86449dbd397..7b5a886189d84 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -4,24 +4,36 @@ description: Setting up Github SSO videoBanner: XjgN2WWFCX8 --- -This guide explains how to set up Github Single Sign On (SSO) for Teleport. +This guide explains how to set up GitHub Single Sign On (SSO) so you can +automatically map teams in your GitHub organization to users and roles in +Teleport. ## Prerequisites +- A GitHub organization with at least one team. + (!docs/pages/includes/edition-prereqs-tabs.mdx!) -- Create and register a GitHub OAuth App. To do so, follow the instructions in - GitHub's documentation. +(!docs/pages/includes/tctl.mdx!) - [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) +## Step 1/3. Create a GitHub OAuth app - Ensure that your OAuth App's "Authentication callback URL" is - `https://PROXY_ADDRESS/v1/webapi/github/`, where `PROXY_ADDRESS` is the public - address of the Teleport Proxy Service. +Create and register a GitHub OAuth App. When you do so, ensure that your OAuth +App's "Authentication callback URL" is the following: -(!docs/pages/includes/tctl.mdx!) +``` +https://PROXY_ADDRESS/v1/webapi/github/ +``` + +`PROXY_ADDRESS` must be the public +address of the Teleport Proxy Serviceyour Teleport Cloud tenant address. -## Step 1/2. Create a GitHub authentication connector +Instructions for creating a GitHub OAuth app are available here: + +[Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) + +## Step 2/3. Create a GitHub authentication connector Define a GitHub authentication connector by creating a file called `github.yaml` with the following content: @@ -61,6 +73,7 @@ Finally, create the connector using `tctl`: ```code $ tctl create github.yaml +# authentication connector "github" has been created ``` @@ -70,7 +83,7 @@ $ tctl create github.yaml able to determine team memberships for these organizations. -## Step 2/2. Configure authentication preference +## Step 3/3. Configure authentication preference Configure the Teleport Auth Service to enable the GitHub authentication connector. @@ -88,10 +101,13 @@ spec: version: v2 ``` +For `rp_id`, use the public address of your Teleport Proxy ServiceTeleport Cloud tenant. + Create the resource: ```code $ tctl create -f cap.yaml +# cluster auth preference has been updated ```
@@ -114,4 +130,117 @@ auth_service: ``` You can now log in with Teleport using GitHub SSO. +
+ +Run the following to log out of Teleport and log in again using GitHub SSO. + + + +```code +$ tsh logout +# Logged out all users from all proxies. +$ tsh login --proxy=tele.example.com +``` + + + + +```code +$ tsh logout +# Logged out all users from all proxies. +$ tsh login --proxy=mytenant.teleport.sh +``` + + + +When you sign in for the first time, you will see a prompt to authorize your +GitHub OAuth app: + +![GitHub SSO authorization view](../../../img/github-sso-auth-screen.jpg) + +After logging in successfully, you will see the following: + +![Login success view](../../../img/login-success.jpg) + +## Troubleshooting + + + + +### Using the Web UI + +If you get "access denied" or other login errors, the number one place to check is the Audit +Log on the Teleport Auth Server. You can access it in the **Activity** tab of the Teleport Web UI. + +Example of a user being denied because the role `clusteradmin` wasn't set up: + +```json +{ + "code": "T1001W", + "error": "role clusteradmin is not found", + "event": "user.login", + "method": "oidc", + "success": false, + "time": "2019-06-15T19:38:07Z", + "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9" +} +``` + +### On the Auth Service host +You can monitor Audit Log file entries and process logs on the Teleport Auth Server. +The Audit Log is located in `/var/lib/teleport/log` by +default and it will contain a detailed reason why a user's login was denied. + + + If you are using a Teleport storage configuration that does not store log entries locally, this will not appear. You can look at the `teleport` +process logs to see `ERROR` and `INFO` entries. + + +Example of a user being denied because the role `clusteradmin` wasn't set up: + + +```json +{ + "code": "T1001W", + "error": "role clusteradmin is not found", + "event": "user.login", + "method": "oidc", + "success": false, + "time": "2019-06-15T19:38:07Z", + "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9" +} +``` + +Some errors (like filesystem permissions or a misconfigured network) can be +diagnosed using Teleport's `stderr` log, which is usually available via: + +```code +$ sudo journalctl -fu teleport +``` + +If you wish to increase the verbosity of Teleport's logs, you can pass the +[`--debug`](../../setup/reference/cli.mdx#teleport-start) flag to the `teleport start` command. + + +If you get "access denied" or other login errors, the number one place to check is the Audit +Log on the Teleport Auth Server. You can access it in the **Activity** tab of the Teleport Web UI. + +Example of a user being denied because the role `clusteradmin` wasn't set up: + +```json +{ + "code": "T1001W", + "error": "role clusteradmin is not found", + "event": "user.login", + "method": "oidc", + "success": false, + "time": "2019-06-15T19:38:07Z", + "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9" +} +``` + + diff --git a/docs/pages/setup/deployments/aws-terraform.mdx b/docs/pages/setup/deployments/aws-terraform.mdx index 0d25725a193ce..adbd40527d15f 100644 --- a/docs/pages/setup/deployments/aws-terraform.mdx +++ b/docs/pages/setup/deployments/aws-terraform.mdx @@ -707,7 +707,7 @@ To add new nodes/EC2 servers that you can "SSH into" you'll need to: - [Install the Teleport binary on the Server](../../installation.mdx) - [Run Teleport - we recommend using systemd](../admin/daemon.mdx#systemd-unit-file) - [Set the correct settings in /etc/teleport.yaml](../reference/config.mdx) -- [Add nodes to the Teleport cluster](../admin/adding-nodes.mdx#adding-nodes-to-the-cluster) +- [Add Nodes to the Teleport cluster](../admin/adding-nodes.mdx) ### Getting the CA pin hash @@ -729,9 +729,7 @@ $ aws ssm get-parameter --name "/teleport/${TF_VAR_cluster_name}/tokens/node" -- # AQICAzgLq8feq4riNouuw8Wxs5EEPlS2qKIVE5Z/qEo1i6mqfwGX3dW56SdoS6PinTWbZL1RAAAAgzCBgAYJKoZIhvcNAQcGoHMwcQIBADBsBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDNdu5TxaT8gyJx63eAIBEIA/JEpX2Vte90UmufIzZzvBQcQaKgWr95aN9xZYMEjWbAiNitxkvZgb98FgFn8d9GNwKQgDGfUYDbzsX8EqTtx7 ``` -You should use this so that nodes can validate the auth server's identity when joining your cluster. - -You can also generate a node join token using `tctl tokens add --type=node` [as detailed here in our admin guide](../admin/adding-nodes.mdx#adding-nodes-to-the-cluster). +You can also generate a Node join token using `tctl tokens add --type=node` [as detailed here in our admin guide](../admin/adding-nodes.mdx). ### Joining nodes via the Teleport auth server diff --git a/docs/pages/setup/operations.mdx b/docs/pages/setup/operations.mdx index d2ca5c5650aeb..98ba32ce96a7c 100644 --- a/docs/pages/setup/operations.mdx +++ b/docs/pages/setup/operations.mdx @@ -4,17 +4,26 @@ description: Teleport Operations - Scaling and High-Availability. layout: tocless-doc --- -
    -
  • - [Scaling](./operations/scaling.mdx). How to configure Teleport for large-scale deployments. -
    • -
  • - [Upgrading](./operations/upgrading.mdx). Learn about components version compatibility and upgrade sequence. -
    • -
  • - [Backup and Restore](./operations/backup-restore.mdx). Backing up and restoring the cluster. -
    • -
  • - [CA Rotation](./operations/ca-rotation.mdx). Rotating certificates and certificate authorities. -
    • -
+The guides in this section show you how to carry out common administration tasks +on an already running Teleport cluster. + +For guides on the fundamentals of setting up your cluster, you should consult +the [Cluster Administration Guides](./admin.mdx) section. + + + + How to configure Teleport for large-scale deployments. + + + Learn about how to upgrade your Teleport cluster while ensuring that components remain compatible. + + + Backing up and restoring the cluster. + + + Rotating Teleport certificate authorities. + + + Migrating your Teleport cluster to single-port TLS routing mode. + + diff --git a/docs/pages/setup/operations/ca-rotation.mdx b/docs/pages/setup/operations/ca-rotation.mdx index 125358306ec73..d6c41c8ad39a7 100644 --- a/docs/pages/setup/operations/ca-rotation.mdx +++ b/docs/pages/setup/operations/ca-rotation.mdx @@ -13,12 +13,9 @@ description: How to rotate Teleport's certificate authority This section will show you how to implement certificate rotation in practice. - - If you are using [CA - Pinning](../admin/adding-nodes.mdx#untrusted-auth-servers) when adding new - nodes, the CA pin will change after the rotation. Make sure you use the *new* - CA pin when adding nodes after rotation. - +If you are using [CA Pinning](../admin/adding-nodes.mdx#obtain-a-ca-pin) +when adding new nodes, the CA pin will change after the rotation. Make sure you +use the *new* CA pin when adding nodes after rotation. ### Rotation phases