Teleport SSO MFA 深度解析:以第三方 IdP 作为一等公民的 MFA 认证体系(RFD 180 实现解读)
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 方法偏好顺序(从高到低):
- WebAuthn
- SSO
- 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 成为首选方法的两个条件:
- 显式提供了
--mfa-mode=sso; - 用户没有注册(或没有插入)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 的 UUIDDeviceType: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 改进。