# Salesforce (/docs/authentication/salesforce)

Salesforce 提供程序的设置和使用。



<Steps>
  <Step>
    ### 获取 Salesforce 凭证 [#获取-salesforce-凭证]

    1. 登录您的 Salesforce 组织（生产版或开发者版）
    2. 导航至 **设置 > 应用管理器**
    3. 点击 **新建连接应用**
    4. 填写基本信息：
       * 连接应用名称：您的应用名称
       * API 名称：根据应用名称自动生成
       * 联系邮箱：您的电子邮件地址
    5. 启用 OAuth 设置：
       * 勾选 **启用 OAuth 设置**
       * 将 **回调 URL** 设置为您的重定向 URI（例如开发环境使用 `http://localhost:3000/api/auth/callback/salesforce`）
       * 选择所需的 OAuth 范围：
         * 访问基本信息（id）
         * 访问身份 URL 服务（openid）
         * 访问电子邮件地址（email）
         * 随时代表您发起请求（refresh\_token, offline\_access）
    6. 启用 &#x2A;*要求使用代码交换证明密钥（PKCE）**（必需）
    7. 保存并记录您的 **消费者密钥**（客户端 ID）和 **消费者密钥**（客户端密钥）

    <Callout type="info">
      * 开发环境中可以使用 `http://localhost:3000` 网址，但生产环境需要 HTTPS
      * 回调 URL 必须与 Better Auth 中的配置完全匹配
      * PKCE（代码交换证明密钥）由 Salesforce 要求此提供程序自动处理
    </Callout>

    <Callout type="warning">
      对于沙盒测试，您可以在沙盒组织中创建连接应用，或使用相同的连接应用并在提供程序配置中指定 `environment: "sandbox"`。
    </Callout>
  </Step>

  <Step>
    ### 配置提供程序 [#配置提供程序]

    要配置提供程序，您需要导入提供程序并将其传递给认证实例的 `socialProviders` 选项。

    ```ts title="auth.ts"
    import { betterAuth } from "better-auth"

    export const auth = betterAuth({
        socialProviders: {
            salesforce: { // [!code highlight]
                clientId: process.env.SALESFORCE_CLIENT_ID as string, // [!code highlight]
                clientSecret: process.env.SALESFORCE_CLIENT_SECRET as string, // [!code highlight]
                environment: "production", // 或 "sandbox" // [!code highlight]
            }, // [!code highlight]
        },
    })
    ```

    #### 配置选项 [#配置选项]

    * `clientId`：连接应用的消费者密钥
    * `clientSecret`：连接应用的消费者密钥
    * `environment`：`"production"`（默认）或 `"sandbox"`
    * `loginUrl`：自定义 My Domain URL（不含 `https://`）- 覆盖环境设置
    * `redirectURI`：如需覆盖则手动生成重定向 URI

    #### 高级配置 [#高级配置]

    ```ts title="auth.ts"
    export const auth = betterAuth({
        socialProviders: {
            salesforce: {
                clientId: process.env.SALESFORCE_CLIENT_ID as string,
                clientSecret: process.env.SALESFORCE_CLIENT_SECRET as string,
                environment: "sandbox", // [!code highlight]
                loginUrl: "my-company.my.salesforce.com", // 自定义 My Domain // [!code highlight]
                redirectURI: "http://localhost:3000/api/auth/callback/salesforce", // 如有需要覆盖 // [!code highlight]
            },
        },
    })
    ```

    <Callout type="info">
      * 使用 `environment: "sandbox"` 进行 Salesforce 沙盒组织测试
      * `loginUrl` 选项适用于启用了 My Domain 的组织
      * `redirectURI` 选项有助于解决重定向 URI 不匹配错误
    </Callout>
  </Step>

  <Step>
    ### 环境变量 [#环境变量]

    将以下环境变量添加到您的 `.env.local` 文件中：

    ```bash title=".env.local"
    SALESFORCE_CLIENT_ID=您的消费者密钥
    SALESFORCE_CLIENT_SECRET=您的消费者密钥
    BETTER_AUTH_URL=http://localhost:3000 # 对重定向 URI 生成很重要
    ```

    对于生产环境：

    ```bash title=".env"
    SALESFORCE_CLIENT_ID=您的消费者密钥
    SALESFORCE_CLIENT_SECRET=您的消费者密钥
    BETTER_AUTH_URL=https://您的域名.com
    ```
  </Step>

  <Step>
    ### 使用 Salesforce 登录 [#使用-salesforce-登录]

    要使用 Salesforce 登录，您可以使用客户端提供的 `signIn.social` 函数。`signIn` 函数接收以下属性的对象：

    * `provider`：要使用的提供程序，应设置为 `salesforce`。

    ```ts title="auth-client.ts"
    import { createAuthClient } from "better-auth/client"
    const authClient = createAuthClient()

    const signIn = async () => {
        const data = await authClient.signIn.social({
            provider: "salesforce"
        })
    }
    ```
  </Step>

  <Step>
    ### 故障排除 [#故障排除]

    #### 重定向 URI 不匹配错误 [#重定向-uri-不匹配错误]

    如果遇到 `redirect_uri_mismatch` 错误：

    1. **检查回调 URL**：确保 Salesforce 已连接应用中的回调 URL 与 Better Auth 的回调 URL 完全匹配
    2. **协议**：确认使用相同的协议（`http://` 与 `https://`）
    3. **端口**：确认端口号匹配（例如 `:3000`）
    4. **如有必要覆盖**：使用 `redirectURI` 选项明确设置回调 URI

    ```ts
    salesforce: {
        clientId: process.env.SALESFORCE_CLIENT_ID as string,
        clientSecret: process.env.SALESFORCE_CLIENT_SECRET as string,
        redirectURI: "http://localhost:3000/api/auth/callback/salesforce", // [!code highlight]
    }
    ```

    #### 环境问题 [#环境问题]

    * **生产环境**：使用 `environment: "production"`（默认）配合 `login.salesforce.com`
    * **沙盒**：使用 `environment: "sandbox"` 配合 `test.salesforce.com`
    * **My Domain**：使用 `loginUrl: "yourcompany.my.salesforce.com"` 用于自定义域名

    #### PKCE 要求 [#pkce-要求]

    Salesforce 要求 PKCE（代码交换证明密钥），此提供程序会自动处理。确保在连接应用设置中启用了 PKCE。

    <Callout type="info">
      默认请求的范围为 `openid`、`email` 和 `profile`。该提供程序会自动包含 `id` 范围以访问基本用户信息。
    </Callout>
  </Step>
</Steps>