為你的 Vue 3 應用程式新增驗證 (Authentication)

本指南將向你展示如何將 Logto 整合到你的 Vue 3 應用程式中。

提示:

• Logto Vue SDK 是使用 composition API 建構並利用 composables，因此僅與 Vue 3 相容。
• 教學影片可在我們的 YouTube 頻道 上觀看。
• 完整範例專案可在我們的 SDK 儲存庫 中找到。

先決條件

• 一個 Logto Cloud 帳戶或 自託管 Logto。
• 在 Logto Console 中創建的單頁應用程式 (SPA)。
• 一個 Vue 3 專案。

安裝

npm

npm i @logto/vue

pnpm

pnpm add @logto/vue

yarn

yarn add @logto/vue

整合

初始化 LogtoClient

匯入並使用 createLogto 來安裝 Logto 插件：

main.ts

import { createLogto, LogtoConfig } from '@logto/vue';
import { createApp } from 'vue';
import App from './App.vue';

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

const app = createApp(App);

app.use(createLogto, config);
app.mount('#app');

配置重定向 URI

在深入細節之前，以下是終端使用者體驗的快速概覽。登入流程可簡化如下：

1. 你的應用程式呼叫登入方法。
2. 使用者被重定向至 Logto 登入頁面。對於原生應用程式，系統瀏覽器會被開啟。
3. 使用者登入後被重定向回你的應用程式（配置為重定向 URI）。

關於基於重導的登入

1. 此驗證流程遵循 OpenID Connect (OIDC) 協議，Logto 強制執行嚴格的安全措施以保護使用者登入。
2. 如果你有多個應用程式，可以使用相同的身分提供者 (IdP, Identity provider)（Logto）。一旦使用者登入其中一個應用程式，Logto 將在使用者訪問另一個應用程式時自動完成登入流程。

欲了解更多關於基於重導登入的原理和優勢，請參閱 Logto 登入體驗解析。

---

備註:

在以下的程式碼片段中，我們假設你的應用程式運行在 http://localhost:3000/。

配置重定向 URI

切換到 Logto Console 的應用程式詳細資訊頁面。新增一個重定向 URI http://localhost:3000/callback。

就像登入一樣，使用者應被重定向到 Logto 以登出共享會話。完成後，將使用者重定向回你的網站會很不錯。例如，將 http://localhost:3000/ 新增為登出後重定向 URI 區段。

然後點擊「儲存」以保存更改。

處理重定向

使用者從 Logto 重定向回你的應用程式後，還有一些事情需要處理。我們來妥善處理這些事項。

首先，讓我們建立一個回呼頁面：

views/CallbackView.vue

import { useHandleSignInCallback } from '@logto/vue';
import router from '@/router';

const { isLoading } = useHandleSignInCallback(() => {
  // 完成後執行某些操作，例如重定向到首頁
});

<template>
  <!-- 當處於進行中時 -->
  <p v-if="isLoading">正在重定向...</p>
</template>

將以下程式碼插入到不需要驗證的 /callback 路由中：

router/index.ts

// 假設使用 vue-router
const router = createRouter({
  routes: [
    {
      path: '/callback',
      name: 'callback',
      component: CallbackView,
    },
  ],
});

實作登入與登出

我們提供兩個可組合的函式 useHandleSignInCallback() 和 useLogto()，可以幫助你輕鬆管理驗證 (Authentication) 流程。

備註:

在呼叫 .signIn() 之前，請確保已在管理控制台中正確配置了 Redirect URI。

views/HomeView.vue

import { useLogto } from '@logto/vue';

const { signIn, signOut, isAuthenticated } = useLogto();

const onClickSignIn = () => signIn('http://localhost:3000/callback');
const onClickSignOut = () => signOut('http://localhost:3000');

<template>
  <button v-if="!isAuthenticated" @click="onClickSignIn">登入</button>
  <button v-else @click="onClickSignOut">登出</button>
</template>

呼叫 .signOut() 將清除記憶體和 localStorage 中所有的 Logto 資料（如果存在）。

檢查點：測試你的應用程式

現在，你可以測試你的應用程式：

1. 執行你的應用程式，你會看到登入按鈕。
2. 點擊登入按鈕，SDK 會初始化登入流程並將你重定向到 Logto 登入頁面。
3. 登入後，你將被重定向回應用程式並看到登出按鈕。
4. 點擊登出按鈕以清除權杖存儲並登出。

獲取使用者資訊

顯示使用者資訊

要顯示使用者資訊，你可以使用 getIdTokenClaims() 方法。例如，在你的 Home 頁面中：

views/HomeView.vue

import { useLogto, type IdTokenClaims } from '@logto/vue';
import { ref } from 'vue';

const { isAuthenticated, getIdTokenClaims } = useLogto();
const user = ref<IdTokenClaims>();

if (isAuthenticated.value) {
  (async () => {
    const claims = await getIdTokenClaims();
    user.value = claims;
  })();
}

<template>
  <div v-if="isAuthenticated && user">
    <table class="table">
      <thead>
        <tr>
          <th>名稱</th>
          <th>值</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="(value, key) in user" v-bind:key="key">
          <td>{{ key }}</td>
          <td>{{ typeof value === "string" ? value : JSON.stringify(value) }}</td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

請求額外的宣告 (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 的設定：

main.ts

import { createLogto, UserScope } from '@logto/vue';

const app = createApp(App);

app.use(createLogto, {
  // ...其他設定
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations,
  ],
});
app.use(router);

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

const claims = await getIdTokenClaims();
// 現在你可以訪問額外的宣告 `claims.email`、`claims.phone` 等。

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

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

const { fetchUserInfo } = useLogto();

const userInfo = await fetchUserInfo();

// 現在你可以訪問宣告 `userInfo.custom_data`

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

權限範圍 (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

宣告名稱	類型	描述	需要使用者資訊嗎？
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 時新增它們：

main.ts

import { createLogto } from '@logto/vue';

app.use(createLogto, {
  // ...other configs
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
});

每個 API 資源都有其自身的權限（權限範圍）。

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

要請求這些權限，你可以在應用程式中配置 Logto 時新增它們：

main.ts

import { createLogto } from '@logto/vue';

app.use(createLogto, {
  // ...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 配置中：

main.ts

import { createLogto } from '@logto/vue';

app.use(createLogto, {
  // ...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 資源的存取權杖

要獲取特定 API 資源的存取權杖 (Access token)，你可以使用 getAccessToken 方法：

views/HomeView.vue

import { useLogto, type UserInfoResponse } from '@logto/vue';

const { isAuthenticated, getAccessToken } = useLogto();

if (isAuthenticated.value) {
  (async () => {
    const accessToken = await getAccessToken('https://shopping.your-app.com/api');
    console.log(accessToken);
  })();
}

此方法將返回一個 JWT 存取權杖 (Access token)，當使用者擁有相關權限時，可以用來存取 API 資源。如果當前快取的存取權杖 (Access token) 已過期，此方法將自動嘗試使用重新整理權杖 (Refresh token) 獲取新的存取權杖 (Access token)。

獲取組織權杖

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

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

main.ts

import { createLogto, UserScope } from '@logto/vue';

app.use(createLogto, {
  // ...other configs
  scopes: [UserScope.Organizations],
});

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

views/OrganizationsView.vue

import { useLogto } from '@logto/vue';
import { onMounted, ref } from 'vue';

const { getOrganizationToken, getOrganizationTokenClaims, getIdTokenClaims } = useLogto();
const organizationIds = ref<string[]>();

onMounted(async () => {
  const claims = await getIdTokenClaims();

  console.log('ID 權杖 (ID token) 宣告 (claims)', claims);
  organizationIds.value = claims?.organizations;
});

const onClickFetchOrganizationToken = async (organizationId: string) => {
  console.log('原始權杖 (raw token)', await getOrganizationToken(organizationId));
  console.log('宣告 (claims)', await getOrganizationTokenClaims(organizationId));
};

<template>
  <ul>
    <li v-for="organizationId of organizationIds" v-bind:key="organizationId">
      <span>{{ organizationId }}</span>
      <button type="button" @click="onClickFetchOrganizationToken(organizationId)">
        取得權杖 (fetch token)（查看控制台）
      </button>
    </li>
  </ul>
</template>

將存取權杖附加到請求標頭

將權杖放在 HTTP 標頭的 Authorization 欄位中，使用 Bearer 格式（Bearer YOUR_TOKEN），即可開始使用。

備註:

Bearer 權杖的整合流程可能會根據你使用的框架或請求者而有所不同。選擇適合你的方式來應用請求的 Authorization 標頭。

進一步閱讀

終端使用者流程：驗證流程、帳戶流程與組織流程 配置連接器 保護你的 API