为你的 Capacitor JS 应用添加认证 (Authentication)

提示:

以下演示基于 Capacitor JS 5.0.6。

先决条件

一个 Logto Cloud 账户或一个自托管 Logto。
一个已创建的 Logto 原生应用。

安装

通过你喜欢的包管理器安装 Logto SDK 和对等依赖项：

npm
Yarn
pnpm

npm i @logto/capacitor
npm i @capacitor/browser @capacitor/app @capacitor/preferences

yarn add @logto/capacitor
yarn add @capacitor/browser @capacitor/app @capacitor/preferences

pnpm add @logto/capacitor
pnpm add @capacitor/browser @capacitor/app @capacitor/preferences

@logto/capacitor 包是 Logto 的 SDK。其余的包是它的对等依赖项。

集成

初始化 Logto 客户端

将以下代码添加到你的 Capacitor 项目中：

import LogtoClient, { type LogtoConfig } from '@logto/capacitor';

const logtoConfig: LogtoConfig = {
  endpoint: '<your-logto-endpoint>',
  appId: '<your-application-id>',
};

const logtoClient = new LogtoClient(config);

在我们深入细节之前，下面是终端用户体验的快速概览。登录流程可以简化为如下：

你的应用调用登录方法。
用户被重定向到 Logto 登录页面。对于原生应用，会打开系统浏览器。
用户完成登录后被重定向回你的应用（配置为重定向 URI）。

此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议，Logto 强制执行严格的安全措施以保护用户登录。
如果你有多个应用程序，可以使用相同的身份提供商 (IdP)（日志 (Logto)）。一旦用户登录到一个应用程序，当用户访问另一个应用程序时，Logto 将自动完成登录过程。

要了解有关基于重定向的登录的原理和好处的更多信息，请参阅 Logto 登录体验解释。

现在，让我们配置重定向 URI。重定向 URI 用于在认证流程结束后将用户重定向回你的应用程序。

确保 URI 重定向到 Capacitor 应用，例如，com.example.app://callback。该值可能会根据你的 Capacitor 应用配置而有所不同。更多详情，请参阅 Capacitor Deep Links。

然后，将以下代码添加到登录按钮的 onClick 处理程序中：

const onClick = async () => {
  await logtoClient.signIn('com.example.app://callback');
  console.log(await logtoClient.isAuthenticated()); // true
  console.log(await logtoClient.getIdTokenClaims()); // { sub: '...', ... }
};

实现登出

由于 Capacitor 在 iOS 上利用 Safari View Controller，在 Android 上利用 Chrome Custom Tabs，认证状态可以持续一段时间。然而，有时用户可能希望立即退出应用程序。在这种情况下，我们可以使用 signOut 方法让用户登出：

const onClick = async () => {
  await logtoClient.signOut();
  console.log(await logtoClient.isAuthenticated()); // false
};

signOut 方法有一个可选参数，用于指定登出后的重定向 URI。如果未提供，用户将被重定向到 Logto 登出页面。

用户需要点击“完成”以关闭网页视图并返回到 Capacitor 应用。如果你希望自动将用户重定向回 Capacitor 应用，可以提供登出后的重定向 URI，例如，com.example.app://callback/sign-out。

确保登出后的重定向 URI 可以重定向到 Capacitor 应用。然后将以下代码添加到登出按钮的 onClick 处理程序中：

const onClick = async () => {
  await logtoClient.signOut('com.example.app://callback/sign-out');
};

检查点：触发认证流程

运行 Capacitor 应用并点击登录按钮。浏览器窗口将打开，重定向到 Logto 登录页面。

如果用户在未完成认证流程的情况下关闭浏览器窗口，Capacitor 应用将收到一个 LogtoClientError。

获取用户信息

显示用户信息

要显示用户的信息，你可以使用 getIdTokenClaims() 方法。例如，在 Capacitor 应用中：

const userClaims = await logtoClient.getIdTokenClaims();
console.log(userClaims);

请求额外的声明

你可能会发现从 client.getIdTokenClaims() 返回的对象中缺少一些用户信息。这是因为 OAuth 2.0 和 OpenID Connect (OIDC) 的设计遵循最小权限原则 (PoLP)，而 Logto 是基于这些标准构建的。

默认情况下，返回的声明（Claim）是有限的。如果你需要更多信息，可以请求额外的权限（Scope）以访问更多的声明（Claim）。

信息:

“声明（Claim）”是关于主体的断言；“权限（Scope）”是一组声明。在当前情况下，声明是关于用户的一条信息。

以下是权限（Scope）与声明（Claim）关系的非规范性示例：

提示:

“sub” 声明（Claim）表示“主体（Subject）”，即用户的唯一标识符（例如用户 ID）。

Logto SDK 将始终请求三个权限（Scope）：openid、profile 和 offline_access。

要请求额外的权限，你可以在初始化客户端时将权限传递给 LogtoConfig 对象。例如：

const logtoConfig = {
  scopes: ['email', 'phone', 'custom_data', 'organizations'],
};

然后你可以在 client.getIdTokenClaims() 的返回值中访问额外的声明：

需要网络请求的声明

为了防止 ID 令牌 (ID token) 过大，一些声明需要通过网络请求来获取。例如，即使在权限中请求了 custom_data 声明，它也不会包含在用户对象中。要访问这些声明，你可以使用 client.fetchUserInfo() 方法：

const userInfo = await logtoClient.fetchUserInfo();
console.log(userInfo);

该方法将通过请求 userinfo 端点来获取用户信息。要了解更多可用的权限和声明，请参阅权限和声明部分。

权限和声明

Logto 使用 OIDC 权限 (Scopes) 和声明 (Claims) 约定来定义用于从 ID 令牌 (ID token) 和 OIDC userinfo 端点获取用户信息的权限 (Scopes) 和声明 (Claims)。"scope" 和 "claim" 都是 OAuth 2.0 和 OpenID Connect (OIDC) 规范中的术语。

对于标准 OIDC 声明 (Claims)，其在 ID 令牌 (ID token) 中的包含严格由所请求的权限 (Scopes) 决定。扩展声明 (Claims)（如 custom_data 和 organizations）可以通过自定义 ID 令牌 (Custom ID token) 设置额外配置到 ID 令牌 (ID token) 中。

简而言之，当你请求某个权限 (Scope) 时，你将在用户信息中获得相应的声明 (Claims)。例如，如果你请求 `email` 权限 (Scope)，你将获得用户的 `email` 和 `email_verified` 数据。

默认情况下，Logto SDK 总是会请求三个权限 (Scopes)：`openid`、`profile` 和 `offline_access`，并且无法移除这些默认权限 (Scopes)。但你可以在配置 Logto 时添加更多权限 (Scopes)：

import { type LogtoConfig, UserScope } from '@logto/capacitor';

const config: LogtoConfig = {
  // ...其他选项
  scopes: [UserScope.Email, UserScope.Phone], // 添加你需要的权限 (scopes)
};

以下是支持的权限 (Scopes) 及其对应的声明 (Claims) 列表：

标准 OIDC 权限 (Scopes)

openid（默认）

Claim name	Type	Description
sub	`string`	用户的唯一标识符

profile（默认）

Claim name	Type	Description
name	`string`	用户的全名
username	`string`	用户名
picture	`string`	终端用户头像的 URL。该 URL 必须指向一个图片文件（例如 PNG、JPEG 或 GIF 图片文件），而不是包含图片的网页。请注意，该 URL 应专门指向适合在描述终端用户时显示的头像，而不是终端用户拍摄的任意照片。
created_at	`number`	终端用户创建的时间。该时间以自 Unix 纪元（1970-01-01T00:00:00Z）以来的毫秒数表示。
updated_at	`number`	终端用户信息最后更新时间。该时间以自 Unix 纪元（1970-01-01T00:00:00Z）以来的毫秒数表示。

其他标准声明 (Claims) 包括 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 和 locale 也会包含在 profile 权限 (Scope) 中，无需请求 userinfo 端点。与上表声明 (Claims) 不同的是，这些声明 (Claims) 仅在其值不为空时返回，而上表声明 (Claims) 的值为空时会返回 null。

备注:

与标准声明 (Claims) 不同，created_at 和 updated_at 声明 (Claims) 使用的是毫秒而不是秒。

email

Claim name	Type	Description
email	`string`	用户的电子邮件地址
email_verified	`boolean`	电子邮件地址是否已被验证

phone

Claim name	Type	Description
phone_number	`string`	用户的电话号码
phone_number_verified	`boolean`	电话号码是否已被验证

address

关于 address 声明 (Claim) 的详细信息，请参阅 OpenID Connect Core 1.0。

信息:

带有 （默认） 标记的权限 (Scopes) 总是由 Logto SDK 请求。当请求相应权限 (Scope) 时，标准 OIDC 权限 (Scopes) 下的声明 (Claims) 总是包含在 ID 令牌 (ID token) 中——无法关闭。

扩展权限 (Scopes)

以下权限 (Scopes) 由 Logto 扩展，并将通过 userinfo 端点返回声明 (Claims)。这些声明 (Claims) 也可以通过控制台 > 自定义 JWT 配置为直接包含在 ID 令牌 (ID token) 中。详见自定义 ID 令牌 (ID token)。

custom_data

Claim name	Type	Description	Included in ID token by default
custom_data	`object`	用户的自定义数据

identities

Claim name	Type	Description	Included in ID token by default
identities	`object`	用户关联的身份
sso_identities	`array`	用户关联的 SSO 身份

roles

Claim name	Type	Description	Included in ID token by default
roles	`string[]`	用户的角色 (Roles)	✅

urn:logto:scope:organizations

Claim name	Type	Description	Included in ID token by default
organizations	`string[]`	用户所属的组织 (Organizations) ID	✅
organization_data	`object[]`	用户所属的组织 (Organizations) 数据

备注:

这些组织 (Organizations) 声明 (Claims) 也可以在使用不透明令牌 (Opaque token) 时通过 userinfo 端点获取。但不透明令牌 (Opaque tokens) 不能作为组织令牌 (Organization tokens) 用于访问组织专属资源。详见不透明令牌 (Opaque token) 与组织 (Organizations)。

urn:logto:scope:organization_roles

Claim name	Type	Description	Included in ID token by default
organization_roles	`string[]`	用户所属组织 (Organizations) 的角色 (Roles)，格式为 `<organization_id>:<role_name>`	✅

API 资源和组织 (Organizations)

我们建议首先阅读 🔐 基于角色的访问控制 (RBAC)，以了解 Logto RBAC 的基本概念以及如何正确设置 API 资源。

配置 Logto 客户端

一旦你设置了 API 资源，就可以在应用中配置 Logto 时添加它们：

import { type LogtoConfig } from '@logto/capacitor';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // 添加 API 资源
};

每个 API 资源都有其自己的权限（权限）。

例如，https://shopping.your-app.com/api 资源具有 shopping:read 和 shopping:write 权限，而 https://store.your-app.com/api 资源具有 store:read 和 store:write 权限。

要请求这些权限，你可以在应用中配置 Logto 时添加它们：

import { type LogtoConfig } from '@logto/capacitor';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

你可能会注意到权限是与 API 资源分开定义的。这是因为 OAuth 2.0 的资源指示器指定请求的最终权限将是所有目标服务中所有权限的笛卡尔积。

因此，在上述情况下，权限可以从 Logto 中的定义简化，两个 API 资源都可以拥有 read 和 write 权限，而无需前缀。然后，在 Logto 配置中：

import { type LogtoConfig } from '@logto/capacitor';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: ['read', 'write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

对于每个 API 资源，它将请求 read 和 write 权限。

备注:

请求 API 资源中未定义的权限是可以的。例如，即使 API 资源没有可用的 email 权限，你也可以请求 email 权限。不可用的权限将被安全地忽略。

成功登录后，Logto 将根据用户的角色向 API 资源发布适当的权限。

获取 API 资源的访问令牌

要获取特定 API 资源的访问令牌 (access token)，你可以使用 getAccessToken 方法：

const token = await logtoClient.getAccessToken('https://shopping.your-app.com/api');

此方法将返回一个 JWT 访问令牌 (access token)，当用户具有相关权限时，可以用来访问 API 资源。如果当前缓存的访问令牌 (access token) 已过期，此方法将自动尝试使用刷新令牌 (refresh token) 获取新的访问令牌 (access token)。

获取组织令牌

如果你对组织不熟悉，请阅读 🏢 组织（多租户）以开始了解。

在配置 Logto 客户端时，你需要添加 用户权限.组织 (UserScope.Organizations) 权限：

import { type LogtoConfig, UserScope } from '@logto/capacitor';

const config: LogtoConfig = {
  // ...other configs
  scopes: [UserScope.Organizations],
};

用户登录后，你可以获取用户的组织令牌：

await logtoClient.getOrganizationToken(organizationId);

延伸阅读

终端用户流程：认证 (Authentication) 流程、账户流程和组织流程配置连接器 (Connectors) 授权 (Authorization)

先决条件​

安装​

集成​

初始化 Logto 客户端​

实现登录​

关于基于重定向的登录​

实现登出​

检查点：触发认证流程​

获取用户信息​

显示用户信息​

请求额外的声明​

需要网络请求的声明​

权限和声明​

标准 OIDC 权限 (Scopes)​

扩展权限 (Scopes)​

API 资源和组织 (Organizations)​

配置 Logto 客户端​

获取 API 资源的访问令牌​

获取组织令牌​

延伸阅读​