跳到主要内容

应用数据结构

简介​

在 Logto 中，应用 指的是已在 Logto 平台注册并被授权访问用户信息或代表用户执行操作的特定软件程序或服务。应用用于标识向 Logto API 发起请求的来源，并管理用户访问这些应用时的认证 (Authentication) 和授权 (Authorization) 流程。

在 Logto 的登录体验中使用应用，可以让用户从一个位置轻松访问和管理他们已授权的应用，并拥有一致且安全的认证 (Authentication) 流程。这有助于简化用户体验，并确保只有被授权的人员才能访问敏感信息或代表组织执行操作。

应用还用于 Logto 的审计日志中，用于追踪用户活动并识别任何潜在的安全威胁或漏洞。通过将特定操作与某个应用关联，Logto 能够提供有关数据如何被访问和使用的详细洞察，帮助组织更好地管理其安全和合规要求。 如果你想将你的应用集成到 Logto，请参阅 集成 Logto。

属性​

应用 ID​

应用 ID 是用于在 Logto 中唯一标识你的应用的自动生成密钥，在 OAuth 2.0 中被称为 client id。

应用类型​

应用 可以是以下应用类型之一：

  • 原生应用：在原生环境中运行的应用。例如 iOS 应用、Android 应用。
    • 设备流应用：是一种专为输入受限设备或无头应用（如智能电视、游戏主机、CLI 工具、IoT 设备）设计的特殊原生应用类型。它使用 OAuth 2.0 设备授权许可 替代标准的基于重定向的流程。详情见 设备流快速入门。
  • 单页应用：在 Web 浏览器中运行的应用，通过从服务器获取新数据来更新页面，而无需加载整个新页面。例如 React DOM 应用、Vue 应用。
  • 传统 Web 应用：仅由 Web 服务器渲染和更新页面的应用。例如 JSP、PHP。
  • 机器对机器 (M2M) 应用：在机器环境中运行、用于直接服务间通信且无需用户交互的应用。

应用密钥​

应用密钥 是用于在认证 (Authentication) 系统中认证应用的密钥，专为私有客户端（传统 Web 和 M2M 应用）作为私有安全屏障。

提示:

单页应用 (SPA) 和原生应用不提供应用密钥。SPA 和原生应用属于“公开客户端”，无法保密密钥（浏览器代码或应用包可被检查）。Logto 通过 PKCE、严格的重定向 URI / CORS 校验、短生命周期访问令牌 (Access token) 和刷新令牌 (Refresh token) 轮换来保护它们，而不是使用应用密钥。

应用名称​

应用名称 是应用的人类可读名称，将显示在管理控制台中。

应用名称 是在 Logto 中管理应用的重要组成部分，因为它允许管理员轻松识别和追踪平台内各个应用的活动。

备注:

需要注意的是，应用名称 应谨慎选择，因为它将对所有有权访问管理控制台的用户可见。它应准确反映应用的用途和功能，同时易于理解和识别。

描述​

应用的简要描述将显示在管理控制台的应用详情页。描述旨在为管理员提供有关应用的更多信息，如用途、功能及其他相关细节。

重定向 URI​

重定向 URI 是为应用预先配置的一组有效重定向 URI。当用户登录 Logto 并尝试访问应用时，他们会被重定向到应用设置中指定的允许 URI 之一。

允许的 URI 列表用于校验应用在认证 (Authentication) 流程中向 Logto 发送的授权请求中包含的重定向 URI。如果授权请求中指定的重定向 URI 与应用设置中的允许 URI 匹配，则用户在认证 (Authentication) 成功后会被重定向到该 URI。如果重定向 URI 不在允许列表中，则不会重定向，认证 (Authentication) 流程会失败。

备注:

务必确保所有有效的重定向 URI 都已添加到 Logto 应用的允许列表中，以确保用户在认证 (Authentication) 后能够成功访问应用。

你可以查阅 重定向端点 了解更多信息。

理解 OIDC 授权码流程中的重定向 URI

通配符模式​

适用范围：单页应用、传统 Web 应用

重定向 URI 支持通配符模式（*），适用于如预览部署等动态环境。通配符可用于 HTTP/HTTPS URI 的主机名和路径名部分。

规则：

  • 通配符仅允许出现在主机名和路径名中
  • 通配符不允许出现在协议、端口、查询参数或哈希片段中
  • 主机名通配符必须包含至少一个点（如 https://*.example.com/callback）

示例：

  • https://*.example.com/callback —— 匹配任意子域
  • https://preview-*.example.com/callback —— 匹配预览部署
  • https://example.com/*/callback —— 匹配任意路径段
警告:

通配符重定向 URI 并非标准 OIDC，且可能增加攻击面。请谨慎使用，并尽量优先使用精确的重定向 URI。

登出后重定向 URI​

登出后重定向 URI 是为应用预先配置的一组有效 URI，用于用户从 Logto 登出后重定向。

允许的 登出后重定向 URI 用于注销，是 OIDC 中 RP 发起（Relying Party Initiated）注销规范的一部分。该规范为应用发起用户注销请求提供了标准化方法，包括在用户登出后重定向到预配置端点。

当用户从 Logto 登出时，其会话被终止，并被重定向到应用设置中指定的允许 URI 之一。这确保用户仅被引导到授权且有效的端点，防止因重定向到未知或未验证端点而导致的未授权访问和安全风险。

你可以查阅 RP 发起注销 了解更多信息。

CORS 允许来源​

CORS（跨域资源共享）允许来源 是允许应用向 Logto 服务发起请求的来源列表。不在允许列表中的来源将无法向 Logto 服务发起请求。

CORS 允许来源列表用于限制来自未授权域的对 Logto 服务的访问，并有助于防止跨站请求伪造（CSRF）攻击。通过在 Logto 中为应用指定允许来源，服务可以确保只有被授权的域能够向服务发起请求。

备注:

允许来源列表应包含应用实际部署的来源。这确保来自应用的请求被允许，而来自未授权来源的请求会被阻止。

OpenID 提供方配置端点​

OpenID Connect 发现 的端点。

授权端点​

授权端点 是 OIDC 术语，是用于启动用户认证 (Authentication) 流程的必需端点。当用户尝试访问已在 Logto 平台注册的受保护资源或应用时，他们会被重定向到 授权端点 以认证 (Authentication) 身份并获取访问所请求资源的授权 (Authorization)。

你可以查阅 授权端点 了解更多信息。

令牌端点​

令牌端点 是 OIDC 术语，是 OIDC 客户端用于从 OIDC 提供方获取访问令牌 (Access token)、ID 令牌 (ID token) 或刷新令牌 (Refresh token) 的 Web API 端点。

当 OIDC 客户端需要获取访问令牌 (Access token) 或 ID 令牌 (ID token) 时，会携带授权许可（通常是授权码或刷新令牌 (Refresh token)）向令牌端点发起请求。令牌端点验证授权许可后，如果有效，则向客户端颁发访问令牌 (Access token) 或 ID 令牌 (ID token)。

你可以查阅 令牌端点 了解更多信息。

Userinfo 端点​

OpenID Connect UserInfo 端点。

始终颁发刷新令牌 (Refresh token)​

适用范围：传统 Web、SPA

启用后，无论认证 (Authentication) 请求中是否包含 prompt=consent，或权限 (Scope) 中是否包含 offline_access，Logto 都会始终颁发刷新令牌 (Refresh token)。

但除非必要（通常用于某些需要刷新令牌 (Refresh token) 的第三方 OAuth 集成），否则不建议这样做，因为这与 OpenID Connect 不兼容，且可能带来潜在问题。

刷新令牌 (Refresh token) 轮换​

默认值：true

启用后，当客户端使用刷新令牌 (Refresh token) 请求新令牌时，Logto 可能会颁发新的刷新令牌 (Refresh token)。如果刷新令牌 (Refresh token) 及其应用授权 (grant) 仍然有效，默认轮换策略如下：

  • 刷新令牌 (Refresh token) 仅可在刷新令牌链存在不超过一年时轮换。这是内部轮换安全上限；刷新令牌自身的 TTL 或应用授权 (grant) TTL 可能更早过期。达到上限后，Logto 不再轮换刷新令牌，当前刷新令牌的过期时间为最终时间。
  • 对于未使用发送方约束刷新令牌的公开客户端（如常规原生应用和单页应用），Logto 在每次刷新令牌请求时轮换刷新令牌，只要允许轮换。
  • 对于其他客户端，Logto 仅在刷新令牌接近过期时轮换（原始 TTL 已过去 >=70%）。
备注:

对于公开客户端，强烈建议出于安全考虑保持刷新令牌 (Refresh token) 轮换开启。

发送方约束刷新令牌绑定到客户端持有的证明密钥或证书。对于常规 SPA，轮换会颁发新刷新令牌，但不会延长刷新令牌的生命周期。新刷新令牌继承前一个刷新令牌的剩余 TTL。

刷新令牌链生命周期:

刷新令牌 (Refresh token) 与应用授权 (grant) 相关联。Logto 默认授权 (grant) TTL 为 180 天。当授权过期时，刷新令牌请求会失败，即使刷新令牌轮换已启用，刷新令牌也无法再用于获取新令牌。

这意味着基于刷新令牌 (Refresh token) 的授权 (Authorization) 的实际最长生命周期目前受限于授权 (grant) TTL、显式吊销或刷新令牌自身的过期时间，以先发生者为准。

理解刷新令牌 (Refresh token) 轮换

刷新令牌 (Refresh token) 存活时间（TTL，天）​

适用范围：原生应用、传统 Web、SPA；默认值：14 天；最大值：180 天

刷新令牌 (Refresh token) 可用于请求新访问令牌 (Access token) 的有效期，过期后将失效。令牌请求会将刷新令牌的 TTL 延长至该值。

通常建议设置较低的值。

备注:

出于安全原因，单页应用 (SPA) 不支持 TTL 刷新。对于 SPA，此设置控制刷新令牌的固定生命周期，从最初颁发时起计算。Logto 不会通过令牌请求延长 TTL，刷新令牌轮换也无法阻止 SPA 刷新令牌过期。

刷新令牌 TTL 与授权 (grant) TTL:

刷新令牌 TTL 并不是唯一的过期限制。刷新令牌与应用授权 (grant) 绑定，Logto 默认授权 (grant) TTL 为 180 天。当授权过期时，即使刷新令牌本身仍然有效，刷新令牌请求也会失败。

对于令牌请求会刷新刷新令牌 TTL 的客户端，授权 (grant) TTL 是刷新令牌链的绝对最长生命周期。对于 SPA，刷新令牌的固定 TTL 可能会在授权 (grant) 过期前先到期。

刷新令牌与会话绑定:

当刷新令牌 (Refresh token) 在授权请求中未包含 offline_access 权限 (Scope) 时，它将绑定到用户会话。会话的固定 TTL 为 14 天。会话过期后，无论刷新令牌自身 TTL 设置如何，刷新令牌都会失效。

如需刷新令牌 TTL 设置完全生效，请确保在授权请求中包含 offline_access 权限 (Scope)。

后端注销 URI​

OpenID Connect 后端注销端点。详见 联合登出：后端注销。

最大允许授权数 (maxAllowedGrants)​

maxAllowedGrants 是 customClientMetadata 下的可选应用级字段，用于控制当前应用每个用户最多可同时拥有的活跃授权 (grant) 数量。

  • 默认值：undefined（无限制）
  • 配置后：每次授权 (Authorization) 成功，Logto 会检查当前应用下该用户的所有活跃授权（跨浏览器和设备）。如果超出限制，Logto 会吊销最早的授权。

当你希望限制每个应用的并发认证 (Authentication) 设备数量时，此设置非常有用。

备注:

该字段不支持以下类型：

  • 机器对机器 (M2M) 应用
  • 受保护应用
  • SAML 应用

自定义数据​

未在预定义应用属性中列出的其他自定义应用信息，用户可根据自身需求定义自定义数据字段，如业务相关设置和配置。