Skip to content

Commit

Permalink
Backport #11419, #11913, and #10638 to v7
Browse files Browse the repository at this point in the history
Edit two guides for Cloud users

Backports #11419

* Edit two guides for Cloud users

PAM guide

- Minor style/clarity/grammar edits
- Use a ScopedBlock to hide Cloud-irrelevant information in the MOTD
  section
- The organization of the original guide was a bit scrambled, so I
  attempted to reorganize it into a form that made more sense.

Tsh guide

- Use ScopedBlocks to provide scope-relevant information.

- Mention Machine ID in the "### SSH certificates for automation"
  section.

- Misc grammar/clarity/style edits

* Respond to PR feedback

Clarify two guides and two intro pages

Backports #11913

* Clarify two guides and two intro pages

See #11841

Make the Adding Nodes guide more usable for Cloud

- Add a ca_pin preset
- Clarify that tctl must be run on the local machine for Cloud users
- Structure the guide as a step-by-step tutorial. The guide already
  included sequences of sample commands, so all this took was to rename
  headings according to the "Step n/d." format and move the CA pinning
  section into the section on starting the Node.
- Add environment variables to use for storing a CA pin and invite
  token to sample commands, plus piped commands to extract these
  strings from the output of tctl commands.
- Use a ScopedBlock to hide the Node Tunneling section for Cloud users
- Indicate that the --auth-server flag in "teleport start" requires a
  port.

Add intros to the Admin and Operations menu pages

- Clarify the purpose of the Admin Guides and Operations sections
  by adding an intro paragraph to each page. Since these sections are
  similar in scope, I added links from one to the other with statements
  about how the two sections differ.

- Replace lists of links with Tiles.

GitHub SSO

- Move the step to create an OAuth app out of the Prerequisites and
  into its own step. This makes it easier to give the instructions
  to use a specific callback URL proper space.
- Be more explicit about the rp_ip value.
- Add explicit instructions for logging in to the cluster after
  creating the auth preference, including screenshots of expected
  results.

* Fix wording and linter issues following PR review

* Respond to PR feedback

Remove a misleading instruction re: CA pinning. Also move some text
about CA pinning to a more appropriate location.

Edit four Access Controls pages for Cloud users

Backports #11826

* Edit four Access Controls pages for Cloud users

See #10638

Access Controls Getting Started guide

- Add a tabbed Prerequisites section for users of different scopes
- Use a ScopedBlock to show OIDC and SAML instructions as Tabs for
  commercial Teleport users and GitHub instructions for OSS Teleport
  users
- Light style/grammar/clarity edits

Role Templates

- Tabbed Prerequisites section for different scopes
- Adjust the visibility of minor details using ScopedBlocks

Locking

- Add a scoped Tabs component to the Prerequisites section
- Add a ScopedBlock to hide CLI- and config file-specific instructions
  from Cloud users.

WebAuthn

- Add scoped Tabs to the Prerequisites section
- Move Tabs with TabItems for static configurations and dynamic
  resources into ScopedBlocks. This way, we don't have to show
  static configuration instructions to Cloud users.
- Remove duplicate config field explanations.
- Minor style/grammar edits

* Respond to PR feedback

- Change verbiage re: belonging to a role
- Remove U2F migration section
  • Loading branch information
ptgott committed Apr 21, 2022
1 parent 393dcc2 commit 6790289
Show file tree
Hide file tree
Showing 15 changed files with 1,115 additions and 465 deletions.
3 changes: 2 additions & 1 deletion docs/config.json
Original file line number Diff line number Diff line change
Expand Up @@ -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="
Expand Down
Binary file added docs/img/github-sso-auth-screen.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/login-success.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
137 changes: 91 additions & 46 deletions docs/pages/access-controls/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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.

<Tabs>
<TabItem label="Open Source">
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`.
<ScopedBlock scope={["oss"]}>

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
Expand All @@ -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"]
```
</TabItem>
<TabItem label="Enterprise">
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: |
<?xml !!! Make sure to shift all lines in XML descriptor
with 4 spaces, otherwise things will not work
```code
$ tctl create github.yaml
```

</ScopedBlock>

<ScopedBlock scope={["enterprise", "cloud"]}>

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.

<Tabs>
<TabItem label="SAML">

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: |
<?xml !!! Make sure to shift all lines in XML descriptor
with 4 spaces, otherwise things will not work
```

Create the `saml` resource:

```code
$ tctl create okta.yaml
```

</TabItem>
</Tabs>
<TabItem label="OIDC">

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
```

</TabItem>
</Tabs>

</ScopedBlock>

## Step 3/3. Create a custom role

Expand All @@ -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:
Expand All @@ -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'
Expand All @@ -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
Expand Down
Loading

0 comments on commit 6790289

Please sign in to comment.