From ee4ed7ae952cdc837add732aefde6256de6195e4 Mon Sep 17 00:00:00 2001 From: joerger Date: Fri, 16 May 2025 16:24:06 -0700 Subject: [PATCH] Warn against second_factors in docs; Replace second_factor as the default preferred value in docs. --- api/proto/teleport/legacy/types/types.proto | 5 ++++- api/types/types.pb.go | 5 ++++- .../device-trust/enforcing-device-trust.mdx | 2 +- .../guides/hardware-key-support.mdx | 2 +- .../access-controls/guides/headless.mdx | 4 ++-- .../guides/mfa-for-admin-actions.mdx | 2 +- .../access-controls/guides/passwordless.mdx | 4 ++-- .../access-controls/guides/per-session-mfa.mdx | 2 +- .../access-controls/guides/webauthn.mdx | 6 +++--- .../admin-guides/access-controls/sso/sso.mdx | 7 +++++++ .../access-controls/authentication.mdx | 6 +++--- docs/pages/reference/resources.mdx | 17 ++++++++++------- .../data-sources/auth_preference.mdx | 4 ++-- .../resources/auth_preference.mdx | 4 ++-- docs/pages/reference/user-types.mdx | 2 +- .../terraform/tfschema/types_terraform.go | 4 ++-- 16 files changed, 46 insertions(+), 30 deletions(-) diff --git a/api/proto/teleport/legacy/types/types.proto b/api/proto/teleport/legacy/types/types.proto index bdccb3c1cf294..468d8291eb946 100644 --- a/api/proto/teleport/legacy/types/types.proto +++ b/api/proto/teleport/legacy/types/types.proto @@ -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", @@ -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+. + // 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 diff --git a/api/types/types.pb.go b/api/types/types.pb.go index 8e5fca76c0c7c..34ebec17647f0 100644 --- a/api/types/types.pb.go +++ b/api/types/types.pb.go @@ -6756,7 +6756,6 @@ type AuthPreferenceSpecV2 struct { // Type is the type of authentication. Type string `protobuf:"bytes,1,opt,name=Type,proto3" json:"type"` // SecondFactor is the type of mult-factor. - // Deprecated: Prefer using SecondFactors instead. SecondFactor github_com_gravitational_teleport_api_constants.SecondFactorType `protobuf:"bytes,2,opt,name=SecondFactor,proto3,casttype=github.com/gravitational/teleport/api/constants.SecondFactorType" json:"second_factor,omitempty"` // Deprecated: Do not use. // ConnectorName is the name of the OIDC or SAML connector. If this value is // not set the first connector in the backend will be used. @@ -6808,6 +6807,10 @@ type AuthPreferenceSpecV2 struct { // 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. SecondFactors []SecondFactorType `protobuf:"varint,21,rep,packed,name=SecondFactors,proto3,enum=types.SecondFactorType" json:"second_factors,omitempty"` // StableUnixUserConfig contains the cluster-wide configuration for stable // UNIX users. diff --git a/docs/pages/admin-guides/access-controls/device-trust/enforcing-device-trust.mdx b/docs/pages/admin-guides/access-controls/device-trust/enforcing-device-trust.mdx index d1b957cc9e7f9..1521d4445f186 100644 --- a/docs/pages/admin-guides/access-controls/device-trust/enforcing-device-trust.mdx +++ b/docs/pages/admin-guides/access-controls/device-trust/enforcing-device-trust.mdx @@ -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: diff --git a/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx b/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx index 2b335d672cdd8..9701354ff36b6 100644 --- a/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx +++ b/docs/pages/admin-guides/access-controls/guides/hardware-key-support.mdx @@ -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: diff --git a/docs/pages/admin-guides/access-controls/guides/headless.mdx b/docs/pages/admin-guides/access-controls/guides/headless.mdx index 3500b087800ac..6f2e89424b16e 100644 --- a/docs/pages/admin-guides/access-controls/guides/headless.mdx +++ b/docs/pages/admin-guides/access-controls/guides/headless.mdx @@ -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 @@ -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 diff --git a/docs/pages/admin-guides/access-controls/guides/mfa-for-admin-actions.mdx b/docs/pages/admin-guides/access-controls/guides/mfa-for-admin-actions.mdx index c4ff9b5818318..9740af74bb5bc 100644 --- a/docs/pages/admin-guides/access-controls/guides/mfa-for-admin-actions.mdx +++ b/docs/pages/admin-guides/access-controls/guides/mfa-for-admin-actions.mdx @@ -71,7 +71,7 @@ metadata: name: cluster-auth-preference spec: type: local - second_factors: ["webauthn"] + second_factor: "webauthn" webauthn: rp_id: example.com ``` diff --git a/docs/pages/admin-guides/access-controls/guides/passwordless.mdx b/docs/pages/admin-guides/access-controls/guides/passwordless.mdx index bae26d513f4a8..e23944e694b6b 100644 --- a/docs/pages/admin-guides/access-controls/guides/passwordless.mdx +++ b/docs/pages/admin-guides/access-controls/guides/passwordless.mdx @@ -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 @@ -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 diff --git a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx index d22683be7adcb..3cd8b63db9853 100644 --- a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx @@ -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 ``` diff --git a/docs/pages/admin-guides/access-controls/guides/webauthn.mdx b/docs/pages/admin-guides/access-controls/guides/webauthn.mdx index d7683e3249657..fe1ae7ae454c4 100644 --- a/docs/pages/admin-guides/access-controls/guides/webauthn.mdx +++ b/docs/pages/admin-guides/access-controls/guides/webauthn.mdx @@ -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 @@ -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 ``` diff --git a/docs/pages/admin-guides/access-controls/sso/sso.mdx b/docs/pages/admin-guides/access-controls/sso/sso.mdx index d5f2382e21d6b..c64f08c4402ab 100644 --- a/docs/pages/admin-guides/access-controls/sso/sso.mdx +++ b/docs/pages/admin-guides/access-controls/sso/sso.mdx @@ -515,6 +515,13 @@ spec: + - sso ``` + + 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. + + ## Working with an external email identity Along with sending groups, an SSO provider will also provide a user's email address. diff --git a/docs/pages/reference/access-controls/authentication.mdx b/docs/pages/reference/access-controls/authentication.mdx index 8819449d86b66..07ed7c51e0d9e 100644 --- a/docs/pages/reference/access-controls/authentication.mdx +++ b/docs/pages/reference/access-controls/authentication.mdx @@ -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 ``` @@ -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 @@ -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 diff --git a/docs/pages/reference/resources.mdx b/docs/pages/reference/resources.mdx index 3c7db6a21c298..1d3c8fb6accef 100644 --- a/docs/pages/reference/resources.mdx +++ b/docs/pages/reference/resources.mdx @@ -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: "" diff --git a/docs/pages/reference/terraform-provider/data-sources/auth_preference.mdx b/docs/pages/reference/terraform-provider/data-sources/auth_preference.mdx index 36b821618c116..fd1c3ec8984d3 100644 --- a/docs/pages/reference/terraform-provider/data-sources/auth_preference.mdx +++ b/docs/pages/reference/terraform-provider/data-sources/auth_preference.mdx @@ -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. diff --git a/docs/pages/reference/terraform-provider/resources/auth_preference.mdx b/docs/pages/reference/terraform-provider/resources/auth_preference.mdx index 9d67636687f5b..f8539c0922ccf 100644 --- a/docs/pages/reference/terraform-provider/resources/auth_preference.mdx +++ b/docs/pages/reference/terraform-provider/resources/auth_preference.mdx @@ -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. diff --git a/docs/pages/reference/user-types.mdx b/docs/pages/reference/user-types.mdx index 0b0f03e31b985..d8b88ebdfa352 100644 --- a/docs/pages/reference/user-types.mdx +++ b/docs/pages/reference/user-types.mdx @@ -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. diff --git a/integrations/terraform/tfschema/types_terraform.go b/integrations/terraform/tfschema/types_terraform.go index e42d17937bd43..4fbbc5538d5a8 100644 --- a/integrations/terraform/tfschema/types_terraform.go +++ b/integrations/terraform/tfschema/types_terraform.go @@ -1468,13 +1468,13 @@ func GenSchemaAuthPreferenceV2(ctx context.Context) (github_com_hashicorp_terraf }, "second_factor": { Computed: true, - Description: "SecondFactor is the type of mult-factor. Deprecated: Prefer using SecondFactors instead.", + Description: "SecondFactor is the type of mult-factor.", Optional: true, PlanModifiers: []github_com_hashicorp_terraform_plugin_framework_tfsdk.AttributePlanModifier{github_com_hashicorp_terraform_plugin_framework_tfsdk.UseStateForUnknown()}, Type: github_com_hashicorp_terraform_plugin_framework_types.StringType, }, "second_factors": { - Description: "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\"].", + Description: "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.", Optional: true, Type: github_com_hashicorp_terraform_plugin_framework_types.ListType{ElemType: github_com_hashicorp_terraform_plugin_framework_types.Int64Type}, },