为你的 Vue 3 应用添加认证 (Authentication)

本指南将向你展示如何将 Logto 集成到你的 Vue 3 应用中。

提示:

• Logto Vue SDK 是使用组合式 API 构建的，并利用了可组合函数，因此它仅兼容 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. 此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议，Logto 强制执行严格的安全措施以保护用户登录。
2. 如果你有多个应用程序，可以使用相同的身份提供商 (IdP)（日志 (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>

将以下代码插入到不需要认证 (Authentication) 的 /callback 路由中：

router/index.ts

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

实现登录和登出

我们提供了两个组合式函数 useHandleSignInCallback() 和 useLogto() ，可以帮助你轻松管理认证 (Authentication) 流程。

备注:

在调用 .signIn() 之前，请确保你已在管理控制台中正确配置了重定向 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)，而 Logto 是基于这些标准构建的。

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

信息:

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

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

提示:

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

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

要请求额外的权限 (Scopes)，你可以配置 Logto provider 配置：

main.ts

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

const app = createApp(App);

app.use(createLogto, {
  // ...other configs
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations,
  ],
});
app.use(router);

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

const claims = await getIdTokenClaims();
// 现在你可以访问额外的声明 (Claims) `claims.email`，`claims.phone`，等等。

需要网络请求的声明

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

const { fetchUserInfo } = useLogto();

const userInfo = await fetchUserInfo();

// 现在你可以访问声明 (Claim) `userInfo.custom_data`

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

权限 (Scopes) 和声明 (Claims)

Logto 使用 OIDC 权限和声明约定 来定义从 ID 令牌和 OIDC 用户信息端点检索用户信息的权限和声明。“权限”和“声明”都是 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 纪元（1970-01-01T00:00:00Z）以来的毫秒数。	否
updated_at	number	终端用户信息最后更新的时间。时间表示为自 Unix 纪元（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 身份	是

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)，以了解 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 的资源指示器 指定请求的最终权限将是所有目标服务中所有权限的笛卡尔积。

因此，在上述情况下，权限可以从 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)。

获取组织令牌

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

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

main.ts

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

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

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

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('原始令牌 (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)">
        获取令牌 (token) （查看控制台）
      </button>
    </li>
  </ul>
</template>

将访问令牌附加到请求头

将令牌放在 HTTP 头的 Authorization 字段中，使用 Bearer 格式（Bearer YOUR_TOKEN），然后你就可以开始了。

备注:

Bearer 令牌的集成流程可能会根据你使用的框架或请求者而有所不同。选择你自己的方式来应用请求的 Authorization 头。

延伸阅读

终端用户流程：认证流程、账户流程和组织流程 配置连接器 保护你的 API