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

本指南将向你展示如何将 Logto 集成到你的 Webflow 网站中。

提示

示例项目可在 Webflow 项目预览查看。
在线演示部署在 https://charless-trendy-site-f191c0.webflow.io/。

前提条件

将 Logto 与 Webflow 集成需要 Webflow 的“自定义代码”功能，这至少需要“基础”计划。
一个 Webflow 网站，可以使用现有网站或创建一个新网站。

集成

初始化 Logto 提供程序

备注

在以下步骤中，我们假设你的 Webflow 网站运行在 https://your-awesome-site.webflow.io。

在此步骤中，我们将为你的 Webflow 网站添加全局级别的自定义代码。由于 Webflow 不支持 NPM，我们将使用 jsdelivr.com CDN 服务来导入 Logto SDK。

打开“Site settings”页面，导航到“Custom code”部分。将以下代码添加到“Head code”部分。

<script type="module">
  // 从 jsdelivr CDN 导入 `@logto/browser` SDK
  import LogtoClient from 'https://esm.run/@logto/browser';

  // 将 `logtoClient` 实例分配给 window 对象，
  // 以便在其他页面中全局使用
  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>', // 例如 http://localhost:3001
    appId: '<your-application-id>',
  });
</script>

实现登录

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

你的应用调用登录方法。
用户被重定向到 Logto 登录页面。对于原生应用，将打开系统浏览器。
用户登录并被重定向回你的应用（配置为重定向 URI）。

关于基于重定向的登录

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

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

配置登录重定向 URI

让我们切换到 Logto Console 的应用详情页面。添加一个重定向 URI https://your-awesome-site.webflow.io/callback 并点击“保存更改”。

实现登录按钮

返回到你的 Webflow 设计器，拖放一个“登录”按钮到主页，并为其分配一个 ID “sign-in”，以便稍后使用 getElementById() 进行引用。

<script type="module">
  const signInButton = document.getElementById('sign-in');
  const onClickSignIn = () => logtoClient.signIn('https://your-awesome-site.webflow.io/callback');
  signInButton.addEventListener('click', onClickSignIn);
</script>

处理重定向

我们快完成了！在最后一步中，我们使用 https://your-awesome-site.webflow.io/callback 作为重定向 URI，现在我们需要正确处理它。

首先，让我们在 Webflow 中创建一个“Callback”页面，并简单地放置一些静态文本“正在重定向...”。然后将以下页面级自定义代码添加到“Callback”页面。

<script type="module">
  (async () => {
    // 通过调用 SDK 方法处理登录回调逻辑
    await logtoClient.handleSignInCallback(window.location.href);

    // 处理完成后重定向回主页
    window.location.assign('https://your-awesome-site.webflow.io');
  })();
</script>

实现登出

调用 .signOut() 将清除内存和 localStorage 中的所有 Logto 数据（如果存在）。

注销后，最好将用户重定向回你的网站。让我们在管理控制台中将 https://your-awesome-site.webflow.io 添加为注销后 URI（显示在重定向 URI 下），并在调用 .signOut() 时使用该 URL 作为参数。

实现一个注销按钮

返回 Webflow 设计器，在你的主页上添加一个“注销”按钮。同样，为按钮分配一个 ID “sign-out”，并将以下代码添加到页面级自定义代码中。

const signOutButton = document.getElementById('sign-out');
const onClickSignOut = () => logtoClient.signOut('https://your-awesome-site.webflow.io');
signOutButton.addEventListener('click', onClickSignOut);

处理认证 (Authentication) 状态

在 Logto SDK 中，我们通常可以使用 logtoClient.isAuthenticated() 方法来检查认证 (Authentication) 状态，如果用户已登录，值将为 true；否则，将为 false。

在你的 Webflow 网站中，你也可以使用它来通过编程方式显示和隐藏登录和注销按钮。应用以下自定义代码以相应地调整按钮的 CSS。

const isAuthenticated = await logtoClient.isAuthenticated();

signInButton.style.display = isAuthenticated ? 'none' : 'block';
signOutButton.style.display = isAuthenticated ? 'block' : 'none';

检查点：测试你的 Webflow 网站

现在，测试你的网站：

部署并访问你的网站 URL，登录按钮应该是可见的。
点击登录按钮，SDK 将启动登录过程，将你重定向到 Logto 登录页面。
登录后，你将被重定向回你的网站，看到用户名和退出按钮。
点击退出按钮以退出。

获取用户信息

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

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

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

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

简而言之，当你请求一个权限时，你将获得用户信息中的相应声明。例如，如果你请求 `email` 权限，你将获得用户的 `email` 和 `email_verified` 数据。

默认情况下，Logto SDK 总是会请求三个权限：`openid`、`profile` 和 `offline_access`，并且无法移除这些默认权限。但你可以在配置 Logto 时添加更多权限：

<script type="module">
  // 从 jsdelivr CDN 导入 `@logto/browser` SDK
  import LogtoClient from 'https://esm.run/@logto/browser';

  // 将 `logtoClient` 实例分配给 window 对象，
  // 以便在其他页面中全局使用
  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>', // 例如 http://localhost:3001
    appId: '<your-application-id>',
    scopes: [
      UserScope.Email,
      UserScope.Phone,
      UserScope.CustomData,
      UserScope.Identities,
      UserScope.Organizations,
    ],
  });
</script>

以下是支持的权限（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 时添加它们：

<script type="module">
  // 从 jsdelivr CDN 导入 `@logto/browser` SDK
  import LogtoClient from 'https://esm.run/@logto/browser';

  // 将 `logtoClient` 实例分配给 window 对象，
  // 以便在其他页面中全局使用
  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>', // 例如 http://localhost:3001
    appId: '<your-application-id>',
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // 添加 API 资源 (API resources)
  });
</script>

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

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

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

<script type="module">
  // 从 jsdelivr CDN 导入 `@logto/browser` SDK
  import LogtoClient from 'https://esm.run/@logto/browser';

  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>',
    appId: '<your-application-id>',
    scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
  });
</script>

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

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

<script type="module">
  // 从 jsdelivr CDN 导入 `@logto/browser` SDK
  import LogtoClient from 'https://esm.run/@logto/browser';

  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>',
    appId: '<your-application-id>',
    scopes: ['read', 'write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
  });
</script>

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

备注

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

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

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

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

const isAuthenticated = await logtoClient.isAuthenticated();

if (isAuthenticated) {
  (async () => {
    const token = await logtoClient.getAccessToken();
    console.log(token);
  })();
}

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

获取组织令牌 (Organization tokens)

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

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

import LogtoClient, { UserScope } from 'https://esm.run/@logto/browser';

window.logtoClient = new LogtoClient({
  // ...other configs
  scopes: [UserScope.Organizations],
});

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

import { UserScope } from 'https://esm.run/@logto/browser';

const isAuthenticated = await logtoClient.isAuthenticated();

(async () => {
  if (!isAuthenticated) {
    return;
  }
  const claims = await logtoClient.getIdTokenClaims();

  console.log('ID 令牌声明 (ID token claims):', claims);
  console.log('组织 (Organization) IDs:', claims.organizations);

  // 假设至少有一个组织 (Organization)，我们取第一个
  const organizationId = claims.organizations[0];
  const token = await logtoClient.getOrganizationToken(organizationId);

  console.log('组织 (Organization) 访问令牌 (access token):', token);
})();

延伸阅读

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

前提条件​

集成​

初始化 Logto 提供程序​

实现登录​

配置登录重定向 URI​

实现登录按钮​

处理重定向​

实现登出​

实现一个注销按钮​

处理认证 (Authentication) 状态​

检查点：测试你的 Webflow 网站​

获取用户信息​

API 资源​

配置 Logto 客户端​

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

获取组织令牌 (Organization tokens)​

延伸阅读​