使用 Okta 的 SAML 单点登录

一份使用 Okta 集成 SAML 单点登录（SSO）到 Better Auth 的指南

本指南将引导你使用身份提供商（IdP）设置 SAML 单点登录（SSO），以 Okta 为示例。有关高级配置细节及完整 API 参考，请查阅 SSO 插件文档。

什么是 SAML？

SAML（安全断言标记语言）是一种基于 XML 的标准，用于在身份提供商（IdP）（例如 Okta、Azure AD、OneLogin）与服务提供商（SP）（此处为 Better Auth）之间交换身份验证和授权数据。

在该配置中：

  • IdP (Okta): Authenticates users and sends assertions about their identity.
  • SP (Better Auth): Validates assertions and logs the user in.up.

第一步：在 Okta 中创建 SAML 应用

  1. Log in to your Okta Admin Console

  2. Navigate to Applications > Applications

  3. Click "Create App Integration"

  4. Select "SAML 2.0" as the Sign-in method

  5. Configure the following settings:

    • Single Sign-on URL: Your Better Auth callback endpoint (e.g., http://localhost:3000/api/auth/sso/saml2/callback/sso). Note: sso is your providerId
    • Audience URI (SP Entity ID): Your Better Auth metadata URL (e.g., http://localhost:3000/api/auth/sso/saml2/sp/metadata)
    • Name ID format: Email Address or any of your choice.

  6. 下载 IdP 元数据 XML 文件和证书

IdP-Initiated SSO: If you want users to access your app from the Okta dashboard, make sure the Single Sign-on URL points to the callback endpoint (/api/auth/sso/saml2/callback/{providerId}). Better Auth automatically handles both SP-initiated and IdP-initiated flows.

第二步：配置 Better Auth

以下是在开发环境中为 Okta 配置的示例：

const ssoConfig = {
  defaultSSO: [{
    domain: "localhost:3000", // 你的域名
    providerId: "sso",
    samlConfig: {
      // 服务提供商配置
      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: "http://localhost:3000/api/auth/sso/saml2/sp/acs/sso",
      // 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
...
[你的 Okta 证书]
...
-----END CERTIFICATE-----`,
      
      // 服务提供商元数据
      spMetadata: {
        metadata: `<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 
          entityID="http://localhost:3000/api/sso/saml2/sp/metadata">
          ...
          [你的 SP 元数据 XML]
          ...
        </md:EntityDescriptor>`
      }
    }
  }]
}

第三步：多个默认提供商（可选）

你可以为不同域配置多个 SAML 提供商：

const ssoConfig = {
  defaultSSO: [
    {
      domain: "company.com",
      providerId: "company-okta",
      samlConfig: {
        // company.com 的 Okta SAML 配置
      }
    },
    {
      domain: "partner.com", 
      providerId: "partner-adfs",
      samlConfig: {
        // partner.com 的 ADFS SAML 配置
      }
    },
    {
      domain: "contractor.org",
      providerId: "contractor-azure",
      samlConfig: {
        // contractor.org 的 Azure AD SAML 配置
      }
    }
  ]
}

Explicit: Pass providerId directly when signing in. Domain fallback: Matches based on the user’s email domain. e.g. user@company.com → matches company-okta provider.

Step 4: Initiating Sign-In

1. 通过 providerId 显式指定（推荐）：

// 显式指定使用哪个提供商
await authClient.signIn.sso({
  providerId: "company-okta",
  callbackURL: "/dashboard"
});

2. 根据邮箱域名匹配：

// 根据邮箱域名自动匹配提供商
await authClient.signIn.sso({
  email: "user@company.com",
  callbackURL: "/dashboard"
});

3. 指定域名进行匹配：

// 显式指定域名进行匹配
await authClient.signIn.sso({
  domain: "partner.com",
  callbackURL: "/dashboard"
});

Important Notes:

  • DummyIDP should ONLY be used for development and testing
  • Never use these certificates in production
  • The example uses localhost:3000 - adjust URLs for your environment
  • For production, always use proper IdP providers like Okta, Azure AD, or OneLogin
  • callbackUrl is the SAML ACS endpoint URL. If omitted, it defaults to {baseURL}/sso/saml2/sp/acs/{providerId}. The post-login destination is controlled by callbackURL in signIn.sso()

第五步：动态注册 SAML 提供商

要实现动态注册，请通过 API 注册 SAML 提供商。详细注册说明请参阅 SSO 插件文档。

注册示例：

await authClient.sso.register({
  providerId: "okta-prod",
  issuer: "https://your-domain.com",
  domain: "your-domain.com",
  samlConfig: {
    // 你的生产环境 SAML 配置
  }
});

额外资源

Edit on GitHub

On this page

什么是 SAML？
第一步：在 Okta 中创建 SAML 应用
第二步：配置 Better Auth
第三步：多个默认提供商（可选）
Step 4: Initiating Sign-In
第五步：动态注册 SAML 提供商
额外资源