Add SSO MFA docs (#50533)

* Add SSO MFA docs.

* Address comments from zmb3.

* Fix links; minor style fix.

* Address comments.

* Try removing leading / in example links.

* Address Nic's comments.

Author: Joerger

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.

examples/resources/oidc-connector-mfa.yaml

@@ -0,0 +1,33 @@
+kind: oidc
+version: v3
+metadata:
+  name: oidc_connector
+spec:
+  # Login settings
+  client_id: <LOGIN-CLIENT-NAME>
+  client_secret: <LOGIN-CLIENT-SECRET>
+  # issuer_url and redirect_url are shared by both login and MFA, meaning the same OIDC provider must be used.
+  issuer_url: https://idp.example.com/
+  redirect_url: https://mytenant.teleport.sh:443/v1/webapi/oidc/callback
+  # ...
+
+  # MFA settings
+  mfa:
+    # Enabled specified whether this OIDC connector supports MFA checks.
+    enabled: true
+    # client_id and client_secret should point to an IdP configured
+    # app configured to handle MFA checks. In most cases, these values
+    # should be different from your login client ID and Secret above.
+    client_id: <MFA-CLIENT-NAME>
+    client_secret: <MFA-CLIENT-SECRET>
+    # prompt can be set to request a specific prompt flow from the IdP. Supported
+    # values depend on the IdP.
+    prompt: none
+    # acr_values are Authentication Context Class Reference values. These values
+    # are context-specific and vary depending on the IdP.
+    acr_values: []
+    # max_age is the amount of time in seconds that an IdP session is valid for.
+    # Defaults to 0 to always force re-authentication for MFA checks. This should
+    # only be set to a non-zero value if the IdP is setup to perform MFA checks on
+    # top of active user sessions.
+    max_age: 0

examples/resources/saml-connector-mfa.yaml

@@ -0,0 +1,29 @@
+#
+# Example resource for a SAML connector
+# This connector can be used for SAML endpoints like Okta
+#
+kind: saml
+version: v2
+metadata:
+  # the name of the connector
+  name: okta
+spec:
+  # Login settings
+  display: Okta
+  entity_descriptor_url: https://example.okta.com/app/<LOGIN-APP-ID>/sso/saml/metadata
+  # acs is shared by both login and MFA, meaning the same SAML provider must be used.
+  acs: https://<cluster-url>/v1/webapi/saml/acs/new_saml_connector
+  # ...
+
+  # MFA settings
+  mfa:
+    # Enabled specifies whether this SAML connector supports MFA checks.
+    enabled: true
+    # entity_descriptor_url should point to an IdP configured app that handles MFA checks.
+    # In most cases, this value should be different from the entity_descriptor_url above.
+    entity_descriptor_url: https://example.okta.com/app/<MFA-APP-ID>/sso/saml/metadata
+    # force_reauth determines whether existing login sessions are accepted or if
+    # re-authentication is always required. Defaults to "yes". This should only be
+    # set to false if the app described above is setup to perform MFA checks on top
+    # of active user sessions.
+    force_reauth: yes