# Facebook (/docs/authentication/facebook)

Facebook 提供者的设置和使用。



<Steps>
  <Step>
    ### 获取 Facebook 凭证 [#获取-facebook-凭证]

    要使用 Facebook 登录，您需要客户端 ID 和客户端密钥。您可以从 [Facebook 开发者门户](https://developers.facebook.com/) 获取它们。
    选择您的应用，导航到 **应用设置 > 基本信息**，找到以下内容：

    * **应用 ID**：这是您的 `clientId`
    * **应用密钥**：这是您的 `clientSecret`

    <Callout type="warn">
      避免在客户端代码（例如前端应用）中暴露 `clientSecret`，因为它是敏感信息。
    </Callout>

    确保将重定向 URL 设置为 `http://localhost:3000/api/auth/callback/facebook` 用于本地开发。生产环境中，您应将其设置为应用程序的 URL。如果更改了认证路由的基本路径，您需要相应地更新重定向 URL。
  </Step>

  <Step>
    ### 配置提供者 [#配置提供者]

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

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

    export const auth = betterAuth({
        socialProviders: {
            facebook: { // [!code highlight]
                clientId: process.env.FACEBOOK_CLIENT_ID as string, // [!code highlight]
                clientSecret: process.env.FACEBOOK_CLIENT_SECRET as string, // [!code highlight]
            }, // [!code highlight]
        },
    })
    ```

    <Callout>
      BetterAuth 还支持 Facebook 企业登录，您只需提供 `configId`，就像在 **Facebook 企业登录 > 配置** 中列出的一样，同时提供 `clientId` 和 `clientSecret`。请注意，该应用必须是企业应用，并且因为 BetterAuth 期望获取电子邮件地址和账户 ID，所以配置类型必须为“用户访问令牌”。“系统用户访问令牌”不受支持。
    </Callout>

    <Callout>
      Facebook 即使在权限已授予的情况下，也可能不会返回 `email`（例如仅有手机号的账户、撤销同意，或 Meta 标记为无效的地址）。有关推荐的 `mapProfileToUser` 兜底处理，请参阅[处理不提供电子邮件的提供者](/docs/concepts/oauth#处理不提供邮箱的提供商)。
    </Callout>
  </Step>

  <Step>
    ### 使用 Facebook 登录 [#使用-facebook-登录]

    要使用 Facebook 登录，您可以使用客户端提供的 `signIn.social` 函数。`signIn` 函数接受一个包含以下属性的对象：

    * `provider`：要使用的提供者，应设置为 `facebook`。

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

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

## 额外配置 [#额外配置]

### 作用域 [#作用域]

默认情况下，Facebook 提供基本用户信息。如果您需要额外权限，可以在认证配置中指定作用域：

```ts title="auth.ts"
export const auth = betterAuth({
    socialProviders: {
        facebook: {
            clientId: process.env.FACEBOOK_CLIENT_ID as string,
            clientSecret: process.env.FACEBOOK_CLIENT_SECRET as string,
            scopes: ["email", "public_profile", "user_friends"], // 覆盖默认权限
            fields: ["user_friends"], // 扩展获取的字段列表
        },
    },
})
```

其他选项：

* `scopes`：访问基本账户信息（可覆盖）。
  * 默认值：`"email", "public_profile"`
* `fields`：扩展从 Facebook 用户资料中获取的字段列表（赋值）。
  * 默认值：`"id", "name", "email", "picture"`

### 使用 ID Token 或访问令牌登录 Facebook [#使用-id-token-或访问令牌登录-facebook]

要使用 ID Token 登录 Facebook，可以使用 `signIn.social` 函数并传递 ID Token。

这在您已在客户端获得 Facebook ID Token 并希望在服务器端使用它登录时非常有用。

<Callout>
  如果提供了 ID Token，则不会发生重定向，用户将直接登录。
</Callout>

对于有限登录，您需要传递 `idToken.token`，仅使用 `accessToken` 时需要同时传递 `idToken.accessToken` 和 `idToken.token`，因为涉及 [#1183](https://github.com/better-auth/better-auth/issues/1183)。

```ts title="auth-client.ts"
const data = await authClient.signIn.social({
    provider: "facebook",
    idToken: {  // [!code highlight]
        ...(platform === 'ios' ?  // [!code highlight]
            { token: idToken }  // [!code highlight]
            : { token: accessToken, accessToken: accessToken }), // [!code highlight]
    },
})
```

有关可用权限的完整列表，请参阅[权限参考](https://developers.facebook.com/docs/permissions)。