Skip to content

Commit

Permalink
Address Nic's comments.
Browse files Browse the repository at this point in the history
  • Loading branch information
Joerger committed Jan 6, 2025
1 parent 055b7e2 commit 00e7e2a
Show file tree
Hide file tree
Showing 3 changed files with 26 additions and 11 deletions.
33 changes: 23 additions & 10 deletions docs/pages/admin-guides/access-controls/sso/sso.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

<Admonition type="warning">
<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.
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.

<Admonition type="warning">
While the customizability of SSO MFA presents multiple secure options previously
Expand All @@ -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.

<Tabs>
Expand Down
1 change: 1 addition & 0 deletions examples/resources/oidc-connector-mfa.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ 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
# ...
Expand Down
3 changes: 2 additions & 1 deletion examples/resources/saml-connector-mfa.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,13 @@ 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 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.
Expand Down

0 comments on commit 00e7e2a

Please sign in to comment.