Skip to content

[v17] Update second_factors docs for v16 compatibility issue #54909

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

Merged
Joerger merged 2 commits into from
May 21, 2025
Merged

[v17] Update second_factors docs for v16 compatibility issue #54909

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ee4ed7a
Warn against second_factors in docs; Replace second_factor as the def…
Joerger May 16, 2025
7de7e6c
Merge branch 'branch/v17' into joerger/v17/second-factors-warning-docs
Joerger May 21, 2025
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
5 changes: 4 additions & 1 deletion api/proto/teleport/legacy/types/types.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2193,7 +2193,6 @@ message AuthPreferenceSpecV2 {
string Type = 1 [(gogoproto.jsontag) = "type"];

// SecondFactor is the type of mult-factor.
// Deprecated: Prefer using SecondFactors instead.
string SecondFactor = 2 [
deprecated = true,
(gogoproto.jsontag) = "second_factor,omitempty",
Expand Down Expand Up @@ -2297,6 +2296,10 @@ message AuthPreferenceSpecV2 {
// SecondFactors is a list of supported multi-factor types.
// 1 is "otp", 2 is "webauthn", 3 is "sso",
// If unspecified, the current default value is [1], or ["otp"].
//
// WARNING: only set SecondFactors if your cluster is fully upgraded to v17+.
Copy link
Copy Markdown
Contributor

@espadolini espadolini May 19, 2025

Choose a reason for hiding this comment

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

Suggested change
// WARNING: only set SecondFactors if your cluster is fully upgraded to v17+.
// WARNING: only set second_factors if your cluster is fully upgraded to v17+.

Copy link
Copy Markdown
Contributor Author

@Joerger Joerger May 19, 2025

Choose a reason for hiding this comment

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

Upper camel case is intentional here

Copy link
Copy Markdown
Contributor

@espadolini espadolini May 20, 2025

Choose a reason for hiding this comment

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

This ends up populating user facing documentation in the terraform docs tho.

Copy link
Copy Markdown
Contributor Author

@Joerger Joerger May 21, 2025

Choose a reason for hiding this comment

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

I see how that is awkward, but if anything that points to this type of docs generation being non-ideal. We would need to change line 2296 as well to get the right output for terraform docs:

second_factors (List of Number) SecondFactors is a list of supported multi-factor types...

// Due to a version compatibility bug, v16 teleport services do not properly
// handle this setting and may fail to start as a result.
repeated SecondFactorType SecondFactors = 21 [(gogoproto.jsontag) = "second_factors,omitempty"];

// StableUnixUserConfig contains the cluster-wide configuration for stable
Expand Down
5 changes: 4 additions & 1 deletion 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 @@ -112,7 +112,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factors: ["webauthn"]
second_factor: "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 @@ -253,7 +253,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_factors: ["webauthn"]` set in your `cluster_auth_preference`,
For example, if you have `second_factor: "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 @@ -54,7 +54,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factors: ["webauthn"]
second_factor: "webauthn"
webauthn:
rp_id: example.com
connector_name: headless # headless by default
Expand Down Expand Up @@ -85,7 +85,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factors: ["webauthn"]
second_factor: "webauthn"
webauthn:
rp_id: example.com
headless: false # disable Headless WebAuthn
Expand Down
2 changes: 1 addition & 1 deletion 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,7 +71,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factors: ["webauthn"]
second_factor: "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_factors: ["webauthn"]
second_factor: "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_factors: ["webauthn"]
second_factor: "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_factors: ["webauthn"]
second_factor: "webauthn"
webauthn:
rp_id: teleport.example.com
```
Expand Down
6 changes: 3 additions & 3 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, include "webauthn" as a second factor method.
second_factors: ["webauthn"]
#To enable WebAuthn support, set this field to 'on', 'optional' or 'webauthn'
second_factor: "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 @@ -472,7 +472,7 @@ Update the `cluster_auth_preference` definition to include the following content
name: cluster-auth-preference
spec:
type: local
second_factors: ["webauthn"]
second_factor: "webauthn"
webauthn:
rp_id: example.com
```
Expand Down
7 changes: 7 additions & 0 deletions docs/pages/admin-guides/access-controls/sso/sso.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,6 +515,13 @@ spec:
+ - sso
```

<Admonition type="warning">
Before using the new `second_factors` field instead of the legacy `second_factor`,
you must ensure that your Teleport cluster is fully upgraded to v17+. Due to a
version compatibility bug, v16 teleport services do not properly handle this setting
and may fail to start as a result.
</Admonition>

## Working with an external email identity

Along with sending groups, an SSO provider will also provide a user's email address.
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_factors: ["webauthn"]
second_factor: "webauthn"
webauthn:
rp_id: example.teleport.sh
```
Expand All @@ -68,7 +68,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factors: ["webauthn"]
second_factor: "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_factors: ["webauthn"]
second_factor: "webauthn"
webauthn:
rp_id: example.teleport.sh
version: v2
Expand Down
17 changes: 10 additions & 7 deletions docs/pages/reference/resources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,17 +231,20 @@ Global cluster configuration options for authentication.
metadata:
name: cluster-auth-preference
spec:
# Sets the type of second factor to use.
# Possible values: "on", "otp" and "webauthn"
# If "on" is set, all MFA protocols are supported.
second_factor: "on"

# Sets the list of allowed second factors for the cluster.
# Possible values: "otp", "webauthn", and "sso".
# 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.
#
# Prefer setting second_factors instead.
#second_factor: "webauthn"
# WARNING: only use second_factors if your cluster is fully upgraded to v17+.
# Due to a version compatibility bug, v16 teleport services do not properly
# handle this setting and may fail to start as a result.
#
# second_factors: ["webauthn", "otp"]

# 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 @@ -41,8 +41,8 @@ Optional:
- `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. Deprecated: Prefer using SecondFactors instead.
- `second_factors` (List of Number) SecondFactors is a list of supported multi-factor types. 1 is "otp", 2 is "webauthn", 3 is "sso", If unspecified, the current default value is [1], or ["otp"].
- `second_factor` (String) SecondFactor is the type of mult-factor.
- `second_factors` (List of Number) SecondFactors is a list of supported multi-factor types. 1 is "otp", 2 is "webauthn", 3 is "sso", If unspecified, the current default value is [1], or ["otp"]. WARNING: only set SecondFactors if your cluster is fully upgraded to v17+. Due to a version compatibility bug, v16 teleport services do not properly handle this setting and may fail to start as a result.
- `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".
- `stable_unix_user_config` (Attributes) StableUnixUserConfig contains the cluster-wide configuration for stable UNIX users. (see [below for nested schema](#nested-schema-for-specstable_unix_user_config))
- `type` (String) Type is the type of authentication.
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 @@ -60,8 +60,8 @@ Optional:
- `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. Deprecated: Prefer using SecondFactors instead.
- `second_factors` (List of Number) SecondFactors is a list of supported multi-factor types. 1 is "otp", 2 is "webauthn", 3 is "sso", If unspecified, the current default value is [1], or ["otp"].
- `second_factor` (String) SecondFactor is the type of mult-factor.
- `second_factors` (List of Number) SecondFactors is a list of supported multi-factor types. 1 is "otp", 2 is "webauthn", 3 is "sso", If unspecified, the current default value is [1], or ["otp"]. WARNING: only set SecondFactors if your cluster is fully upgraded to v17+. Due to a version compatibility bug, v16 teleport services do not properly handle this setting and may fail to start as a result.
- `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".
- `stable_unix_user_config` (Attributes) StableUnixUserConfig contains the cluster-wide configuration for stable UNIX users. (see [below for nested schema](#nested-schema-for-specstable_unix_user_config))
- `type` (String) Type is the type of authentication.
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_factors` is `["webauthn"]`, Teleport
If `teleport.auth_service.authentication.second_factor` 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