Merge branch 'master' into tcsc/idc-res-ar-docs

docs/cspell.json

@@ -949,6 +949,7 @@
     "topk",
     "tpmrm",
     "trustedclusters",
+    "trustedclustersv2",
     "trustpolicy",
     "truststore",
     "tshd",

docs/pages/admin-guides/access-controls/sso/sso.mdx

@@ -213,7 +213,7 @@ spec:
       - '2001:db8::/96'
 ```
 
-## Configuring SSO
+## Configuring SSO for login
 
 Teleport works with SSO providers by relying on the concept of an
 **authentication connector**. An authentication connector is a configuration
@@ -411,6 +411,116 @@ values to match your identity provider:
 
 At this time, the `spec.provider` field should not be set for any other identity providers.
 
+## Configuring SSO for MFA checks
+
+Teleport administrators can configure Teleport to delegate MFA checks to an 
+SSO provider as an alternative to registering MFA devices directly with the Teleport cluster.
+This allows Teleport users to use MFA devices and custom flows configured in the SSO provider
+to carry out privileged actions in Teleport, such as:
+
+- [Per-session MFA](../guides/per-session-mfa.mdx)
+- [Moderated sessions](../guides/moderated-sessions.mdx)
+- [Admin actions](../guides/mfa-for-admin-actions.mdx)
+
+Administrators may want to consider enabling this feature in order to:
+
+- Make all authentication (login and MFA) go through the IDP, reducing administrative overhead
+- Make custom MFA flows, such as prompting for 2 distinct devices for a single MFA check
+- Integrate with non-webauthn devices supported directly by your IDP
+
+<Admonition type="note">
+  SSO MFA is an enterprise feature. Only OIDC and SAML auth connectors are supported.
+</Admonition>
+
+### Configure the IDP App / Client
+
+There is no standardized MFA flow unlike there is with SAML/OIDC 
+login, so each IDP may offer zero, one, or more ways to offer MFA checks. 
+
+Generally, these offerings will fall under one of the following cases:
+
+1. Use a separate IDP app for MFA:
+
+You can create a separate IDP app with a custom MFA flow. For example, with
+Auth0 (OIDC), you can create a separate app with a custom [Auth0 Action](https://auth0.com/docs/customize/actions)
+which prompts for MFA for an active OIDC session.
+
+2. Use the same IDP app for MFA:
+
+Some IDPs provide a way to fork to different flows using the same IDP app.
+For example, with Okta (OIDC), you can provide `acr_values: ["phr"]` to 
+[enforce phishing resistant authentication](https://developer.okta.com/docs/guides/step-up-authentication/main/#predefined-parameter-values).
+
+For a simpler approach, you could use the same IDP app for both login and MFA
+with no adjustments. For Teleport MFA checks, the user will be required to
+relogin through the IDP with username, password, and MFA if required.
+
+<Admonition type="warning">
+  While the customizability of SSO MFA presents multiple secure options previously
+  unavailable to administrators, it also presents the possibility of insecure
+  misconfigurations. Therefore, we strongly advice administrators to incorporate
+  strict, phishing-resistant checks with WebAuthn, Device Trust, or some similar
+  security features into their custom SSO MFA flow.
+</Admonition>
+
+### Updating your authentication connector to enable MFA checks
+
+Take the authentication connector file `connector.yaml` created in [Configuring SSO for login](#configuring-sso-for-login)
+and add MFA settings.
+
+<Tabs>
+<TabItem label="OIDC">
+
+```yaml
+(!examples/resources/oidc-connector-mfa.yaml!)
+```
+
+</TabItem>
+<TabItem label="SAML">
+
+```yaml
+(!examples/resources/saml-connector-mfa.yaml!)
+```
+
+You may use `entity_descriptor_url` in lieu of `entity_descriptor` to fetch
+the entity descriptor from your IDP. 
+
+We recommend "pinning" the entity descriptor by including the XML rather than
+fetching from a URL.
+
+</TabItem>
+</Tabs>
+
+Update the connector: 
+
+```code
+$ tctl create -f connector.yaml
+```
+
+### Allowing SSO as an MFA method in your cluster
+
+Before you can use the SSO MFA flow we created above, you need to enable SSO
+as a second factor in your cluster settings. Modify the dynamic config resource
+using the following command:
+
+```code
+$ tctl edit cluster_auth_preference
+```
+
+Make the following change:
+
+```diff
+kind: cluster_auth_preference
+version: v2
+metadata:
+  name: cluster-auth-preference
+spec:
+  # ...
+  second_factors:
+   - webauthn
++  - sso
+```
+
 ## Working with an external email identity
 
 Along with sending groups, an SSO provider will also provide a user's email address.