為你的 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 登入頁面。對於原生應用程式，會開啟系統瀏覽器。
使用者登入後，會被重新導向回你的應用程式（設定為 redirect URI）。

此驗證流程遵循 OpenID Connect (OIDC) 協議，Logto 強制執行嚴格的安全措施以保護使用者登入。
如果你有多個應用程式，可以使用相同的身分提供者 (IdP, Identity provider)（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);

請求額外的宣告 (Claims)

你可能會發現從 client.getIdTokenClaims() 返回的物件中缺少一些使用者資訊。這是因為 OAuth 2.0 和 OpenID Connect (OIDC) 的設計遵循最小權限原則 (PoLP, Principle of Least Privilege)，而 Logto 是基於這些標準構建的。

預設情況下，僅返回有限的宣告 (Claims)。如果你需要更多資訊，可以請求額外的權限範圍 (Scopes) 以存取更多宣告。

資訊:

「宣告 (Claim)」是對主體所做的斷言；「權限範圍 (Scope)」是一組宣告。在目前的情況下，宣告是關於使用者的一部分資訊。

以下是權限範圍與宣告關係的非規範性範例：

提示:

「sub」宣告表示「主體 (Subject)」，即使用者的唯一識別符（例如使用者 ID）。

Logto SDK 將始終請求三個權限範圍：openid、profile 和 offline_access。

要請求額外的權限範圍 (Scopes)，可以在初始化客戶端時將權限範圍傳遞給 LogtoConfig 物件。例如：

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

然後你可以在 client.getIdTokenClaims() 的返回值中訪問額外的宣告 (Claims)：

需要網路請求的宣告 (Claims)

為了防止 ID 權杖 (ID token) 膨脹，某些宣告 (Claims) 需要透過網路請求來獲取。例如，即使在權限範圍 (Scopes) 中請求了 custom_data 宣告，它也不會包含在使用者物件中。要存取這些宣告，你可以使用 client.fetchUserInfo() 方法：

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

此方法將透過請求 userinfo 端點來獲取使用者資訊。要了解更多可用的權限範圍 (Scopes) 和宣告 (Claims)，請參閱權限範圍 (Scopes) 和宣告 (Claims) 部分。

權限範圍 (Scopes) 和宣告 (Claims)

Logto 採用 OIDC 權限範圍 (Scopes) 與宣告 (Claims) 慣例來定義從 ID 權杖 (ID token) 及 OIDC userinfo 端點取得使用者資訊時的權限範圍與宣告。無論「權限範圍 (Scope)」還是「宣告 (Claim)」，皆為 OAuth 2.0 與 OpenID Connect (OIDC) 規範中的術語。

對於標準 OIDC 宣告 (Claims)，其是否包含於 ID 權杖 (ID token) 內，完全取決於所請求的權限範圍 (Scopes)。擴充宣告（如 custom_data 與 organizations）則可透過自訂 ID 權杖 (Custom ID token) 設定，額外配置於 ID 權杖中。

簡而言之，當你請求某個權限範圍 (Scope) 時，會在使用者資訊中取得對應的宣告 (Claims)。例如，若請求 `email` 權限範圍，則會取得使用者的 `email` 與 `email_verified` 資料。

預設情況下，Logto SDK 會始終請求三個權限範圍 (Scopes)：`openid`、`profile` 和 `offline_access`，且無法移除這些預設權限範圍。不過，你可以在設定 Logto 時新增更多權限範圍：

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

const config: LogtoConfig = {
  // ...other options
  scopes: [UserScope.Email, UserScope.Phone], // 添加你需要的權限範圍 (scopes)
};

以下是支援的權限範圍 (Scopes) 及對應的宣告 (Claims) 清單：

標準 OIDC 權限範圍 (Scopes)

openid（預設）

Claim name	Type	Description
sub	`string`	使用者的唯一識別符 (The unique identifier of the user)

profile（預設）

Claim name	Type	Description
name	`string`	使用者全名 (The full name of the user)
username	`string`	使用者名稱 (The username of the user)
picture	`string`	終端使用者大頭貼的 URL。此 URL 必須指向圖片檔案（如 PNG、JPEG 或 GIF），而非包含圖片的網頁。請注意，此 URL 應明確指向適合描述終端使用者的個人照片，而非任意由終端使用者拍攝的照片。(URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.)
created_at	`number`	終端使用者建立時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)
updated_at	`number`	終端使用者資訊最後更新時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)

其他標準宣告 (Standard claims) 包含 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 及 locale 也會包含在 profile 權限範圍內，無需額外請求 userinfo endpoint。與上表宣告不同的是，這些宣告僅在其值不為空時才會回傳，而上表宣告若值為空則會回傳 null。

備註:

與標準宣告不同，created_at 與 updated_at 宣告使用毫秒而非秒為單位。

email

Claim name	Type	Description
email	`string`	使用者的電子郵件地址 (The email address of the user)
email_verified	`boolean`	電子郵件地址是否已驗證 (Whether the email address has been verified)

phone

Claim name	Type	Description
phone_number	`string`	使用者的電話號碼 (The phone number of the user)
phone_number_verified	`boolean`	電話號碼是否已驗證 (Whether the phone number has been verified)

address

請參閱 OpenID Connect Core 1.0 以瞭解 address 宣告的詳細資訊。

資訊:

標註為 （預設） 的權限範圍 (Scopes) 會由 Logto SDK 自動請求。當請求對應權限範圍時，標準 OIDC 權限範圍下的宣告 (Claims) 會始終包含於 ID 權杖 (ID token) 中，且無法關閉。

擴充權限範圍 (Extended scopes)

以下權限範圍由 Logto 擴充，會透過 userinfo endpoint 回傳宣告 (Claims)。這些宣告也可透過 Console > Custom JWT 設定直接包含於 ID 權杖 (ID token) 中。詳情請參閱自訂 ID 權杖 (Custom ID token)。

custom_data

Claim name	Type	Description	Included in ID token by default
custom_data	`object`	使用者的自訂資料 (The custom data of the user)

identities

Claim name	Type	Description	Included in ID token by default
identities	`object`	使用者的連結身分 (The linked identities of the user)
sso_identities	`array`	使用者的連結 SSO 身分 (The linked SSO identities of the user)

roles

Claim name	Type	Description	Included in ID token by default
roles	`string[]`	使用者的角色 (The roles of the user)	✅

urn:logto:scope:organizations

Claim name	Type	Description	Included in ID token by default
organizations	`string[]`	使用者所屬的組織 ID (The organization IDs the user belongs to)	✅
organization_data	`object[]`	使用者所屬的組織資料 (The organization data the user belongs to)

備註:

這些組織宣告 (Organization claims) 也可在使用不透明權杖 (Opaque token) 時，透過 userinfo endpoint 取得。然而，不透明權杖無法作為組織權杖 (Organization tokens) 來存取組織專屬資源。詳見不透明權杖與組織 (Opaque token and organizations)。

urn:logto:scope:organization_roles

Claim name	Type	Description	Included in ID token by default
organization_roles	`string[]`	使用者所屬組織角色，格式為 `<organization_id>:<role_name>` (The organization roles the user belongs to with the format of `<organization_id>:<role_name>`)	✅

API 資源 (API resources) 和組織 (Organizations)

我們建議先閱讀 🔐 角色型存取控制 (RBAC, Role-Based Access Control)，以瞭解 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 resources)
};

每個 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 的資源標示符 (Resource Indicators) 指定請求的最終權限範圍將是所有目標服務中所有權限範圍的笛卡兒積。

因此，在上述情況中，權限範圍可以從 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 資源的存取權杖 (Access token)

要獲取特定 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)。

取得組織權杖 (Organization tokens)

如果你對組織 (Organization) 不熟悉，請閱讀 🏢 組織（多租戶，Multi-tenancy）以開始了解。

在配置 Logto client 時，你需要新增 UserScope.Organizations 權限範圍 (scope)：

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

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

使用者登入後，你可以為使用者獲取組織權杖 (organization token)：

await logtoClient.getOrganizationToken(organizationId);

延伸閱讀

終端使用者流程：驗證流程、帳號流程與組織流程 (End-user flows: authentication flows, account flows, and organization flows) 設定連接器 (Configure connectors) 授權 (Authorization)

先決條件​

安裝​

整合​

初始化 Logto 客戶端​

實作登入​

關於基於重導的登入​

實作登出​

檢查點：觸發驗證流程​

獲取使用者資訊​

顯示使用者資訊​

請求額外的宣告 (Claims)​

需要網路請求的宣告 (Claims)​

權限範圍 (Scopes) 和宣告 (Claims)​

標準 OIDC 權限範圍 (Scopes)​

擴充權限範圍 (Extended scopes)​

API 資源 (API resources) 和組織 (Organizations)​

配置 Logto 用戶端​

取得 API 資源的存取權杖 (Access token)​

取得組織權杖 (Organization tokens)​

延伸閱讀​