為你的 React 應用程式新增驗證 (Authentication)
本指南將向你展示如何將 Logto 整合到你的 React 應用程式中。
- 範例專案可在我們的 SDK repository 中找到。
- 教學影片可在我們的 YouTube 頻道 上觀看。
先決條件
- 一個 Logto Cloud 帳戶或 自託管 Logto。
- 在 Logto Console 中創建的單頁應用程式 (SPA)。
- 一個 React 專案。
安裝
透過你喜愛的套件管理器安裝 Logto SDK：
- npm
- pnpm
- yarn
npm i @logto/reactpnpm add @logto/reactyarn add @logto/react整合
初始化 Logto 提供者
在你的應用程式中導入並使用 LogtoProvider 來提供 Logto 上下文：
import { LogtoProvider, LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
endpoint: '<your-logto-endpoint>', // 例如：http://localhost:3001
appId: '<your-application-id>',
};
const App = () => (
<LogtoProvider config={config}>
<YourAppContent />
</LogtoProvider>
);
配置重定向 URI
在深入細節之前，以下是終端使用者體驗的快速概覽。登入流程可簡化如下：
- 你的應用程式呼叫登入方法。
- 使用者被重定向至 Logto 登入頁面。對於原生應用程式，系統瀏覽器會被開啟。
- 使用者登入後被重定向回你的應用程式（配置為重定向 URI）。
關於基於重導的登入
- 此驗證流程遵循 OpenID Connect (OIDC) 協議，Logto 強制執行嚴格的安全措施以保護使用者登入。
- 如果你有多個應用程式，可以使用相同的身分提供者 (IdP, Identity provider)（Logto）。一旦使用者登入其中一個應用程式，Logto 將在使用者訪問另一個應用程式時自動完成登入流程。
欲了解更多關於基於重導登入的原理和優勢，請參閱 Logto 登入體驗解析。
在以下的程式碼片段中，我們假設你的應用程式運行在 http://localhost:3000/。
配置重定向 URI
切換到 Logto Console 的應用程式詳細資訊頁面。新增一個重定向 URI http://localhost:3000/callback。
就像登入一樣，使用者應被重定向到 Logto 以登出共享會話。完成後，將使用者重定向回你的網站會很不錯。例如，將 http://localhost:3000/ 新增為登出後重定向 URI 區段。
然後點擊「儲存」以保存更改。
處理重定向
由於我們使用 http://localhost:3000/callback 作為重定向 URI，現在我們需要妥善處理它。
首先，讓我們建立一個回調頁面：
import { useHandleSignInCallback } from '@logto/react';
const Callback = () => {
const { isLoading } = useHandleSignInCallback(() => {
// 完成後執行某些操作，例如重定向到首頁
});
// 當處於進行中時
if (isLoading) {
return <div>正在重定向...</div>;
}
return null;
};
最後，插入以下程式碼以建立一個不需要驗證的 /callback 路由：
// 假設使用 react-router
<Route path="/callback" element={<Callback />} />
實作登入與登出
我們提供兩個 hooks useHandleSignInCallback() 和 useLogto()，可以幫助你輕鬆管理驗證流程。
在呼叫 .signIn() 之前，請確保已在管理控制台中正確配置了 Redirect URI。
import { useLogto } from '@logto/react';
const Home = () => {
const { signIn, signOut, isAuthenticated } = useLogto();
return isAuthenticated ? (
<button onClick={signOut}>Sign Out</button>
) : (
<button onClick={() => signIn('http://localhost:3000/callback')}>Sign In</button>
);
};
呼叫 .signOut() 將清除記憶體和 localStorage 中所有的 Logto 資料（如果存在）。
檢查點：測試你的應用程式
現在，你可以測試你的應用程式：
- 執行你的應用程式，你會看到登入按鈕。
- 點擊登入按鈕，SDK 會初始化登入流程並將你重定向到 Logto 登入頁面。
- 登入後，你將被重定向回應用程式並看到登出按鈕。
- 點擊登出按鈕以清除權杖存儲並登出。
獲取使用者資訊
顯示使用者資訊
要顯示使用者的資訊，你可以使用 getIdTokenClaims() 方法。例如，在你的 Home 頁面中：
import { useLogto, type IdTokenClaims } from '@logto/react';
import { useEffect, useState } from 'react';
const Home = () => {
const { isAuthenticated, getIdTokenClaims } = useLogto();
const [user, setUser] = useState<IdTokenClaims>();
useEffect(() => {
(async () => {
if (isAuthenticated) {
const claims = await getIdTokenClaims();
setUser(claims);
}
})();
}, [getIdTokenClaims, isAuthenticated]);
return (
// ...
{isAuthenticated && user && (
<table>
<thead>
<tr>
<th>名稱</th>
<th>值</th>
</tr>
</thead>
<tbody>
{Object.entries(user).map(([key, value]) => (
<tr key={key}>
<td>{key}</td>
<td>{typeof value === 'string' ? value : JSON.stringify(value)}</td>
</tr>
))}
</tbody>
</table>
)}
);
}
請求額外的宣告 (Claims)
你可能會發現從 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)，你可以配置 Logto provider 的設定：
import { LogtoConfig, UserScope } from '@logto/react';
const config: LogtoConfig = {
// ...其他設定
scopes: [
UserScope.Email,
UserScope.Phone,
UserScope.CustomData,
UserScope.Identities,
UserScope.Organizations,
],
};
然後你可以在 getIdTokenClaims() 的返回值中存取額外的宣告 (Claims)：
const claims = await getIdTokenClaims();
// 現在你可以存取額外的宣告 (Claims) `claims.email`、`claims.phone` 等。
需要網路請求的宣告 (Claims)
為了防止 ID 權杖 (ID token) 膨脹，某些宣告 (Claims) 需要透過網路請求來獲取。例如，即使在權限範圍 (Scopes) 中請求了 custom_data 宣告，它也不會包含在使用者物件中。要存取這些宣告，你可以使用 fetchUserInfo() 方法：
const { fetchUserInfo } = useLogto();
const userInfo = await fetchUserInfo();
// 現在你可以存取宣告 (Claim) `userInfo.custom_data`
權限範圍 (Scopes) 和宣告 (Claims)
Logto 使用 OIDC 權限範圍 (Scopes) 和宣告 (Claims) 慣例 來定義從 ID 權杖 (ID token) 和 OIDC 使用者資訊端點 (userinfo endpoint) 獲取使用者資訊的權限範圍和宣告。無論是「權限範圍 (Scope)」還是「宣告 (Claim)」，都是 OAuth 2.0 和 OpenID Connect (OIDC) 規範中的術語。
以下是支援的權限範圍 (Scopes) 及其對應的宣告 (Claims)：
openid
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| sub | string | 使用者的唯一識別符 | 否 |
profile
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| name | string | 使用者的全名 | 否 |
| username | string | 使用者的用戶名 | 否 |
| picture | string | 使用者個人資料圖片的 URL。此 URL 必須指向圖像文件（例如 PNG、JPEG 或 GIF 圖像文件），而不是包含圖像的網頁。請注意，此 URL 應特別參考適合在描述使用者時顯示的個人資料照片，而不是使用者拍攝的任意照片。 | 否 |
| created_at | number | 使用者創建的時間。時間以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。 | 否 |
| updated_at | number | 使用者資訊最後更新的時間。時間以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。 | 否 |
其他 標準宣告 包括 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 和 locale 也將包含在 profile 權限範圍中，無需請求使用者資訊端點。與上述宣告的不同之處在於，這些宣告僅在其值不為空時返回，而上述宣告在值為空時將返回 null。
與標準宣告不同，created_at 和 updated_at 宣告使用毫秒而非秒。
email
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
string | 使用者的電子郵件地址 | 否 | |
| email_verified | boolean | 電子郵件地址是否已驗證 | 否 |
phone
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| phone_number | string | 使用者的電話號碼 | 否 |
| phone_number_verified | boolean | 電話號碼是否已驗證 | 否 |
address
請參閱 OpenID Connect Core 1.0 以獲取地址宣告的詳細資訊。
custom_data
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| custom_data | object | 使用者的自訂資料 | 是 |
identities
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| identities | object | 使用者的連結身分 | 是 |
| sso_identities | array | 使用者的連結 SSO 身分 | 是 |
roles
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| roles | string[] | 使用者的角色 | 否 |
urn:logto:scope:organizations
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| organizations | string[] | 使用者所屬的組織 ID | 否 |
| organization_data | object[] | 使用者所屬的組織資料 | 是 |
urn:logto:scope:organization_roles
| 宣告名稱 | 類型 | 描述 | 需要使用者資訊嗎？ |
|---|---|---|---|
| organization_roles | string[] | 使用者所屬的組織角色，格式為 <organization_id>:<role_name> | 否 |
考慮到效能和資料大小，如果「需要使用者資訊嗎？」為「是」，則表示該宣告不會顯示在 ID 權杖中，而會在 使用者資訊端點 回應中返回。
API 資源
我們建議先閱讀 🔐 角色型存取控制 (RBAC, Role-Based Access Control)，以瞭解 Logto RBAC 的基本概念以及如何正確設定 API 資源。
配置 Logto 用戶端
一旦你設定了 API 資源，就可以在應用程式中配置 Logto 時新增它們：
import { LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
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 { LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
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 { LogtoConfig } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
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 方法：
import { useLogto } from '@logto/react';
const Home = () => {
const { isAuthenticated, getAccessToken } = useLogto();
const [accessToken, setAccessToken] = useState('');
useEffect(() => {
(async () => {
if (isAuthenticated) {
const token = await getAccessToken('https://shopping.your-app.com/api');
setAccessToken(token);
}
})();
}, [isAuthenticated, getAccessToken]);
return <p>{{ accessToken }}</p>;
};
此方法將返回一個 JWT 存取權杖 (Access token)，當使用者擁有相關權限時，可以用來存取 API 資源。如果當前快取的存取權杖 (Access token) 已過期，此方法將自動嘗試使用重新整理權杖 (Refresh token) 獲取新的存取權杖 (Access token)。
取得組織權杖 (Organization tokens)
如果你對組織 (Organization) 不熟悉，請閱讀 🏢 組織（多租戶，Multi-tenancy） 以開始了解。
在配置 Logto client 時，你需要新增 UserScope.Organizations 權限範圍 (scope)：
import { LogtoConfig, UserScope } from '@logto/react';
const config: LogtoConfig = {
// ...other configs
scopes: [UserScope.Organizations],
};
使用者登入後，你可以為使用者獲取組織權杖 (organization token)：
import { useLogto } from '@logto/react';
import { useEffect, useState } from 'react';
const Organizations = () => {
const { isAuthenticated, getOrganizationToken, getIdTokenClaims } = useLogto();
const [organizationIds, setOrganizationIds] = useState<string[]>();
useEffect(() => {
(async () => {
if (!isAuthenticated) {
return;
}
const claims = await getIdTokenClaims();
console.log('ID 權杖 (ID token) 宣告 (claims)', claims);
setOrganizationIds(claims?.organizations);
})();
}, [isAuthenticated, getIdTokenClaims]);
return (
<section>
<ul>
{organizationIds?.map((organizationId) => {
return (
<li key={organizationId}>
<span>{organizationId}</span>
<button
type="button"
onClick={async () => {
console.log('原始權杖 (raw token)', await getOrganizationToken(organizationId));
}}
>
取得權杖 (fetch token)（查看主控台）
</button>
</li>
);
})}
</ul>
</section>
);
};
export default Organizations;
將存取權杖 (Access token) 附加到請求標頭
將權杖放在 HTTP 標頭的 Authorization 欄位中，使用 Bearer 格式（Bearer YOUR_TOKEN），即可完成。
Bearer 權杖的整合流程可能會根據你使用的框架或請求者而有所不同。選擇適合你的方式來應用請求的 Authorization 標頭。