Add SSO MFA docs.

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,106 @@ 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 MFA checks can be delegated to your SSO provider. 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:
+
+- MFA device management (e.g. register or delete a webauthn device in Teleport)
+- [Per-session MFA](./per-session-mfa.mdx)
+- [Moderated sessions](./moderated-sessions.mdx)
+- [Admin actions](./mfa-for-admin-actions.mdx)
+
+<Admonition type="warning">
+  SSO MFA is an enterprise feature. Only OIDC and SAML auth connectors are supported.
+</Admonition>
+
+### Considerations
+
+Administrators may want to consider enabling this feature for the following benefits:
+
+- All authentication (login and MFA) goes through the IdP, consolidating monitoring
+- 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.
+- Enable new SSO users to carry out MFA-reliant actions, such as [Per-session MFA](./per-session-mfa.mdx),
+without requiring them to register their device through Teleport first.
+
+### 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.
+
+Teleport does not make any assumptions as to how the MFA app is configured.
+If desired, you could even use your basic login flow with username, password,
+and MFA device.
+
+<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 the previous step
+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
+metadata:
+  name: oidc_connector
+spec:
+  # Login settings
+  client_id: <LOGIN-CLIENT-NAME>
+  client_secret: <LOGIN-CLIENT-SECRET>
+  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
+
+version: v3

examples/resources/saml-connector-mfa.yaml

@@ -0,0 +1,28 @@
+#
+# 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: https://<cluster-url>/v1/webapi/saml/acs/new_saml_connector
+  # ...
+
+  # MFA settings
+  mfa:
+    # Enabled specified 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