Skip to main content
Version: 19.x (unreleased)

Configuring SSO for MFA Checks

Report an Issue

Teleport administrators can configure Teleport to delegate multi-factor authentication checks to a single sign-on provider as an alternative to registering MFA devices directly with the Teleport cluster. This guide explains how to configure SSO for MFA checks.

SSO for MFA checks allows Teleport users to use MFA devices and custom flows configured in the SSO provider to carry out privileged actions in Teleport, such as:

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
note

SSO MFA is an enterprise feature. Only OIDC and SAML auth connectors are supported.

Prerequisites​

  • A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • This guide assumes that you are familiar with how to integrate your identity provider with Teleport. Make sure that you understand the guide in Integrate your IdP for your provider. You must already have an authentication connector configured.

Step 1/3. Configure the IdP application or 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 which prompts for MFA for an active OIDC session.

  1. 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.

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.

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.

Step 2/3. Update your authentication connector​

Add MFA settings to your authentication connector, as shown in the following examples:

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

Update the connector:

tctl create -f connector.yaml

Step 3/3. Allow SSO as an MFA method in your cluster​

Before you can use the SSO MFA flow we created above, you need to enable SSO for multi-factor authentication in your cluster settings. Modify the dynamic config resource using the following command:

tctl edit cluster_auth_preference

Make the following change:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  # ...
  second_factors:
   - webauthn
+  - sso