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

提示:

• 以下演示基于 SvelteKit 2.0.0 构建。
• 示例项目可在 GitHub 仓库 中找到。

前提条件

• 一个 Logto Cloud 账户或一个 自托管 Logto。
• 一个已创建的 Logto 传统 Web 应用程序。

安装

通过你喜欢的包管理器安装 Logto SDK：

npm

npm i @logto/sveltekit

pnpm

pnpm add @logto/sveltekit

yarn

yarn add @logto/sveltekit

集成

添加 Logto hook

在你的 hooks.server.ts 文件中，添加以下代码将 Logto hook 注入到你的服务器中：

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    endpoint: '<your-logto-endpoint>',
    appId: '<your-logto-app-id>',
    appSecret: '<your-logto-app-secret>',
  },
  {
    encryptionKey: '<a-random-string>',
  }
);

由于这些信息是敏感的，建议使用环境变量：

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';
import { env } from '$env/dynamic/private';

export const handle = handleLogto(
  {
    endpoint: env.LOGTO_ENDPOINT,
    appId: env.LOGTO_APP_ID,
    appSecret: env.LOGTO_APP_SECRET,
  },
  {
    encryptionKey: env.LOGTO_COOKIE_ENCRYPTION_KEY,
  }
);

如果你有多个 hooks，可以使用 sequence() helper function 来将它们串联起来：

hooks.server.ts

import { sequence } from '@sveltejs/kit/hooks';

export const handle = sequence(handleLogto, handleOtherHook);

现在你可以在 locals 对象中访问 Logto 客户端。对于 TypeScript，你可以在 app.d.ts 中添加类型：

import type { LogtoClient, UserInfoResponse } from '@logto/sveltekit';

declare global {
  namespace App {
    interface Locals {
      logtoClient: LogtoClient;
      user?: UserInfoResponse;
    }
  }
}

我们稍后会讨论 user 对象。

实现登录和登出

备注:

在以下代码片段中，我们假设你的应用程序运行在 http://localhost:3000/。

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

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

关于基于重定向的登录

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

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

---

配置重定向 URI

切换到 Logto Console 的应用详情页面。添加一个重定向 URI http://localhost:3000/callback。

就像登录一样，用户应该被重定向到 Logto 以注销共享会话。完成后，最好将用户重定向回你的网站。例如，添加 http://localhost:3000/ 作为注销后重定向 URI 部分。

然后点击“保存”以保存更改。

在你想要实现登录和登出的页面中，定义以下操作：

+page.server.ts

import type { Actions } from './$types';

export const actions: Actions = {
  signIn: async ({ locals }) => {
    await locals.logtoClient.signIn('http://localhost:3000/callback');
  },
  signOut: async ({ locals }) => {
    await locals.logtoClient.signOut('http://localhost:3000/');
  },
};

然后在你的 Svelte 组件中使用这些操作：

+page.svelte

<form method="POST" action="?/{data.user ? 'signOut' : 'signIn'}">
  <button type="submit">Sign {data.user ? 'out' : 'in'}</button>
</form>

检查点：测试你的应用程序

现在，你可以测试你的应用程序：

1. 运行你的应用程序，你将看到登录按钮。
2. 点击登录按钮，SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
3. 登录后，你将被重定向回你的应用程序，并看到登出按钮。
4. 点击登出按钮以清除令牌存储并登出。

获取用户信息

显示用户信息

要显示用户的信息，你可以将 locals.user 对象注入到布局中，从而使其在所有页面中可用：

+layout.server.ts

import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async ({ locals }) => {
  return { user: locals.user };
};

在你的 Svelte 组件中：

+page.svelte

<script>
  /** @type {import('./$types').PageData} */
  export let data;
</script>

{#if data.user}
<ul>
  {#each Object.entries(data.user) as [key, value]}
  <li>{key}: {value}</li>
  {/each}
</ul>
{/if}

请求额外的声明 (Claims)

你可能会发现从 locals.user 返回的对象中缺少一些用户信息。这是因为 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)，你可以将权限传递给 handleLogto 函数中的 LogtoConfig 对象：

hooks.server.ts

import { UserScope, handleLogto } from '@logto/sveltekit';

export const handle = handleLogto({
  // ...other options
  scopes: [UserScope.email, UserScope.phone], // 如有需要，添加更多权限 (Scopes)
});

然后你可以在 locals.user 对象中访问额外的声明 (Claims)。

需要网络请求的声明 (Claims)

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

默认情况下，locals.user 对象是手动调用 getIdTokenClaims 方法的便捷方式。如果你想使用 fetchUserInfo 方法的结果，可以通过为钩子设置 fetchUserInfo 选项为 true 来实现：

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    /* Logto config */
  },
  {
    /* Cookie config */
  },
  {
    fetchUserInfo: true,
  }
);

手动获取用户信息

你可以使用这些 Logto 方法以编程方式检索用户信息：

• locals.logtoClient.getIdTokenClaims()：通过解码本地 ID 令牌获取用户信息。某些声明可能不可用。
• locals.logtoClient.fetchUserInfo()：通过向 userinfo endpoint 发送请求获取用户信息。

需要注意的是，可以检索的用户信息声明取决于用户在登录时使用的权限，并且考虑到性能和数据大小，ID 令牌可能不包含所有用户声明，某些用户声明仅在 userinfo endpoint 中可用（请参阅下面的相关列表）。

权限 (Scopes) 和声明 (Claims)

Logto 使用 OIDC 权限和声明约定 来定义从 ID 令牌和 OIDC 用户信息端点检索用户信息的权限和声明。“权限”和“声明”都是 OAuth 2.0 和 OpenID Connect (OIDC) 规范中的术语。

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

openid

Claim name	Type	描述	需要 userinfo 吗？
sub	string	用户的唯一标识符	否

profile

Claim name	Type	描述	需要 userinfo 吗？
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	描述	需要 userinfo 吗？
email	string	用户的电子邮件地址	否
email_verified	boolean	电子邮件地址是否已验证	否

phone

Claim name	Type	描述	需要 userinfo 吗？
phone_number	string	用户的电话号码	否
phone_number_verified	boolean	电话号码是否已验证	否

address

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

custom_data

Claim name	Type	描述	需要 userinfo 吗？
custom_data	object	用户的自定义数据	是

identities

Claim name	Type	描述	需要 userinfo 吗？
identities	object	用户关联的身份信息	是
sso_identities	array	用户关联的 SSO 身份信息	是

roles

Claim name	Type	描述	需要 userinfo 吗？
roles	string[]	用户的角色 (Roles)	否

urn:logto:scope:organizations

Claim name	Type	描述	需要 userinfo 吗？
organizations	string[]	用户所属的组织 (Organizations) ID 列表	否
organization_data	object[]	用户所属的组织 (Organizations) 数据	是

备注:

这些组织 (Organizations) 声明 (Claims) 也可以通过 userinfo 端点获取，当使用 不透明令牌 (Opaque token) 时也是如此。然而，不透明令牌 (Opaque tokens) 不能作为组织令牌 (Organization tokens) 用于访问组织专属资源。详情请参见 不透明令牌 (Opaque token) 与组织 (Organizations)。

urn:logto:scope:organization_roles

Claim name	Type	描述	需要 userinfo 吗？
organization_roles	string[]	用户所属组织 (Organizations) 的角色 (Roles)，格式为 <organization_id>:<role_name>	否

---

考虑到性能和数据大小，如果“需要 userinfo 吗？”为“是”，则该声明 (Claim) 不会出现在 ID 令牌 (ID token) 中，而会在 userinfo 端点 响应中返回。

API 资源和组织 (Organizations)

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

配置 Logto 客户端

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

hooks.server.ts

export const handle = handleLogto(
  {
    // ...other configs
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // 添加 API 资源 (API resources)
  }
  // ...other configs
);

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

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

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

hooks.server.ts

export const handle = handleLogto(
  {
    // ...other configs
    scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
  }
  // ...other configs
);

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

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

hooks.server.ts

export const handle = handleLogto(
  {
    // ...other configs
    scopes: ['read', 'write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
  }
  // ...other configs
);

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

备注:

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

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

获取 API 资源的访问令牌 (Access token)

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

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

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

获取组织令牌 (Organization tokens)

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

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

hooks.server.ts

import { handleLogto, UserScope } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    // ...other configs
    scopes: [UserScope.Organizations],
  }
  // ...other configs
);

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

const token = await locals.logtoClient.getOrganizationToken(organizationId);

延伸阅读

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