Cognito

获取 Cognito 凭证

要与 Cognito 集成，需要在 Amazon Cognito 控制台 中设置 用户池 和 应用客户端。

按照以下步骤操作：

1. 进入 Cognito 控制台，创建一个 用户池。
2. 在 应用客户端 中，创建一个新的 应用客户端（如果启用，则记录客户端 ID 和客户端密钥）。
3. 进入 域 并设置一个 Cognito 托管 UI 域（例如：your-app.auth.us-east-1.amazoncognito.com）。
4. 在 应用客户端设置 中启用：
   • 允许的 OAuth 流程：授权码授予
   • 允许的 OAuth 范围：openid、profile、email
5. 添加回调 URL（例如：http://localhost:3000/api/auth/callback/cognito）。

配置提供者

在 auth 实例的 socialProviders 键中配置 cognito 键。

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  socialProviders: {
    cognito: {
      clientId: process.env.COGNITO_CLIENT_ID as string, 
      clientSecret: process.env.COGNITO_CLIENT_SECRET as string, 
      domain: process.env.COGNITO_DOMAIN as string, // 例如 "your-app.auth.us-east-1.amazoncognito.com"
      region: process.env.COGNITO_REGION as string, // 例如 "us-east-1"
      userPoolId: process.env.COGNITO_USERPOOL_ID as string, 
      identityProvider: "Google", // 可选：跳过托管 UI 选择器
    },
  },
})

使用 Cognito 登录

要使用 Cognito 登录，请从客户端使用 signIn.social 函数。

import { createAuthClient } from "better-auth/client"

const authClient = createAuthClient()

const signIn = async () => {
  const data = await authClient.signIn.social({
    provider: "cognito"
  })
}

要针对每次调用覆盖预选的身份提供者（例如，渲染一个绕过 Cognito 选择器的“使用 Okta 登录”按钮），请通过 additionalParams 传递 identity_provider 键：

await authClient.signIn.social({
  provider: "cognito",
  additionalParams: { identity_provider: "Okta" },
})

其他选项：

• scope：要请求的其他 OAuth2 范围（与默认权限合并）。

  • 默认值："openid" "profile" "email"
  • 常见的 Cognito 范围：
    • openid：OpenID Connect 身份验证所必需
    • profile：访问基本个人资料信息
    • email：访问用户的电子邮件
    • phone：访问用户的电话号码
    • aws.cognito.signin.user.admin：授予访问 Cognito 特定 API 的权限

• 注意：你必须在 Cognito 应用客户端设置中配置这些范围。可用范围

• getUserInfo：用于从 Cognito UserInfo 端点获取用户信息的自定义函数。

• identityProvider：预选一个 Cognito 配置的身份提供者，以跳过托管 UI 选择器。有效值包括 "COGNITO"、用户池中的 SAML/OIDC 提供者名称，或 "Google"、"Facebook"、"LoginWithAmazon"、"SignInWithApple" 之一。通过 additionalParams.identity_provider 进行的每次调用覆盖具有更高优先级。

• refreshAccessToken：用于刷新令牌的自定义函数。它接收存储的刷新令牌。

刷新令牌

Cognito 会在成功的授权码授予后返回刷新令牌。之后的刷新令牌授予会返回新的访问令牌和 ID 令牌。只有在应用客户端启用了刷新令牌轮换时，Cognito 才会返回新的刷新令牌；否则，原始刷新令牌仍然有效，Better Auth 会继续使用它。

当提供者账户具有刷新令牌且 accessTokenExpiresAt 已知时，auth.api.getAccessToken 会自动刷新过期的访问令牌。它会返回有效的访问令牌和 ID 令牌。如果你需要在响应中包含刷新令牌，请改用 /refresh-token 端点。

在无数据库的设置中，如果启用了 storeAccountCookie，Better Auth 会将提供者账户数据（包括 OAuth 令牌材料）存储在加密的 account_data cookie 中。令牌刷新响应会设置更新后的 cookie，因此服务端调用方必须将返回的 Set-Cookie 标头转发给浏览器。Cognito JWT 可能很大；Better Auth 会对超大的账户 cookie 进行分块，但浏览器和代理仍可能强制执行总标头大小限制。对于较大的令牌载荷或需要持久令牌存储的生产流程，请使用基于数据库的账户存储。