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

Document second_factors field #49016

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
+55 −37
Open

Document second_factors field #49016

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eb913a7
Document second_factors; Update test plan.
Joerger Nov 14, 2024
80ef4ca
Update proto comment; Update terraform docs.
Joerger Nov 14, 2024
57019df
Clarify second_factors reference.
Joerger Nov 14, 2024
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
21 changes: 10 additions & 11 deletions .github/ISSUE_TEMPLATE/webtestplan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,10 +123,9 @@ All actions should require re-authn with a webauthn device.
For each, test the invite, reset, and login flows

- [ ] Verify that input fields validates
- [ ] Verify with `second_factor` type to `off`
- [ ] Verify with `second_factor` type to `otp`, requires otp
- [ ] Verify with `second_factor` type to `webauthn`, requires hardware key
- [ ] Verify with `second_factor` type to `on`, requires a MFA device
- [ ] Verify with `second_factors` set to `["otp"]`, requires otp
- [ ] Verify with `second_factors` set to `["webauthn"]`, requires hardware key
- [ ] Verify with `second_factors` set to `["webauthn", "otp"]`, requires a MFA device
- [ ] Verify that error message is shown if an invite/reset is expired/invalid
- [ ] Verify that account is locked after several unsuccessful login attempts

Expand Down Expand Up @@ -807,16 +806,16 @@ Add the following to enable read access to trusted clusters
- Auth methods
- Verify that the app supports clusters using different auth settings
(`auth_service.authentication` in the cluster config):
- [ ] `type: local`, `second_factor: "otp"`
- [ ] `type: local`, `second_factors: ["otp"]`
- [ ] Test per-session MFA items listed later in the test plan.
- [ ] `type: local`, `second_factor: "webauthn"`,
- [ ] `type: local`, `second_factors: ["webauthn"]`,
- [ ] Test per-session MFA items listed later in the test plan.
- [ ] `type: local`, `second_factor: "webauthn"`, log in passwordlessly with hardware key
- [ ] `type: local`, `second_factor: "webauthn"`, log in passwordlessly with touch ID
- [ ] `type: local`, `second_factor: "on"`, log in with OTP
- [ ] `type: local`, `second_factors: ["webauthn"]`, log in passwordlessly with hardware key
- [ ] `type: local`, `second_factors: ["webauthn"]`, log in passwordlessly with touch ID
- [ ] `type: local`, `second_factors: ["webauthn", "otp"]`, log in with OTP
- [ ] Test per-session MFA items listed later in the test plan.
- [ ] `type: local`, `second_factor: "on"`, log in with hardware key
- [ ] `type: local`, `second_factor: "on"`, log in with passwordless auth
- [ ] `type: local`, `second_factors: ["webauthn", "otp"]`, log in with hardware key
- [ ] `type: local`, `second_factors: ["webauthn", "otp"]`, log in with passwordless auth
- [ ] Verify that the passwordless credential picker works.
- To make the picker show up, you need to add the same MFA device with passwordless
capabilities to multiple users.
Expand Down
3 changes: 3 additions & 0 deletions api/proto/teleport/legacy/types/types.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2000,6 +2000,7 @@ message AuthPreferenceSpecV2 {
string Type = 1 [(gogoproto.jsontag) = "type"];

// SecondFactor is the type of mult-factor.
// Deprecated: Prefer setting SecondFactors instead.
string SecondFactor = 2 [
(gogoproto.jsontag) = "second_factor,omitempty",
(gogoproto.casttype) = "github.com/gravitational/teleport/api/constants.SecondFactorType"
Expand Down Expand Up @@ -2100,6 +2101,8 @@ message AuthPreferenceSpecV2 {
SignatureAlgorithmSuite signature_algorithm_suite = 20;

// SecondFactors is a list of supported second factor types.
// 1 is "otp", 2 is "webauthn", 3 is "sso",
// If unspecified, the current default value is [1], or ["otp"].
repeated SecondFactorType SecondFactors = 21 [(gogoproto.jsontag) = "second_factors,omitempty"];
}

Expand Down
3 changes: 3 additions & 0 deletions api/types/types.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion 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 @@ -111,7 +111,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: (=clusterDefaults.clusterName=)
device_trust:
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,7 +280,7 @@ Yubikey for Hardware Key support, you might get an error on rare occasions.
Depending on your settings, you might be asked to tap your Yubikey many times.
Each tap is necessary to safely authenticate you.

For example, if you have `second_factor: webauthn` set in your `cluster_auth_preference`,
For example, if you have `second_factors: ["webauthn"]` set in your `cluster_auth_preference`,
and `require_session_mfa: hardware_key_touch` set on your role,
you'll see the following output when you first sign in:

Expand Down
4 changes: 2 additions & 2 deletions docs/pages/admin-guides/access-controls/guides/headless.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: example.com
connector_name: headless # headless by default
Expand Down Expand Up @@ -83,7 +83,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: example.com
headless: false # disable Headless WebAuthn
Expand Down
3 changes: 1 addition & 2 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 @@ -71,8 +71,7 @@ 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"
second_factors: ["webauthn"]
webauthn:
rp_id: example.com
```
Expand Down
4 changes: 2 additions & 2 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 @@ -138,7 +138,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: example.com
connector_name: passwordless # passwordless by default
Expand Down Expand Up @@ -229,7 +229,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: example.com
passwordless: false # disable passwordless
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ per-session MFA with FIPS builds, provide the following in your `teleport.yaml`:
teleport:
auth_service:
local_auth: false
second_factor: on
second_factors: ["webauthn"]
webauthn:
rp_id: teleport.example.com
```
Expand Down
7 changes: 3 additions & 4 deletions docs/pages/admin-guides/access-controls/guides/webauthn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ Teleport configuration as below:
name: cluster-auth-preference
spec:
type: local
# To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
second_factor: "on"
# To enable WebAuthn support, include "webauthn" as a second factor method.
second_factors: ["webauthn"]
webauthn:
# Required, replace with proxy web address (example.com, example.teleport.sh).
# rp_id is the public domain of the Teleport Proxy Service, *excluding* protocol
Expand Down Expand Up @@ -469,8 +469,7 @@ Update the `cluster_auth_preference` definition to include the following content
name: cluster-auth-preference
spec:
type: local
# To make webauthn the only form of multi-factor allowed, set this field to 'webauthn'.
second_factor: "webauthn"
second_factors: ["webauthn"]
webauthn:
rp_id: example.com
```
Expand Down
1 change: 1 addition & 0 deletions docs/pages/admin-guides/infrastructure-as-code/infrastructure-as-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,7 @@ static configuration file:
|---|---|
|`spec.type`|`auth_service.authentication.type`|
|`spec.second_factor`|`auth_service.authentication.second_factor`|
|`spec.second_factors`|`auth_service.authentication.second_factors`|
|`spec.connector_name`|`auth_service.authentication.connector_name`
|`spec.u2f`|`auth_service.authentication.u2f`|
|`spec.disconnect_expired_cert`|`auth_service.disconnect_expired_cert`|
Expand Down
9 changes: 8 additions & 1 deletion docs/pages/includes/config-reference/auth-service.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,11 +156,18 @@ auth_service:
# Possible values: true, false, "hardware_key", "hardware_key_touch".
# Defaults to false.
require_session_mfa: false

# second_factors is the list of allowed second factors for the cluster.
# Possible values: "otp" and "webauthn". Order does not matter.
# Defaults to ["otp"].
second_factors: ["webauthn", "otp"]

# second_factor can be 'on', 'otp' or 'webauthn'.
# - 'on' requires either otp or webauthn second factor.
# - 'otp' and 'webauthn' require the corresponding second factor.
second_factor: otp
#
# Prefer setting second_factors instead.
#second_factor: otp

# Sets whether passwordless authentication is allowed.
# Passwordless requires WebAuthn.
Expand Down
6 changes: 3 additions & 3 deletions docs/pages/reference/access-controls/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Add the following to your Teleport configuration file, which is stored in
auth_service:
authentication:
type: local
second_factor: on
second_factors: ["webauthn"]
webauthn:
rp_id: example.teleport.sh
```
Expand All @@ -68,7 +68,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: example.teleport.sh
version: v2
Expand Down Expand Up @@ -102,7 +102,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: example.teleport.sh
version: v2
Expand Down
11 changes: 9 additions & 2 deletions docs/pages/reference/resources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,10 +247,17 @@ Global cluster configuration options for authentication.
metadata:
name: cluster-auth-preference
spec:
# Sets the type of second factor to use.
# Sets the list of allowed second factors for the cluster.
# Possible values: "otp" and "webauthn".
# Defaults to ["otp"].
second_factors: ["webauthn", "otp"]
# second_factors is the list of allowed second factors for the cluster.
# Possible values: "on", "otp" and "webauthn"
# If "on" is set, all MFA protocols are supported.
second_factor: "otp"
#
# Prefer setting second_factors instead.
#second_factor: "webauthn"
# The name of the OIDC or SAML connector. if this is not set, the first connector in the backend is used.
connector_name: ""
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/reference/terraform-provider/data-sources/auth_preference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@
- `message_of_the_day` (String)
- `okta` (Attributes) Okta is a set of options related to the Okta service in Teleport. Requires Teleport Enterprise. (see [below for nested schema](#nested-schema-for-specokta))
- `require_session_mfa` (Number) RequireMFAType is the type of MFA requirement enforced for this cluster. 0 is "OFF", 1 is "SESSION", 2 is "SESSION_AND_HARDWARE_KEY", 3 is "HARDWARE_KEY_TOUCH", 4 is "HARDWARE_KEY_PIN", 5 is "HARDWARE_KEY_TOUCH_AND_PIN".
- `second_factor` (String) SecondFactor is the type of mult-factor.
- `second_factors` (List of Number) SecondFactors is a list of supported second factor types.
- `second_factor` (String) SecondFactor is the type of mult-factor. Deprecated: Prefer setting SecondFactors instead.
- `second_factors` (List of Number) SecondFactors is a list of supported second factor types. 1 is "otp", 2 is "webauthn", 3 is "sso", If unspecified, the current default value is [1], or ["otp"].

Check failure on line 44 in docs/pages/reference/terraform-provider/data-sources/auth_preference.mdx

View workflow job for this annotation

GitHub Actions / Lint docs prose style 

[vale] reported by reviewdog 🐶
[messaging.consistent-terms] For consistent product messaging in the docs, use 'multi-factor' instead of 'second factor'.

Raw Output:
{"message": "[messaging.consistent-terms] For consistent product messaging in the docs, use 'multi-factor' instead of 'second factor'.", "location": {"path": "docs/pages/reference/terraform-provider/data-sources/auth_preference.mdx", "range": {"start": {"line": 44, "column": 74}}}, "severity": "ERROR"}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have to say List of Number?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is automatically generated by terraform-plugin-docs - https://github.com/hashicorp/terraform-plugin-docs/blob/2004e44ee970c07f78889f7525f794c8d3654dfc/internal/schemamd/write_type.go#L51C4-L51C5

- `signature_algorithm_suite` (Number) SignatureAlgorithmSuite is the configured signature algorithm suite for the cluster. If unspecified, the current default value is "legacy". 1 is "legacy", 2 is "balanced-v1", 3 is "fips-v1", 4 is "hsm-v1".
- `type` (String) Type is the type of authentication.
- `u2f` (Attributes) U2F are the settings for the U2F device. (see [below for nested schema](#nested-schema-for-specu2f))
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/reference/terraform-provider/resources/auth_preference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@
- `message_of_the_day` (String)
- `okta` (Attributes) Okta is a set of options related to the Okta service in Teleport. Requires Teleport Enterprise. (see [below for nested schema](#nested-schema-for-specokta))
- `require_session_mfa` (Number) RequireMFAType is the type of MFA requirement enforced for this cluster. 0 is "OFF", 1 is "SESSION", 2 is "SESSION_AND_HARDWARE_KEY", 3 is "HARDWARE_KEY_TOUCH", 4 is "HARDWARE_KEY_PIN", 5 is "HARDWARE_KEY_TOUCH_AND_PIN".
- `second_factor` (String) SecondFactor is the type of mult-factor.
- `second_factors` (List of Number) SecondFactors is a list of supported second factor types.
- `second_factor` (String) SecondFactor is the type of mult-factor. Deprecated: Prefer setting SecondFactors instead.
- `second_factors` (List of Number) SecondFactors is a list of supported second factor types. 1 is "otp", 2 is "webauthn", 3 is "sso", If unspecified, the current default value is [1], or ["otp"].

Check failure on line 63 in docs/pages/reference/terraform-provider/resources/auth_preference.mdx

View workflow job for this annotation

GitHub Actions / Lint docs prose style 

[vale] reported by reviewdog 🐶
[messaging.consistent-terms] For consistent product messaging in the docs, use 'multi-factor' instead of 'second factor'.

Raw Output:
{"message": "[messaging.consistent-terms] For consistent product messaging in the docs, use 'multi-factor' instead of 'second factor'.", "location": {"path": "docs/pages/reference/terraform-provider/resources/auth_preference.mdx", "range": {"start": {"line": 63, "column": 74}}}, "severity": "ERROR"}
- `signature_algorithm_suite` (Number) SignatureAlgorithmSuite is the configured signature algorithm suite for the cluster. If unspecified, the current default value is "legacy". 1 is "legacy", 2 is "balanced-v1", 3 is "fips-v1", 4 is "hsm-v1".
- `type` (String) Type is the type of authentication.
- `u2f` (Attributes) U2F are the settings for the U2F device. (see [below for nested schema](#nested-schema-for-specu2f))
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/reference/user-types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ authentication method required by the upstream SSO provider. Teleport is not
aware of the authentication method not the user credentials, it trusts the IdP
response.

If `teleport.auth_service.authentication.second_factor` is `webauthn`, Teleport
If `teleport.auth_service.authentication.second_factors` is `["webauthn"]`, Teleport
might ask for an additional MFA for administrative actions. This protects
against IdP compromise.

Expand Down
4 changes: 2 additions & 2 deletions integrations/terraform/tfschema/types_terraform.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading