使用 Okta 的 SAML 单点登录
本指南将引导你通过使用身份提供商（IdP）设置 SAML 单点登录（SSO），以 Okta 为示例。有关高级配置详情和完整的 API 参考，请查看 SSO 插件文档。
🌐 This guide walks you through setting up SAML Single Sign-On (SSO) with your Identity Provider (IdP), using Okta as an example. For advanced configuration details and the full API reference, check out the SSO Plugin Documentation.
什么是 SAML？
🌐 What is SAML?
SAML（安全断言标记语言）是一种基于 XML 的标准，用于在身份提供者（IdP）（例如 Okta、Azure AD、OneLogin）和服务提供者（SP）（在本例中为 Better Auth）之间交换身份验证和授权数据。
🌐 SAML (Security Assertion Markup Language) is an XML-based standard for exchanging authentication and authorization data between an Identity Provider (IdP) (e.g., Okta, Azure AD, OneLogin) and a Service Provider (SP) (in this case, Better Auth).
在这种设置下：
🌐 In this setup:
- IdP (Okta)：验证用户并发送有关其身份的声明。
- SP（更好认证）：验证断言并登录用户。
第 1 步：在 Okta 中创建一个 SAML 应用
🌐 Step 1: Create a SAML Application in Okta
- 登录你的 Okta 管理控制台
- 导航到 应用 > 应用
- 点击“创建应用集成”
- 选择“SAML 2.0”作为登录方式
- 配置以下设置：
- 单点登录 URL：你的 Better Auth ACS 端点（例如，
http://localhost:3000/api/auth/sso/saml2/sp/acs/sso），其中sso为你的 providerId - 受众 URI（SP 实体 ID）：你的 Better Auth 元数据 URL（例如，
http://localhost:3000/api/auth/sso/saml2/sp/metadata） - 名称 ID 格式：电子邮件地址或你选择的任意内容。
- 单点登录 URL：你的 Better Auth ACS 端点（例如，
- 下载 IdP 元数据 XML 文件和证书
步骤 2：配置更好的认证
🌐 Step 2: Configure Better Auth
这是一个在开发环境中配置 Okta 的示例：
🌐 Here’s an example configuration for Okta in a dev environment:
const ssoConfig = {
defaultSSO: [{
domain: "localhost:3000", // Your domain
providerId: "sso",
samlConfig: {
// SP Configuration
issuer: "http://localhost:3000/api/auth/sso/saml2/sp/metadata",
entryPoint: "https://trial-1076874.okta.com/app/trial-1076874_samltest_1/exktofb0a62hqLAUL697/sso/saml",
callbackUrl: "/dashboard", // Redirect after successful authentication
// IdP Configuration
idpMetadata: {
entityID: "https://trial-1076874.okta.com/app/exktofb0a62hqLAUL697/sso/saml/metadata",
singleSignOnService: [{
Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
Location: "https://trial-1076874.okta.com/app/trial-1076874_samltest_1/exktofb0a62hqLAUL697/sso/saml"
}],
},
cert: `-----BEGIN CERTIFICATE-----
MIIDqjCCApKgAwIBAgIGAZhVGMeUMA0GCSqGSIb3DQEBCwUAMIGVMQswCQYDVQQGEwJVUzETMBEG
...
[Your Okta Certificate]
...
-----END CERTIFICATE-----`,
// SP Metadata
spMetadata: {
metadata: `<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
entityID="http://localhost:3000/api/sso/saml2/sp/metadata">
...
[Your SP Metadata XML]
...
</md:EntityDescriptor>`
}
}
}]
}第 3 步：多个默认提供者（可选）
🌐 Step 3: Multiple Default Providers (Optional)
你可以为不同的域配置多个 SAML 提供程序：
🌐 You can configure multiple SAML providers for different domains:
const ssoConfig = {
defaultSSO: [
{
domain: "company.com",
providerId: "company-okta",
samlConfig: {
// Okta SAML configuration for company.com
}
},
{
domain: "partner.com",
providerId: "partner-adfs",
samlConfig: {
// ADFS SAML configuration for partner.com
}
},
{
domain: "contractor.org",
providerId: "contractor-azure",
samlConfig: {
// Azure AD SAML configuration for contractor.org
}
}
]
}显式：登录时直接传递 providerId。
域回退： 根据用户的邮箱域匹配。例如 user@company.com → 匹配 company-okta 提供者。
第四步：开始登录
🌐 Step 4: Initiating Sign-In
你可以通过三种方式启动单点登录（SSO）流程：
🌐 You can start an SSO flow in three ways:
1. 明确指定 providerId（推荐）：
// Explicitly specify which provider to use
await authClient.signIn.sso({
providerId: "company-okta",
callbackURL: "/dashboard"
});2. 按电子邮件域匹配：
// Automatically matches provider based on email domain
await authClient.signIn.sso({
email: "user@company.com",
callbackURL: "/dashboard"
});3. 按字段指定:
// Explicitly specify domain for matching
await authClient.signIn.sso({
domain: "partner.com",
callbackURL: "/dashboard"
});重要提示：
- DummyIDP 仅应用于开发和测试
- 切勿在生产环境中使用这些证书
- 该示例使用
localhost:3000- 请根据你的环境调整 URL - 在生产环境中，请始终使用像 Okta、Azure AD 或 OneLogin 这样的正规身份提供商
第 5 步：动态注册 SAML 提供商
🌐 Step 5: Dynamically Registering SAML Providers
对于动态注册，你应使用 API 注册 SAML 提供商。详细的注册说明请参阅 SSO 插件文档。
🌐 For dynamic registration, you should register SAML providers using the API. See the SSO Plugin Documentation for detailed registration instructions.
示例注册：
🌐 Example registration:
await authClient.sso.register({
providerId: "okta-prod",
issuer: "https://your-domain.com",
domain: "your-domain.com",
samlConfig: {
// Your production SAML configuration
}
});附加资源
🌐 Additional Resources