使用 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 这样的正规 IdP 提供商
第 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】