Teleport SSO MFA 深度解析:以第三方 IdP 作为一等公民的 MFA 认证体系(RFD 180 实现解读)

原创2026-09-21 09:14:481,999 阅读
文章标签:网络安全认证鉴权运维后端

Teleport SSO MFA 深度解析:以第三方 IdP 作为一等公民的 MFA 认证体系(RFD 180 实现解读)

导读

本文基于 Teleport 开源仓库中的设计文档 rfd/0180-sso-mfa.md,深入剖析 Teleport 如何将第三方身份提供商(IdP)的多因子认证(MFA)纳入自身的 MFA 检查体系:从 tsh / WebUI / Teleport Connect 三端的 UX 设计、second_factors 与 Auth Connector mfa 配置模型、SSO MFA 挑战与回应的完整流程,到 Proto 协议扩展与安全边界假设。读完本文,你将掌握 SSO MFA 的启用前提、配置方法、核心安全模型,以及该特性在当前仓库中的实际代码落点,能够据此评估或部署基于 IdP 的 MFA 方案。

一、What / Why:为什么 Teleport 要把 MFA 检查委托给 IdP

RFD 180(作者 Brian Joerger,状态 implemented)定义的能力是:通过第三方身份提供商(IdP)以 SSO 方式满足 Teleport 的 MFA 检查。Per-session MFA 必须对所有 Teleport 客户端支持,管理动作 MFA、受控会话等作为延伸目标,理想状态是把 SSO 作为一等公民(first class)的 MFA 方法。

将 MFA 检查委托给已注册的 IdP 有这些潜在收益:

  • 统一管控:管理员可以直接在 IdP 侧配置和监控所有认证环节,无需在多个系统间切换;
  • 集成自定义 MFA 机制:Teleport 可以复用 IdP 上已注册的 MFA 设备与机制(包括第三方服务商提供的 MFA 卸载能力);
  • 新用户零门槛:新 SSO 用户无需手动注册新设备即可走完 MFA 流程;
  • 老用户多路径:已有用户可以在 MFA 检查时选择多种方式,例如 WebAuthn 设备未插入时改用 SSO;
  • 安全增强:通过要求 SSO MFA 检查来约束新用户添加第一个 MFA 设备。

同时该特性也存在 UX 隐患:选项过多造成混淆(OTP、WebAuthn、SSO 并存)、在某些场景下把用户"锁死"在 SSO MFA、以及 WebAuthn 可用时仍自动弹出浏览器窗口。这些在后续设计中被逐一处理。

二、UX 设计:设备呈现、首选方法与三端交互

2.1 虚拟的 SSO MFA 设备

当一个 Auth Connector 启用了 MFA,Teleport 会把来自该 Connector 的用户视同拥有一个对应的 SSO MFA 设备,从而让用户看到自己真实的 MFA 选项。例如:

> tsh mfa ls
Name     Type     Added at Last used
-------- -------- -------- ---------
yubi     WebAuthn <date>   <date>
okta     SAML     -        -

关键约束:Teleport 并不会为每个用户在后端真正存储一个 MFA 设备资源,因此 tsh mfa add/rm 这类交互对 SSO 设备不生效,应返回可读的错误信息。RFD 明确把"支持 tsh mfa add/rm"(例如引入 use_sso_mfa 用户偏好字段)留作后续范围。

2.2 首选 MFA 方法顺序

MFA 方法偏好顺序(从高到低):

  1. WebAuthn
  2. SSO
  3. OTP

当存在 2 或 3 种可选 MFA 方法时,客户端默认选择最优先的方法,同时仍展示其余选项供用户切换。唯一的例外是登录场景:仅当用户同时有 WebAuthn 与 OTP 设备时才会出现两种 MFA 选项,这一行为保持不变。

2.3 tsh 的命令行体验

用户被提示 MFA 时,将自动按其可用的首选方法执行,并给出"如何改用其他方法"的指引:

Available MFA methods [WEBAUTHN, SSO, OTP]. Continuing with WEBAUTHN.
If you wish to perform MFA with another method, specify with --mfa-mode=<sso,webauthn,otp> flag.

Tap any security key to continue

当 SSO 是首选方法时,提示变为引导用户完成本地浏览器的 SSO MFA 流程:

Available MFA methods [SSO, OTP]. Continuing with SSO.
If you wish to perform MFA with another method, specify with --mfa-mode=<sso,webauthn,otp> flag.

To continue, complete an auth check in your local web browser:
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:60433/f5858c78-75e1-4f3f-b2c5-69e8e76c0ff9

SSO 成为首选方法的两个条件:

  1. 显式提供了 --mfa-mode=sso;
  2. 用户没有注册(或没有插入)WebAuthn 设备。

平台细节:在 macOS、Linux、Windows 上,Teleport 可以通过 libfido2 与 Touch ID 相关库检测用户是否插入了 MFA 设备,进而决定是否把 SSO 提升为首选。

当前仓库中,这一提示逻辑可以在 lib/client/mfa/cli.go 中看到端倪——当可用方法不止一种时,客户端会打印类似的说明,提示使用 --mfa-mode 标志或 TELEPORT_MFA_MODE 环境变量切换;而 lib/client/api.go 中的 parseMFAMode 负责把该值解析为实际认证器偏好。仓库代码还印证了 per-session MFA 只接受 WebAuthn、SSO MFA 与 Browser MFA 三种方式,显式指定 --mfa-mode=otp 会被拒绝。

2.4 WebUI 与 Teleport Connect 的 MFA 模态框

WebUI 在 SSO MFA 启用时,于现有 MFA 模态框中增加 SSO 按钮,原 Continue 按钮改名为 WebAuthn。按钮的颜色/显隐随可用方法动态变化:

WebAuthn SSO WebAuthn 按钮 SSO 按钮
yes yes 高亮 置灰
yes no 高亮 移除
no yes 移除 高亮

点击 SSO 按钮后,SSO 重定向 URL 会在弹窗浏览器中打开;SSO 认证完成后窗口自动关闭,WebUI 继续处理返回的 MFA 响应。

Teleport Connect 的 tshd MFA 提示同样升级为带 WebAuthn 与 SSO 按钮的模态框:

  • 点 WebAuthn:密钥开始闪烁,沿用现有 WebAuthn 模态框直至用户触摸密钥;
  • 点 SSO:自动打开浏览器窗口,并展示新模态框,允许用户取消 SSO 登录,或在浏览器未自动打开时点击展示的可点击链接。

三、用户故事:从"必须注册设备"到"SSO 一步到位"

3.1 首次登录的 SSO 用户

旧行为:SSO 用户首次登录时,Teleport 用户没有注册任何 MFA 设备。要访问受 per-session MFA 保护的资源,必须先通过 tsh mfa add 或 WebUI 设置页添加设备;直接连接会报错:

> tsh ssh server01
ERROR: MFA is required to access this resource but user has no MFA devices; use 'tsh mfa add' to register MFA devices

SSO MFA 之后:这类用户会被引导通过 SSO 提供商重新认证,体验无缝衔接:

> tsh ssh server01
MFA is required to access Node "server01"

To continue, complete an auth check in your local web browser:
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:60433/f5858c78-75e1-4f3f-b2c5-69e8e76c0ff9

添加第一个 MFA 设备:通常新 SSO 用户添加首个设备无需额外认证;借助 SSO MFA,连"第一个设备"的注册都可以附加一次 SSO MFA 检查:

> tsh mfa add
Choose device type [TOTP, WEBAUTHN]: WEBAUTHN
Enter device name: yubi
Allow passwordless logins [YES, NO]: NO

To continue, complete an auth check in your local web browser:
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:53129/65ddd8d8-0616-4b61-b442-595871838247

### complete registration
Tap your *new* security key
...

3.2 已注册 MFA 设备的存量 SSO 用户

  • WebAuthn 与 SSO 都可用:优先走 WebAuthn(Tap any security key to continue),同时提示可用 --mfa-mode 切换;
  • 仅 SSO 可用:直接进入浏览器认证流程(同上文 2.3 的输出)。

删除最后一个 MFA 设备:通常删除最后一个设备被禁止,但借助 SSO MFA 检查,可以让用户"删掉最后一个设备"并把 SSO 作为默认 MFA 方法。RFD 特别澄清了两点:

  • SSO 用户不依赖 MFA 设备完成登录,即使集群认证偏好要求第二因子,SSO 用户也不会被锁死——他们只在使用需要 MFA 的功能前被要求注册一个 MFA 设备;
  • 免密(passwordless)设备与 MFA 设备分开对待。SSO MFA 设备不是免密设备,因此"允许 SSO 用户删除最后一个免密设备(只要还有其他 MFA 设备)"需要单独的特例,该改动不在 RFD 直接范围内,但预计会随之落地。

四、配置:Cluster Auth Preference × Auth Connector 双重开关

SSO MFA 需要同时配置集群认证偏好与 Auth Connector 才能生效。

4.1 集群认证偏好:从 second_factor 到 second_factors

某用户能否使用 SSO MFA,取决于"该用户是否是 SSO 用户"以及"其 Auth Connector 是否配置了 MFA"。因此把 second_factor: sso 当作集群级强制项并不合理。RFD 的演进思路是把单值 second_factor 改为多值 second_factors,让管理员对允许的第二因子有更细粒度的控制:

second_factors 说明
otp 启用 OTP MFA
webauthn 启用 WebAuthn,必须同时设置 webauthn 相关配置
sso 对"来自启用了 MFA 的 Auth Connector 的 SSO 用户"启用 SSO MFA

注意:自 v16 起 second_factor 已无法关闭,因此无需用额外配置项支持 off / optional 语义。

示例配置:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: oidc
  connector_name: auth0
  require_session_mfa: yes
  second_factors: [ sso, webauthn ]

旧字段 second_factor 将被弃用但长期支持:系统根据上表把 second_factor 映射填充到 second_factors(例如 on → [otp, webauthn],webauthn → [webauthn]),并在管理员写入已弃用字段时打印弃用警告。

仓库侧的实现印证:在 api/types/second_factor.go 中,SecondFactorType 枚举包含 otp、webauthn、sso 三个字符串值,secondFactorsFromLegacySecondFactor 实现了从旧 SecondFactorType 到 <a href="https://link.gitcode.com/i/f34d58ce2deefb8b964f00c65d9c226a" target="_blank">]SecondFactorType 的映射,而 LegacySecondFactorFromSecondFactors 提供反向兼容——其中 hasSSO 单独命中时在 WebUI 中被视为 off(例如禁用"添加 MFA 设备"按钮),但 SSO MFA 提示仍然可用。相关资源定义位于 [api/types/authentication.go。

4.2 Auth Connector:新增 mfa 设置段

Auth Connector 增加 mfa 设置字段,允许该 Connector 除登录请求外还处理 MFA 检查;这些设置对该 Connector 注册的全部用户生效。SAML 与 OIDC 分别示例如下:

kind: saml
version: v2
metadata:
  name: okta
spec:
  display: Okta
  acs: https://root.example.com:3080/v1/webapi/saml/acs/okta
  entity_descriptor_url: AAA
  entity_descriptor: BBB
  attributes_to_roles:
    - {name: groups, value: okta-dev, roles: [dev]}
  # 新增的 mfa 设置字段,默认 null。
  mfa:
    # enabled 指定该 auth connector 是否支持 MFA 检查。
    enabled: yes
    # entity_descriptor_url 或 entity_descriptor 应指向一个配置为处理 MFA 检查的 IdP 应用。
    entity_descriptor_url: XXX
    entity_descriptor: YYY
    # force_reauth 决定现有登录会话是否被接受,还是始终要求重新认证。默认 "yes"。
    force_reauth: yes
---
kind: oidc
version: v2
metadata:
  name: auth0
spec:
  display: Auth0
  client_id: AAA
  client_secret: BBB
  issuer_url: https://gravitational.auth0.com/
  redirect_url: https://root.example.com:3080/v1/webapi/oidc/callback
  claims_to_roles:
    - {claim: email, value: bjoerger@goteleport.com, roles: [dev]}
  # 新增的 mfa 设置字段,默认 null。
  mfa:
    # enabled 指定该 auth connector 是否支持 MFA 检查。
    enabled: yes
    # client_id 与 client_secret 应指向一个配置为处理 MFA 检查的 IdP 应用。
    client_id: XXX
    client_secret: YYY
    # prompt 可设置以向 IdP 请求特定提示流程。支持的值取决于 IdP。
    prompt: null
    # acr_values 可设置以向 IdP 请求特定的 acr 用于 MFA 检查。支持的值取决于 IdP。
    acr_values: []
    # max_age 决定现有 IdP 会话何时被视为过期。默认 "0" 以在 MFA 检查时强制重新认证。
    max_age: 0

大部分 MFA 设置项从父 Auth Connector 继承,其中较新的字段值得展开:

mfa.force_reauth(SAML):SAML 侧通过在 SAML 请求中加入 ForceAuth 属性实现强制重认证,该字段同时加入父 Connector 与 MFA Connector 设置。

仓库中的资源实现可以佐证:在 api/types/oidc.go 中,OIDCConnectorV3 提供 GetMFASettings()(返回 *OIDCConnectorMFASettings)与 WithMFASettings()(用 MFA 设置覆盖父 Connector 的 ClientID/ClientSecret 等),后者正是"MFA 应用可复用父连接器凭据"这一设计的关键实现;api/types/saml.go 中 SAMLConnectorV2 亦有对应的 GetMFASettings / SetMFASettings / WithMFASettings。此外 WithMFASettings 在生成时会清除 ClientSecret 之类的敏感字段(见 api/types/oidc.go)。

五、安全模型:SSO 作为 MFA 方法的前提与边界

Teleport 将 MFA 检查用于其最敏感的安全特性(per-session MFA、受控会话、管理动作 MFA)。引入 SSO 作为 MFA 方法后,若 Auth Connector 配置不当,可能面临从"内部用户规避安全 MFA 检查"到"IdP 被攻破后攻击者获得关键权限"的风险。

5.1 IdP 配置假设与严格准则

SSO MFA 的安全性取决于 Teleport 与 IdP 双方的正确配置;具体 MFA 技术细节因 IdP 而异,甚至可能被管理员卸载到外部服务商。因此 Teleport 不对 IdP 侧如何处理 MFA 作任何具体假设,IdP 侧 MFA 流程的安全性由 IdP 管理员负责。

  • SSO MFA 为可选启用(opt-in):文档会指导管理员,仅当 IdP 自身具备严格检查(例如受管 WebAuthn 设备、可信设备)时才为该 Connector 启用 MFA;
  • 强制重认证为默认:即使某 Connector 启用了 MFA 但 IdP 侧没有真正的严格 MFA 检查,用户仍会被要求通过 SSO 提供商重新认证。实际效果是:仅窃取 SSO 会话不足以绕过 MFA 检查,攻击者还必须窃取用户的 SSO 身份(密码、MFA)。

5.2 IdP 被攻破的场景

全面 IdP 攻破后,攻击者可能自动创建拥有任意权限的用户。在设备信任(device trust)被要求的情况下,新自动预置的 SSO 用户必须在可信设备上添加第一个 MFA 设备;叠加"管理动作 MFA""per-session MFA"等特性,IdP 攻破的爆炸半径被大幅收敛——攻击者无法访问关键基础设施,也无法改动集群安全配置。

而把 SSO 作为 MFA 方法会绕过设备信任检查,重新打开上述攻击面。因此设备信任必须被强制纳入 SSO MFA 检查,以维持这一不变量。

5.3 挑战作用域、重用与防重放

SSO MFA 挑战遵循 RFD 155(见仓库文档 rfd/0155-scoped-webauthn-credentials.md)的思路,支持 MFA 挑战作用域(challenge scopes),并允许对特定作用域(如 Admin MFA)按需复用。

  • 防重放:当未请求/不允许重用时,SSO MFA token 被验证一次后立即丢弃,防止重放攻击。

5.4 防钓鱼

与 SSO 登录一样,SSO MFA 流程同样易受钓鱼攻击。IdP 管理员必须遵循上述严格准则,在 IdP 侧配置防钓鱼的 MFA 检查。这取决于具体 IdP——例如 Okta 支持 phr(phishing-resistant,防钓鱼)OIDC acr 值,要求通过 Fido2/WebAuthn 认证才能满足该要求。

六、实现:SSO MFA 的完整调用链

6.1 挑战与回应流程(tsh / CLI 路径)

RFD 给出了完整的时序图。以下为 CLI(如 tsh ssh node)路径:

sequenceDiagram
    participant Client
    participant Teleport
    participant IdP
    participant Node

    Note over Client: `tsh ssh node`
    Note over Client: Prepare SSO client callback URL
    par initiate SSO MFA ceremony
        Client ->> Teleport: rpc CreateAuthenticateRequest<br/>w/ client callback url
        Teleport ->> Teleport: create SSO Auth request
        Teleport ->> Teleport: SSO MFA session for { request_id, username }
        Teleport ->> Client: SSOChallenge{ redirect_url, request_id }
    end
    Note over Client: Prompt user to complete SSO MFA check
    par complete SSO MFA ceremony
        Client ->> IdP: browse to redirect URL
        IdP ->> IdP: login and pass configured MFA check
        IdP ->> Teleport: send successful IdP auth response
        Teleport ->> Teleport: verify IdP username matches the SSO Auth request username
        Teleport ->> Teleport: retrieve SSO MFA session for { request_id, username }<br/>and add an mfa_token
        Teleport ->> IdP: return client callback URL<br/>w/ encode encrypted mfa_token in query params
        IdP -> Client: redirect
    end
    Note over Client: Decode and decrypt mfa_token<br/>from redirect query params
    par per-session MFA ceremony
        Client ->> Teleport: rpc GenerateUserSingleUseCerts<br/>w/ SSOChallengeResponse{ request_id, mfa_token }
        Teleport ->> Teleport: retrieve SSO MFA session for { request_id, username }
        Teleport ->> Teleport: check mfa_token against SSO MFA session
        Teleport ->> Client: issue MFA verified certs
    end
    Client ->> Node: connect w/ MFA verified certs

关键安全点:IdP 返回的用户名必须与 SSO Auth request 中的用户名一致;mfa_token 与 request_id 成对校验,客户端凭此证明自己是该 MFA 会话的持有者。

6.2 WebUI 路径

WebUI 的流程略有不同:

sequenceDiagram
    participant User
    participant WebUI
    participant Proxy
    participant Auth
    participant IdP
    participant Node

    User ->> WebUI: launch new node session
    WebUI ->> Proxy: /web/cluster/<cluster>/console/node/<node-id>/<login>
    Proxy <<-->> WebUI: Open WebSocket
    Proxy ->> Auth: initiate SSO MFA ceremony (see diagram above)
    Auth ->> Proxy: SSOChallenge{ redirect_url, request_id }
    Proxy -->> WebUI: send SSOChallenge over websocket
    WebUI ->> User: prompt user with MFA modal<br/>Buttons [ Webauthn, SSO, Cancel ]
    User ->> WebUI: click SSO
    WebUI ->> IdP: open a pop-up window at IdP redirect_url
    IdP ->> Proxy: complete SSO MFA ceremony<br/>set mfa_token as web cookie
    Proxy ->> IdP: return client callback URL - /web/msg/info/login_success<br/>w/ mfa_token in query params
    IdP ->> WebUI: redirect to /web/msg/info/login_success
    Note over WebUI: catch redirect to success screen,<br/>close pop-up window,<br/>parse mfa_token from query params
    WebUI -->> Proxy: send SSOChallengeResponse{ request_id, mfa_token } over websocket
    Proxy <<->> Auth: complete Per-session MFA ceremony
    Proxy ->> Node: connect w/ MFA verified certs

与 CLI 路径不同,Web 流程不对 mfa_token 使用客户端持有的密钥加密,但 mfa_token 单独无用——必须配合始终由客户端保密保存的 request_id 才能生效。

6.3 SSO MFA 会话数据

用户请求 SSO MFA 挑战时,后端会创建 SSO MFA 会话数据对象;SSO 流程完成后,客户端与会话数据获得匹配的 MFA token,用于客户端证明自己是会话持有者:

// SSOMFASessionData SSO MFA Session data.
type SSOMFASessionData struct {
  // RequestID is the ID of the corresponding SSO Auth request, which is used to
  // identity this session.
  RequestID string `json:"request_id,omitempty"`
  // Username is the Teleport username.
  Username string `json:"username,omitempty"`
  // MFAToken is a secret token set when the SSO flow is completed and returned to
  // the user. The user can then use this token to prove they own the MFA session.
  MFAToken string `json:"token,omitempty"`
  // ConnectorID is id of the corresponding Auth connector.
  ConnectorID string `json:"connector_id,omitempty"`
  // ConnectorType is SSO type of the corresponding Auth connector.
  ConnectorType string `json:"connector_type,omitempty"`
  // ChallengeExtensions are challenge extensions that apply to this SSO MFA session.
  ChallengeExtensions *mfav1.ChallengeExtensions `json:"challenge_extensions,omitempty"`
}

6.4 MFA 设备的"虚拟化"取法

任何源自 mfa-enabled Auth Connector 的用户都被视为注册了 SSO MFA 设备。该设备不存储在后端,而是通过读取用户的 CreatedBy 字段、获取对应 Auth Connector、检查其是否启用 MFA,再按 Connector 详情填充出一个 SSO MFA 设备。

仓库代码印证:服务端在构造 MFA 挑战时会调用 BeginSSOMFAChallenge,并在收到 SSOChallengeResponse 后调用 VerifySSOMFASession 完成校验,两者都位于 lib/auth/auth.go(相关调用点见第 8458 行与第 8749 行附近);其接口定义与 mock 位于 lib/auth/mfa/mfav2/service.go 与 lib/auth/mfa/mfav2/mocks_test.go。

七、Proto 协议扩展

RFD 对认证协议做了如下扩展,以下结构均已在仓库 proto 中落地。

CreateAuthenticateChallengeRequest 增加客户端 SSO 回调 URL:

message CreateAuthenticateChallengeRequest {
  ...
+ // SSOClientRedirectURL should be supplied If the client supports SSO MFA checks.
+ // If unset, the server will only return non-SSO challenges, or an error if SSO
+ // challenges are required.
+ string SSOClientRedirectURL = 7 [(gogoproto.jsontag) = "sso_client_redirect_url,omitempty"];
}

SSOChallenge 与 MFAAuthenticateChallenge:

// SSOChallenge contains SSO auth request details to perform an SSO MFA check.
message SSOChallenge {
  // RequestId is the ID of an SSO auth request.
  string request_id = 1;
  // RedirectUrl is an IdP redirect URL to initiate the SSO MFA flow.
  string redirect_url = 2;
}
message MFAAuthenticateChallenge {
  ...
+ // SSO Challenge is an sso MFA challenge. If set, the client can go to the
+ // IdP redirect URL to perform an MFA check in the IdP and obtain an MFA
+ // token. This token and sso request pair can then be used as MFA verification.
+ SSOChallenge SSOChallenge = 5;
}

SSOChallengeResponse 与 MFAAuthenticateResponse:

// SSOChallengeResponse is a response to SSOChallenge.
message SSOChallengeResponse {
  // RequestId is the ID of an SSO auth request.
  string request_id = 1;
  // MFAToken is a secret token used to verify the user's SSO MFA session.
  string mfa_token = 2;
}
message MFAAuthenticateResponse {
  oneof Response {
    TOTPResponse TOTP = 2;
    webauthn.CredentialAssertionResponse Webauthn = 3;
+   SSOChallengeResponse SSO = 4;
  }
}

SSOMFADevice 与 MFADevice:

// SSOMFADevice contains details of an SSO MFA method.
message SSOMFADevice {
  // connector_id is the ID of the SSO connector.
  string connector_id = 1;
  // connector_type is the type of the SSO connector.
  string connector_type = 2;
}
message MFADevice {
  ...
  oneof device {
    TOTPDevice totp = 8;
    U2FDevice u2f = 9;
    WebauthnDevice webauthn = 10;
+   SSOMFADevice sso = 11;
  }
}

SAML Connector 的 MFA 设置(含 SAMLForceReauth 枚举):

message SAMLConnectorMFASettings {
  // Enabled specified whether this SAML connector supports MFA checks. Defaults to false.
  bool enabled = 1;
  // EntityDescriptor is XML with descriptor. It can be used to supply configuration
  // parameters in one XML file rather than supplying them in the individual elements.
  // If unset, the parent SAML connector's EntityDescriptor will be used.
  string entity_descriptor = 2;
  // EntityDescriptorUrl is a URL that supplies a configuration XML. If unset,
  // the parent SAML connector's EntityDescriptor will be used.
  string entity_descriptor_url = 3;
  // ForceReauth specified whether re-authentication should be forced for MFA checks. UNSPECIFIED is
  // treated as YES. to always re-authentication for MFA checks. This should only be set to YES if the
  // IdP is setup to perform MFA checks on top of active user sessions.
  SAMLForceReauth ForceReauth = 4;
}

// SAMLForceReauth specified whether existing SAML sessions should be accepted or re-authentication
// should be forced.
enum SAMLForceReauth {
  // UNSPECIFIED is treated as the default value for the context; NO for login, YES for MFA checks.
  FORCE_REAUTH_UNSPECIFIED = 0;
  // YES re-authentication should be forced for existing SAML sessions..
  FORCE_REAUTH_YES = 1;
  // NO re-authentication should not be forced for existing SAML sessions.
  FORCE_REAUTH_NO = 2;
}
message SAMLConnectorSpecV2 {
  ...
+ // MFASettings contains settings to enabled SSO MFA checks through this auth connector.
+ SAMLConnectorMFASettings MFASettings = 17 [(gogoproto.jsontag) = "mfa_settings,omitempty"];
+ // ForceReauth specified whether re-authentication should be forced on login. UNSPECIFIED
+ // is treated as NO.
+ SAMLForceReauth ForceReauth = 18 [(gogoproto.jsontag) = "force_reauth,omitempty"];
}

OIDC Connector 的 MFA 设置:

message OIDCConnectorMFASettings {
  // Enabled specified whether this SAML connector supports MFA checks. Defaults to false.
  bool enabled = 1;
  // ClientID is the id of the authentication client (Teleport Auth server). If unset,
  // the parent OIDC connector's ClientID will be used.
  string client_id = 2;
  // ClientSecret is used to authenticate the client. If unset, the parent OIDC connector's
  // ClientSecret will be used.
  string client_secret = 3;
  // AcrValues are Authentication Context Class Reference values. The meaning of the ACR
  // value is context-specific and varies for identity providers. Some identity providers
  // support MFA specific contexts, such Okta with its "phr" (phishing-resistant) ACR.
  string acr_values = 4;
  // Prompt is an optional OIDC prompt. An empty string omits prompt.
  // If not specified, it defaults to select_account for backwards compatibility.
  string prompt = 5;
  // MaxAge is the amount of time 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.
  google.protobuf.Duration max_age = 6;
}
message OIDCConnectorSpecV3 {
  ...
+ // MFASettings contains settings to enabled SSO MFA checks through this auth connector.
+ OIDCConnectorMFASettings MFASettings = 19 [(gogoproto.jsontag) = "mfa_settings,omitempty"];
}

SSO Auth Request 增加用户名(用于 MFA 请求的归属校验):

message SAMLAuthRequest {
  ...
+ // Username is the Teleport username for the auth request. This must be set for MFA requests.
+ string Username = 19 [(gogoproto.jsontag) = "username,omitempty"];
}

message OIDCAuthRequest {
  ...
+ // Username is the Teleport username for the auth request. This must be set for MFA requests.
+ string Username = 20 [(gogoproto.jsontag) = "username,omitempty"];
}

仓库中的实际落点

当前仓库中,SSOChallenge、SSOChallengeResponse 已定义于 api/proto/teleport/mfa/v1/challenge.proto(v1 版本带 Deprecated 标记,提示改用 teleport.mfa.v2,对应文件为 api/proto/teleport/mfa/v2/challenge.proto);SSOMFADevice 定义于 api/proto/teleport/legacy/types/mfa_device.proto,作为 MFADevice 的 oneof device 第 11 号成员,并额外携带 display_name 字段(用于向用户展示 Connector 名称)。这些事实说明 RFD 180 已从设计稿进入实现状态。

八、向后兼容

SSO MFA 流程整体向后兼容:若 SSO MFA 不受支持,客户端与服务端都会回退到经典 MFA 方法。边界情况如下:

  • 客户端期望 SSO MFA,但 Auth 服务端未返回 SSO 挑战:客户端返回"该用户不支持 SSO MFA"的错误。典型触发场景是用户指定了 --mfa-mode=sso,但 Auth Connector 未启用 MFA,或 Auth 服务端版本过旧;
  • 服务端要求 SSO MFA,但客户端未提供 SSO 回调 URL:服务端返回"必须提供回调 URL"的错误。由于这只发生在旧客户端,错误信息会提示用户升级到 v17+;
  • Proxy 服务端过旧:SSO 回调端点不认识 MFA token 字段,token 会在流程末尾丢失。客户端检测到 token 缺失后报错,提示 Proxy 不支持 SSO MFA,并要求在非预期情况下联系集群管理员升级到 v17+。

九、审计事件

SSO MFA 检查通过现有携带 MFADeviceMetadata 的审计事件跟踪,元数据取自与 SSO MFA 会话绑定的 SSO MFA 设备:

  • DeviceName:Auth Connector 的名称
  • DeviceID:Auth Connector 的 UUID
  • DeviceType:SSO 类型(OIDC、SAML)
message MFADeviceMetadata {
  // Name is the user-specified name of the MFA device.
  string DeviceName = 1 [(gogoproto.jsontag) = "mfa_device_name"];
  // ID is the UUID of the MFA device generated by Teleport.
  string DeviceID = 2 [(gogoproto.jsontag) = "mfa_device_uuid"];
  // Type is the type of this MFA device.
  string DeviceType = 3 [(gogoproto.jsontag) = "mfa_device_type"];
}

这样管理员可以在审计日志中看到"某用户通过 Okta(SAML)完成了 per-session MFA 检查"这类完整信息。

十、附加考虑与明确的范围边界

10.1 OIDC ACR Values

ACR(Authentication Context Class Reference)值可在 OIDC 认证请求中指定所需认证类型,理论上可用于要求 IdP 执行 MFA。但各 OIDC 提供商支持的 ACR 值互不相同(如 Okta 支持防钓鱼 phr,要求 Fido2/WebAuthn 认证),因此 Teleport 默认不使用任何 ACR 值,仅在文档中说明如何在 OIDC Connector 中按需设置 acr_values。

10.2 SAML RequestedAuthnContext

SAML 客户端可通过 RequestedAuthnContext 请求特定认证类型,支持情况同样随提供商而异。Teleport 暂时无法直接使用;若未来找到支持类似 Okta phr 语义的 SAML 提供商,可能在 SAML Connector 资源中增加 requested_authn_context 字段。注意:使用 ADFS 或 JumpCloud 作为 SAML IdP 时,Teleport 会通过设置 PasswordProtectedTransport 作为最小 RequestedAuthnContext 来强制密码认证;当 SAML Connector 仅为 MFA 启用时,这个最小要求会被跳过。

10.3 SSO MFA 设备锁定(不在范围内)

由于后端没有为每个用户创建 SSO MFA 设备,现有设备锁定实现无法直接锁定某用户的 SSO MFA 方法,RFD 将其排除在范围外。替代方案包括:IdP 管理员把用户移出 SSO MFA 服务应用;或调整 Auth Connector 的 MFA 配置——SSO MFA 流程在挑战/回应两侧都内建了 Connector 检查,因此禁用 Connector 的 MFA 在效果上等同于直接锁定该 SSO MFA 设备。

10.4 tctl sso configure(不在范围内)

RFD 提出未来可更新 tctl sso configure 以引导用户为 MFA 检查配置 Auth Connector,但考虑到不同 IdP 需要差异化的简化流程,此项工作量大,暂不纳入范围,属于欢迎的后续改进。

10.5 GitHub Connector(不在初始实现内)

GitHub 的 OIDC 提供商不提供精细的 MFA 配置:只能走基础 GitHub 2FA 登录流程,既没有 Okta 式的 MFA ACR 值,也没有 Auth0 式的自定义 MFA Web 流程。因此 GitHub Connector 被排除在初始实现之外。

10.6 Headless(无头认证)支持 SSO MFA

原本 Headless 认证只支持 WebAuthn(旧式 OTP 尤其易受钓鱼攻击)。但一个安全配置且由提供商强制 WebAuthn 的 SSO MFA Connector 同样具备足够的防钓鱼能力,因此 SSO MFA 被支持作为 Headless 审批的 MFA 方法。前提依旧是:管理员必须遵循文档警告,不要在不安全的 SSO MFA 配置下启用无头认证。

十一、总结:从设计到代码的一等公民 MFA 方法

RFD 180 给出了 SSO MFA 从产品、UX、配置到协议、安全的完整设计,而当前仓库已经将其落地为可运行的实现:协议侧 api/proto/teleport/mfa/v2/challenge.proto 定义了 SSO 挑战与响应,api/proto/teleport/legacy/types/mfa_device.proto 定义了虚拟 SSO MFA 设备;配置侧 api/types/second_factor.go 实现了 second_factors 与旧字段的映射,api/types/oidc.go 与 api/types/saml.go 实现了 Connector 的 MFA 设置继承与覆盖;服务端 lib/auth/auth.go 完成 SSO MFA 挑战的发起与验证,客户端 lib/client/mfa/cli.go 提供 --mfa-mode / TELEPORT_MFA_MODE 的方法选择提示。

对使用者而言,部署 SSO MFA 的核心要点是:先在 cluster_auth_preference 中把 sso 加入 second_factors,再为目标 SAML/OIDC Connector 配置 mfa.enabled: yes(连同 IdP 侧的 MFA 应用与严格检查),即可让来自该 Connector 的用户用 IdP 完成 Teleport 的 MFA 检查,并同时受益于"首个设备添加可要求 SSO MFA""删除最后设备不再被锁死"等 UX 改进。

登录后查看全文
teleport