From 94aa3990fac0a6966ed23f4cbb54c3520f4bf67b Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Wed, 13 Apr 2022 13:01:08 -0400 Subject: [PATCH] Edit four Access Controls guides for Cloud users Backports #11838 * Edit four Access Controls guides for Cloud users See #10638 Per-session MFA - Add scoped Tabs to the Prerequisites section - Add a ScopedBlock so Cloud users don't see the option to enable per-session MFA via static config - Minor copy-edits and organization edits. For example, turn a section that refers to an example in another section into an Admonition. Dual Authorization - Add scoped Tabs to the Prerequisites - Use a scoped Notice for the edition warning - Style/clarity/grammar edits - Hide the Troubleshooting section for Cloud users Moderated Sessions - Change the edition warning to a scoped Notice. Since this guide is a conceptual guide rather than a step-by-step tutorial, there's no other scope-irrelevant information to hide. Impersonation - Add scoped Tabs to the Prerequisites - Used ScopedBlocks to hide minor scope-irrelevant details - Minor style/grammar/clarity edits * Respond to PR feedback * Respond to PR feedback --- .../access-controls/guides/dual-authz.mdx | 93 ++++++++++++++----- .../access-controls/guides/impersonation.mdx | 84 ++++++++++------- .../guides/moderated-sessions.mdx | 12 ++- .../guides/per-session-mfa.mdx | 73 +++++++++++++-- docs/pages/includes/plugins/rbac.mdx | 2 +- 5 files changed, 197 insertions(+), 67 deletions(-) diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx index 4d1ab509a5b03..8bcf0f87afb94 100644 --- a/docs/pages/access-controls/guides/dual-authz.mdx +++ b/docs/pages/access-controls/guides/dual-authz.mdx @@ -7,20 +7,20 @@ videoBanner: b_iqJm_o15I You can set up Teleport to require require the approval of multiple team members to perform some critical actions. Here are the most common scenarios: -- Improve security of your system and prevent one successful phishing attack from compromizing your system. +- Improve the security of your system and prevent one successful phishing attack from compromising your system. - Satisfy FedRAMP AC-3 Dual authorization control that requires approval of two authorized individuals. -Let's set up Teleport's access requests to require approval of -two team members for a privileged role `dbadmin`. +Let's set up Teleport's access requests to require the approval of two team members +for a privileged role `dbadmin`. - This guide requires a commercial edition of Teleport. The open source edition of Teleport only supports [Github](../../setup/admin/github-sso.mdx) as an SSO provider. - + The steps below describe how to use Teleport with Mattermost. You can also [integrate with many other providers](../../enterprise/workflow/index.mdx). @@ -28,8 +28,45 @@ two team members for a privileged role `dbadmin`. ## Prerequisites -- Installed [Teleport Enterprise](../../enterprise/introduction.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=) -- [Tctl enterprise admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=) + + + +- A running Teleport cluster. For details on how to set this up, see our Enterprise + [Getting Started](../../enterprise/getting-started.mdx) guide. + +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), + which you can download by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=). + To download these tools, visit the [Downloads](../../cloud/downloads.mdx) page. + + ```code + $ tctl version + # Teleport v(=cloud.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=cloud.version=) go(=teleport.golang=) + ``` + + + - Mattermost installed. - + ```yaml (!examples/resources/plugins/teleport-mattermost-cloud.toml!) ``` -## Dual authorization +## Step 2/3. Configure dual authorization -Alice and Ivan are reviewers - they can approve requests for assuming role `dbadmin`. -Bob is a devops and can assume `dbadmin` role if two members of the `reviewer` role -approved the request. +In this section, we will use an example to show you how to require dual +authorization for a user to assume a role. -Create `dbadmin`, `reviewer` and `devops` roles: +### Require dual authorization for a role + +Alice and Ivan are reviewers. They can approve requests for assuming role +`dbadmin`. Bob is a DevOps engineer and can assume the `dbadmin` role if two members +of the `reviewer` role approve the request. + +Create the following `dbadmin`, `reviewer` and `devops` roles: ```yaml kind: role @@ -159,9 +201,7 @@ spec: 'type': 'db' ``` -Example below creates local users Alice, Ivan and Bob. - -Bob does not have a role `dbadmin` assigned to him, but can create an access request for it. +The commands below create the local users Bob, Alice, and Ivan. ```code $ tctl users add bob@example.com --roles=devops @@ -169,7 +209,9 @@ $ tctl users add alice@example.com --roles=reviewer $ tctl users add ivan@example.com --roles=reviewer ``` -## Access Requests flow +### Create an access request + +Bob does not have a role `dbadmin` assigned to him, but can create an access request for it. Bob can create an access request for the `dbadmin` role in the Web UI or CLI: @@ -215,11 +257,16 @@ Bob can also assume granted access request roles using Web UI: ![Teleport Assume](../../../img/access-controls/dual-authz/teleport-7-bob-assume.png) + +{/* TODO: This H2 will show up in the table of contents when this section is invisible. +We need a way to hide invisible H2s from the TOC. */} + + ## Troubleshooting ### Cert errors in self-hosted deployments -You may be getting certificate errors if Teleport's auth server is missing an address in the server certificate: +You may be getting certificate errors if Teleport's Auth Service is missing an address in the server certificate: ```txt authentication handshake failed: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs @@ -229,9 +276,11 @@ authentication handshake failed: x509: cannot validate certificate for 127.0.0.1 x509: certificate is valid for,*.teleport.cluster.local, teleport.cluster.local, not example.com ``` -To fix the problem, update the auth service with a public address, and restart Teleport: +To fix the problem, update the Auth Service with a public address, and restart Teleport: ```yaml auth_service: public_addr: ['localhost:3025', 'example.com:3025'] ``` + + diff --git a/docs/pages/access-controls/guides/impersonation.mdx b/docs/pages/access-controls/guides/impersonation.mdx index cc722ffa3a437..8350b17bfb86a 100644 --- a/docs/pages/access-controls/guides/impersonation.mdx +++ b/docs/pages/access-controls/guides/impersonation.mdx @@ -3,8 +3,6 @@ title: Impersonating Teleport Users description: How to issue short-lived certs on behalf of Teleport users using impersonation. --- -# Impersonation - Sometimes users need to create short-lived certificates for non-interactive users, for example, CI/CD systems. Your programs interacting with Teleport may need to create their own authentication as well. Teleport's impersonation allows @@ -22,13 +20,13 @@ non-interactive CI/CD user Jenkins and a security scanner. ## Step 1/3: Create a CI/CD user and corresponding role -First, let's create a role called `jenkins`. Notice the `max_session_ttl` +First, we will create a role called `jenkins`. Notice the `max_session_ttl` parameter, which limits the cert duration for certificates issued to users with this role. As a rule of thumb, the shorter the TTL, the better. -Next, we'll create a user also named `jenkins` and assign the role to the user. +We will also create a user also named `jenkins` and assign the role to the user. -Save this file as `jenkins.yaml` to create the user and role: +Save this file as `jenkins.yaml`: ```yaml kind: role @@ -57,20 +55,15 @@ spec: roles: ['jenkins'] ``` - - Here and below follow along and create yaml resources using `tctl create -f`: +Create the resources: - ```code - $ tctl create -f jenkins.yaml - ``` - +```code +$ tctl create -f jenkins.yaml +``` ## Step 2/3: Create an impersonator role -Let's create a role `impersonator`. Users with this role will be permitted to +Next, we will create a role called `impersonator`. Users with this role will be permitted to impersonate the `jenkins` user and role. Save this role definition as `impersonator.yaml`: @@ -101,7 +94,13 @@ spec: '*': '*' ``` -Next, create an interactive user `alice` and assign the impersonator role so +Create the `role` resource: + +```code +$ tctl create -f impersonator.yaml +``` + +Next, create an interactive user named `alice` and assign the impersonator role so that `alice` can impersonate `jenkins`. ```code -$ tsh login --proxy=teleport.localhost --user=alice --auth=local +$ tsh login --proxy=proxy.example.com --user=alice --auth=local $ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h ``` + + + +```code +$ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local +$ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h +``` + + + Here is an example of how Alice can use the keys: ```code @@ -161,10 +172,10 @@ To prevent unintended consequences, Teleport defines the following impersonation being impersonated. - Even if the `jenkins` role could impersonate some other roles, Alice would not be able to use this permission. Teleport prevents recursive impersonation. -- Alice can get a new `jenkins` certificate with the same TTL, but metadata - updated, for example pointing to a different Teleport leaf cluster. Teleport - allows impersonated users to renew their certificates with the reduced scope - of the certificate. +- Alice can get a new `jenkins` certificate with the same TTL, but with the + metadata updated, for example, to point to a different Teleport leaf cluster. + Teleport allows impersonated users to renew their certificates with the + reduced scope of the certificate. ### Dynamic Impersonation @@ -175,7 +186,7 @@ based on matching labels. For example, suppose you wanted to define a `security-impersonator` role that allowed the impersonation of any users or roles with the label -`group: security`. This could be accomplished with the folowing role definition: +`group: security`. This could be accomplished with the following role definition: ```yaml kind: role @@ -246,11 +257,11 @@ the `group: security` label. $ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h ``` -**Matching user traits** +### Matching user traits We can also define impersonation rules by matching against user traits. -Here we update the `security-impersonator` role to allow for the impersonation +Here we updated the `security-impersonator` role to allow for the impersonation of any other users or roles where the `group` user trait contains the same value as the label on the role and/or user to impersonate: @@ -279,7 +290,7 @@ spec: ``` While user traits typically come from an external identity provider, we can test -with local user `alice` by manually updating Alices's account with traits. +with local user `alice` by manually updating Alice's account with traits. ```yaml kind: user @@ -298,12 +309,9 @@ Since Alice's `group` trait contains `security`, and the `security-scanner` user has a label of `group: security`, Alice will be able to impersonate the security scanner. - -Alice will need to log in again to receive the newly updated traits. - +Alice will need to log in again to receive the newly updated traits: + + ```code # Once Alice logs in again, she will receive a new certificate with updated roles. @@ -312,6 +320,18 @@ $ tsh login --proxy=teleport.example.com --user=alice --auth=local $ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h ``` + + + +```code +# Once Alice logs in again, she will receive a new certificate with updated roles. +$ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local +# Alice can now get a certificate for the security scanner +$ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h +``` + + + ### Filter fields Here is an explanation of the fields used in the `where` conditions within this guide. diff --git a/docs/pages/access-controls/guides/moderated-sessions.mdx b/docs/pages/access-controls/guides/moderated-sessions.mdx index 45472acda82e8..dfe3885643301 100644 --- a/docs/pages/access-controls/guides/moderated-sessions.mdx +++ b/docs/pages/access-controls/guides/moderated-sessions.mdx @@ -4,10 +4,18 @@ description: Moderated Sessions h1: Moderated Sessions --- + + + Moderated Sessions requires Teleport Enterprise or Teleport Cloud. + + + ## Introduction -Moderated Sessions allows Teleport administrators to -define requirements for other users to be present in a Server or Kubernetes Access session. Depending on the requirements, these users can observe the session in real time, participate in the session, and terminate the session at will. +Moderated Sessions allows Teleport administrators to define requirements for +other users to be present in a Server or Kubernetes Access session. Depending on +the requirements, these users can observe the session in real time, participate +in the session, and terminate the session at will. ### Use cases diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index 0b1a798ed1a5e..ae47b53b02bd9 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -4,8 +4,6 @@ description: Require MFA checks to initiate sessions. videoBanner: j8Ze7HhjFGw --- -# Per-session MFA - Teleport supports requiring additional multi-factor authentication checks when starting new: @@ -47,9 +45,10 @@ their on-disk Teleport certificates. - Second factor hardware device, such as YubiKey or SoloKey - A Web browser with [WebAuthn support]( https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) (if using - SSH from the Teleport Web UI) + SSH from the Teleport Web UI). + + - Teleport FIPS builds disable local users. To configure WebAuthn in order to use per-session MFA with FIPS builds, provide the following in your `teleport.yaml`: @@ -63,14 +62,21 @@ teleport: ``` -## Configuration +## Configure per-session MFA Per-session MFA can be enforced cluster-wide or only for some specific roles. ### Cluster-wide -To enforce MFA checks cluster-wide, update `teleport.yaml` on the Auth server -to contain: + + +To enforce MFA checks for all roles, edit your cluster authentication +configuration: + + + + +Update `teleport.yaml` on the Auth Server to contain: ```yaml auth_service: @@ -79,6 +85,51 @@ auth_service: require_session_mfa: yes ``` + + + +Create a file called `cap.yaml` with the following content: + +```yaml +kind: cluster_auth_preference +metadata: + name: cluster-auth-preference +spec: + require_session_mfa: true +version: v2 +``` + +Create the resource: + +```code +$ tctl create -f cap.yaml +``` + + + + + + + +Create a file called `cap.yaml` with the following content: + +```yaml +kind: cluster_auth_preference +metadata: + name: cluster-auth-preference +spec: + require_session_mfa: true +version: v2 +``` + +Create the resource: + +```code +$ tctl create -f cap.yaml +``` + + + ### Per role To enforce MFA checks for a specific role, update the role to contain: @@ -101,7 +152,7 @@ spec: Role-specific enforcement only applies when accessing resources matching a role's `allow` section. -#### Roles example +### Roles example Let's walk through an example of setting up per-session MFA checks for roles. @@ -179,9 +230,9 @@ $ tsh ssh prod3.example.com If per-session MFA was enabled cluster-wide, Jerry would be prompted for MFA even when logging into `dev1.example.com`. -## Database access MFA + -Database access supports per-connection MFA. When Jerry connects to the database +Database Access supports per-connection MFA. When Jerry connects to the database `prod-mysql-instance` (with label `env: prod`), he gets prompted for an MFA check for each `tsh db connect` call: @@ -204,6 +255,8 @@ $ tsh db connect prod-mysql-instance # mysql> ``` + + ## Limitations Current limitations for this feature are: diff --git a/docs/pages/includes/plugins/rbac.mdx b/docs/pages/includes/plugins/rbac.mdx index a620900449241..7ee71f95a7174 100644 --- a/docs/pages/includes/plugins/rbac.mdx +++ b/docs/pages/includes/plugins/rbac.mdx @@ -32,7 +32,7 @@ spec: -Create a non-interactive bot `access-plugin` user and role. +Create a non-interactive bot user and role called `access-plugin`. ```yaml kind: user