diff --git a/docs/pages/admin-guides/access-controls/sso/sso.mdx b/docs/pages/admin-guides/access-controls/sso/sso.mdx index 7f6c8af15c4b6..76cd88c08b182 100644 --- a/docs/pages/admin-guides/access-controls/sso/sso.mdx +++ b/docs/pages/admin-guides/access-controls/sso/sso.mdx @@ -418,29 +418,42 @@ SSO provider as an alternative to registering MFA devices directly with the Tele 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](../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 for the following benefits: +Administrators may want to consider enabling this feature in order to: -- All authentication (login and MFA) goes through the IDP, reducing administrative overhead +- 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 - + SSO MFA is an enterprise feature. Only OIDC and SAML auth connectors are supported. ### 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. +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). -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. +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. While the customizability of SSO MFA presents multiple secure options previously @@ -452,7 +465,7 @@ and MFA device. ### Updating your authentication connector to enable MFA checks -Take the authentication connector file `connector.yaml` created in the previous step +Take the authentication connector file `connector.yaml` created in [Configuring SSO for login](#configuring-sso-for-login) and add MFA settings. diff --git a/examples/resources/oidc-connector-mfa.yaml b/examples/resources/oidc-connector-mfa.yaml index 38910eb217e25..ca56b727d1487 100644 --- a/examples/resources/oidc-connector-mfa.yaml +++ b/examples/resources/oidc-connector-mfa.yaml @@ -6,6 +6,7 @@ spec: # Login settings client_id: 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 # ... diff --git a/examples/resources/saml-connector-mfa.yaml b/examples/resources/saml-connector-mfa.yaml index 7b1f96ff220cc..9c58802ec0ace 100644 --- a/examples/resources/saml-connector-mfa.yaml +++ b/examples/resources/saml-connector-mfa.yaml @@ -11,12 +11,13 @@ spec: # Login settings display: Okta entity_descriptor_url: https://example.okta.com/app//sso/saml/metadata + # acs is shared by both login and MFA, meaning the same SAML provider must be used. acs: https:///v1/webapi/saml/acs/new_saml_connector # ... # MFA settings mfa: - # Enabled specified whether this SAML connector supports MFA checks. + # 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.