Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Simplify how-to guides #47586

Merged
merged 1 commit into from
Oct 17, 2024
Merged

Simplify how-to guides #47586

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 15 additions & 51 deletions docs/pages/admin-guides/access-controls/device-trust/device-management.mdx
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading