# 使用 Okta 实现 SAML SSO (/docs/guides/saml-sso-with-okta)

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



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

## 什么是 SAML？ [#什么是-saml]

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

在该配置中：

* **IdP (Okta)**：对用户进行身份验证并发送有关其身份的断言
* **SP (Better Auth)**：验证断言并登录用户

### 第一步：在 Okta 中创建 SAML 应用 [#第一步在-okta-中创建-saml-应用]

1. 登录 Okta 管理控制台

2. 导航至 Applications > Applications

3. 点击“Create App Integration”

4. 选择“SAML 2.0”作为登录方式

5. 配置以下设置：

   * **Single Sign-on URL**：你的 Better Auth 回调端点（例如，`http://localhost:3000/api/auth/sso/saml2/sp/acs/sso`）。注意：`sso` 是你的 `providerId`
   * **Audience URI (SP Entity ID)**：你的 Better Auth 元数据 URL（例如，`http://localhost:3000/api/auth/sso/saml2/sp/metadata`）
   * **Name ID format**：Email Address 或你选择的任意格式

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

<Callout type="info">
  **IdP 发起的 SSO**：如果你希望用户从 Okta 仪表板访问你的应用，请确保 **Single Sign-on URL** 指向回调端点（`/api/auth/sso/saml2/sp/acs/{providerId}`）。Better Auth 会自动处理 SP 发起和 IdP 发起的流程。
</Callout>

### 第二步：配置 Better Auth [#第二步配置-better-auth]

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

```typescript
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",
      // 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 提供商：

```typescript
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 配置
      }
    }
  ]
}
```

<Callout type="info">
  **显式指定**：登录时直接传入 providerId
  **域名回退**：根据用户的邮箱域名进行匹配。例如 [user@company.com](mailto:user@company.com) → 匹配 `company-okta` 提供商。
</Callout>

### 第四步：发起登录 [#第四步发起登录]

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

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

**2. 根据邮箱域名匹配：**

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

**3. 指定域名进行匹配：**

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

**重要注意事项**：

* DummyIDP 只能用于开发和测试
* 切勿在生产环境中使用这些证书
* 示例使用 `localhost:3000`，请根据你的环境调整 URL
* 对于生产环境，始终使用 Okta、Azure AD 或 OneLogin 等适当的 IdP 提供商
* ACS URL 会根据 `{baseURL}/sso/saml2/sp/acs/{providerId}` 自动派生。登录后的目标位置由 `signIn.sso()` 中的 `callbackURL` 控制

### 第五步：动态注册 SAML 提供商 [#第五步动态注册-saml-提供商]

要实现动态注册，请通过 API 注册 SAML 提供商。详细注册说明请参阅 [SSO 插件文档](/docs/plugins/sso#注册-saml-提供者)。

注册示例：

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

## 额外资源 [#额外资源]

* [SSO 插件文档](/docs/plugins/sso)
* [Okta SAML 文档](https://developer.okta.com/docs/concepts/saml/)
* [SAML 2.0 规范](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf)。