Document second_factors field (#49016)

* Document second_factors; Update test plan. * Update proto comment; Update terraform docs. * Clarify second_factors reference. * Fix docs lint. * Address comments. * Address marco's comment.
gravitational · Jan 6, 2025 · 3ebf269 · 3ebf269
1 parent f650376
commit 3ebf269
Show file tree

Hide file tree

Showing 18 changed files with 1,971 additions and 1,952 deletions.
diff --git a/.github/ISSUE_TEMPLATE/webtestplan.md b/.github/ISSUE_TEMPLATE/webtestplan.md
@@ -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
 
@@ -808,16 +807,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.

diff --git a/api/proto/teleport/legacy/types/types.proto b/api/proto/teleport/legacy/types/types.proto
@@ -2134,7 +2134,9 @@ 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",
     (gogoproto.casttype) = "github.com/gravitational/teleport/api/constants.SecondFactorType"
   ];
@@ -2233,7 +2235,9 @@ message AuthPreferenceSpecV2 {
   // 1 is "legacy", 2 is "balanced-v1", 3 is "fips-v1", 4 is "hsm-v1".
   SignatureAlgorithmSuite signature_algorithm_suite = 20;
 
-  // SecondFactors is a list of supported second factor types.
+  // 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"].
   repeated SecondFactorType SecondFactors = 21 [(gogoproto.jsontag) = "second_factors,omitempty"];
 }
 

diff --git a/api/types/types.pb.go b/api/types/types.pb.go
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
@@ -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:

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
@@ -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:
 

diff --git a/docs/pages/admin-guides/access-controls/guides/headless.mdx b/docs/pages/admin-guides/access-controls/guides/headless.mdx
@@ -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
@@ -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

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
@@ -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
 ```

diff --git 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_factor: "on"
+  second_factors: ["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_factor: "on"
+  second_factors: ["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
@@ -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
 ```

diff --git 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, 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
@@ -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
   ```

diff --git a/docs/pages/admin-guides/infrastructure-as-code/infrastructure-as-code.mdx b/docs/pages/admin-guides/infrastructure-as-code/infrastructure-as-code.mdx
@@ -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`|

diff --git a/docs/pages/includes/config-reference/auth-service.yaml b/docs/pages/includes/config-reference/auth-service.yaml
@@ -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", "webauthn", and "sso". 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.

diff --git 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_factor: on
+      second_factors: ["webauthn"]
       webauthn:
         rp_id: example.teleport.sh
   ```
@@ -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
@@ -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

diff --git a/docs/pages/reference/resources.mdx b/docs/pages/reference/resources.mdx
@@ -222,10 +222,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", "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.
-  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: ""

diff --git 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.
-- `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 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"].
 - `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))

diff --git 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.
-- `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 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"].
 - `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))

diff --git 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_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.
 

diff --git a/integrations/terraform/tfschema/types_terraform.go b/integrations/terraform/tfschema/types_terraform.go