Skip to content

Commit

Permalink
Simplify how-to guides (#47586)
Browse files Browse the repository at this point in the history 
Closes #38931

Remove "Static" and "Dynamic" configuration branching. Use the dynamic
approach unless the guide already shows readers how to use the static
approach elsewhere, e.g., using `teleport db configure create`.

For example, in the AWS OpenSearch guide, creating a Teleport
configuration is required for the guide anyway, so this change uses only
the static approach.

Ignore edge cases where the branching has some qualities that are unique
to a specific guide:

- `application-access/cloud-apis/google-cloud.mdx`: includes branching
  on authentication preference type.
- `application-access/guides/connecting-apps.mdx` because it explains
  syntax differences between the static and dynamic approaches.
- `enroll-aws-databases/aws-cross-account.mdx`: branches using three
  tabs, so editing requires another approach than the one this change
  applies.

This change edits only how-to guides, not conceptual guides, since the
goal of a how-to guide is to get the user to an end state as quickly as
possible.
  • Loading branch information
@ptgott
ptgott authored Oct 17, 2024
1 parent c1a6e17 commit fdf9e25
Show file tree
Hide file tree
Showing 13 changed files with 104 additions and 494 deletions.
66 changes: 15 additions & 51 deletions docs/pages/admin-guides/access-controls/device-trust/device-management.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,11 +138,14 @@ For auto-enrollment to work, the following conditions must be met:
integration, like the [Jamf Pro integration](./jamf-integration.mdx).
- Auto-enrollment must be enabled in the cluster setting.

Enable auto-enrollment in your cluster settings:
Enable auto-enrollment in your cluster settings. To do so, modify the dynamic
config resource using the following command:

<Tabs dropDownCaption="Teleport Deployment">
<TabItem label="Dynamic Resources" options="Self-Hosted,Teleport Enterprise Cloud" >
Modify the dynamic config resource using `tctl edit cluster_auth_preference`:
```code
$ tctl edit cluster_auth_preference
```

Make the following change:

```diff
kind: cluster_auth_preference
Expand All @@ -156,22 +159,7 @@ spec:
+ auto_enroll: true
```

</TabItem>
<TabItem label="Static Config" options="Self-Hosted">
Edit the Auth Server's `teleport.yaml` file:

```diff
auth_service:
authentication:
# ...
device_trust:
+ auto_enroll: true
```

After saving the changes, restart the Teleport service.

</TabItem>
</Tabs>
Save and close your editor to apply your changes.

Once enabled, users with their device registered in Teleport will have their
device enrolled to Teleport in their next login.
Expand Down Expand Up @@ -244,18 +232,14 @@ To configure `ekcert_allowed_cas`, you must first obtain the CA certificate in
PEM format from the manufacturer of the TPM included in your devices. This step
varies from manufacturer to manufacturer.

After you obtain the CA certificate in PEM format, there are two ways of
configuring `ekcert_allowed_cas`:
After you obtain the CA certificate in PEM format, modify the dynamic config
resource using the following command:

- Statically using the Teleport configuration file. This is the simplest
option, but is not possible for Teleport Cloud clusters and not recommended
for clusters in a highly available configuration.
- Dynamically using `cluster_auth_preference` resource. This works with all
clusters and is the most flexible.
```code
$ tctl edit cluster_auth_preference
```

<Tabs dropDownCaption="Teleport Deployment">
<TabItem label="Dynamic Resources" options="Self-Hosted,Teleport Enterprise Cloud" >
Modify the dynamic config resource using `tctl edit cluster_auth_preference`:
Make the following change:

```diff
kind: cluster_auth_preference
Expand All @@ -274,27 +258,7 @@ spec:
+ -----END CERTIFICATE-----
```

</TabItem>
<TabItem label="Static Config" options="Self-Hosted">
Edit the Auth Server's `teleport.yaml` file and restart:

```diff
auth_service:
authentication:
...
device_trust:
+ ekcert_allowed_cas:
+ # The CA can be configured inline within the configuration file:
+ - |
+ -----BEGIN CERTIFICATE-----
+ --snip--
+ -----END CERTIFICATE-----
+ # Or, it can be configured in the configuration file using a path:
+ - /path/to/my/ekcert-ca.pem
```

</TabItem>
</Tabs>
Save and close your editor to apply your changes.

## Troubleshooting

Expand Down
47 changes: 11 additions & 36 deletions docs/pages/admin-guides/access-controls/device-trust/enforcing-device-trust.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,10 +96,13 @@ accesses.

To enable device mode `required` update your configuration as follows:

<Tabs dropDownCaption="Teleport Deployment">
<TabItem label="Dynamic Resources" options="Self-Hosted,Teleport Enterprise Cloud" >
Create a `cap.yaml` file or get the existing configuration using
`tctl get cluster_auth_preference`:
Edit your cluster authentication preference using the following command:

```code
$ tctl edit cluster_auth_preference
```

Make the following change:

```diff
kind: cluster_auth_preference
Expand All @@ -115,39 +118,11 @@ spec:
+ mode: "required" # add this line
```

Update the configuration:

```code
$ tctl create -f cap.yaml
cluster auth preference has been updated
```

You can also edit this configuration directly:

```code
$ tctl edit cluster_auth_preference
```

</TabItem>
<TabItem label="Static Config" options="Self-Hosted">
Edit the Auth Server's `teleport.yaml` file and restart all Auth Services:

```diff
auth_service:
authentication:
type: local
second_factor: "on"
webauthn:
rp_id: (=clusterDefaults.clusterName=)
device_trust:
+ mode: "required" # add this line
```

</TabItem>
</Tabs>
Save and close your editor to apply your changes.

Once the config is updated, SSH, Database and Kubernetes access without a trusted device will be forbidden.
For example, SSH access without a trusted device fails with the following error:
Once the config is updated, SSH, Database and Kubernetes access without a
trusted device will be forbidden. For example, SSH access without a trusted
device fails with the following error:

```code
$ tsh ssh (=clusterDefaults.nodeIP=)
Expand Down
74 changes: 27 additions & 47 deletions docs/pages/admin-guides/access-controls/guides/mfa-for-admin-actions.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,50 +56,30 @@ WebAuthn is the only form of second factor allowed.
for a wider range of cluster configurations.
</Notice>

<Tabs>
<TabItem label="Dynamic Resources" scope={["team", "cloud"]}>

Edit the `cluster_auth_preference` resource:

```code
$ tctl edit cap
```

Update the `cluster_auth_preference` definition to include the following content:

```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
# To make webauthn the only form of second factor allowed, set this field to 'webauthn'.
second_factor: "webauthn"
webauthn:
rp_id: example.com
```
Save and exit the file. `tctl` will update the remote definition:

```text
cluster auth preference has been updated
```

</TabItem>
<TabItem label="Static Config" scope={["oss", "enterprise"]}>
Edit the Auth Service's `teleport.yaml` file and restart all Auth Service instances:

```yaml
# snippet from /etc/teleport.yaml:
auth_service:
authentication:
type: local
# To make webauthn the only form of second factor allowed, set this field to 'webauthn'.
second_factor: "webauthn"
webauthn:
rp_id: example.com
```

</TabItem>
</Tabs>
Edit the `cluster_auth_preference` resource:

```code
$ tctl edit cap
```

Update the `cluster_auth_preference` definition to include the following content:

```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
# To make webauthn the only form of second factor allowed, set this field to 'webauthn'.
second_factor: "webauthn"
webauthn:
rp_id: example.com
```
Save and exit the file. `tctl` will update the remote definition:

```text
cluster auth preference has been updated
```

129 changes: 17 additions & 112 deletions docs/pages/admin-guides/access-controls/guides/passwordless.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,54 +119,17 @@ using `tsh login --proxy=example.com --auth=local` in order to get their first
passwordless registration.

To enable passwordless by default, add `connector_name: passwordless` to your
cluster configuration:
cluster configuration.

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
<Tabs>
<TabItem label="Static Config">
Auth Server `teleport.yaml` file:

```yaml
auth_service:
authentication:
type: local
second_factor: on
webauthn:
rp_id: example.com
connector_name: passwordless # passwordless by default
```
</TabItem>
<TabItem label="Dynamic resources">
Create a `cap.yaml` file or get the existing configuration using
`tctl get cluster_auth_preference`:

```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
webauthn:
rp_id: example.com
connector_name: passwordless # passwordless by default
```

Update the configuration:

```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```
</TabItem>
</Tabs>
</TabItem>
Edit your cluster authentication preference configuration using the following
command:

```code
$ tctl edit cluster_auth_preference
```

<TabItem scope={["cloud"]} label="Teleport Enterprise">
Create a `cap.yaml` file or get the existing configuration using
`tctl get cluster_auth_preference`:
Ensure that the configuration includes the `connector_name` field as shown
below:

```yaml
kind: cluster_auth_preference
Expand All @@ -181,16 +144,6 @@ spec:
connector_name: passwordless # passwordless by default
```
Update the configuration:

```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```
</TabItem>

</Tabs>

## Troubleshooting
### "Allow passwordless logins" doesn't appear
Expand Down Expand Up @@ -259,55 +212,15 @@ $ tsh webauthnwin diag
### Disable passwordless

If you want to forbid passwordless access to your cluster, add `passwordless:
false` to your configuration:
false` to your configuration. Edit your cluster authentication preference using
the following command:

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
<Tabs>
<TabItem label="Static Config">
Auth Server `teleport.yaml` file:

```yaml
# snippet from /etc/teleport.yaml:
auth_service:
authentication:
type: local
second_factor: on
webauthn:
rp_id: example.com
passwordless: false # disable passwordless
```
</TabItem>
<TabItem label="Dynamic resources">
Create a `cap.yaml` file or get the existing configuration using
`tctl get cluster_auth_preference`:

```yaml
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
webauthn:
rp_id: example.com
passwordless: false # disable passwordless
```

Update the configuration:

```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```
</TabItem>
</Tabs>
</TabItem>
```code
$ tctl edit cluster_auth_preference
```

<TabItem scope={["cloud"]} label="Teleport Enterprise">
Create a `cap.yaml` file or get the existing configuration using
`tctl get cluster_auth_preference`:
In your editor, ensure that your `cluster_auth_preference` includes a
`passwordless` field similar to the following:

```yaml
kind: cluster_auth_preference
Expand All @@ -322,15 +235,7 @@ spec:
passwordless: false # disable passwordless
```

Update the configuration:

```code
$ tctl create -f cap.yaml
# cluster auth preference has been updated
```
</TabItem>

</Tabs>
Save and close your editor to apply your changes.

### Why did my multi-factor authentication (MFA) device become a passkey?

Expand Down
Loading

0 comments on commit fdf9e25

Please sign in to comment.