跳到主要内容

应用程序数据结构

简介​

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

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

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

属性​

应用程序 ID​

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

应用程序类型​

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

  • 原生应用：运行在原生环境中的应用。例如，iOS 应用、Android 应用。
  • 单页应用 (Single page app)：运行在 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 发送的授权 (Authorization) 请求中包含的重定向 URI。如果授权 (Authorization) 请求中指定的重定向 URI 与应用程序设置中的某个允许 URI 匹配，用户将在认证 (Authentication) 成功后被重定向到该 URI。如果重定向 URI 不在允许列表中，用户将不会被重定向，认证 (Authentication) 过程将失败。

备注:

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

你可以查阅 Redirection endpoint 了解更多信息。

理解 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-initiated logout 了解更多信息。

CORS 允许来源​

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

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

备注:

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

OpenID 提供方配置端点​

OpenID Connect 发现的端点。

授权端点​

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

你可以查阅 Authorization Endpoint 了解更多信息。

令牌端点​

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

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

你可以查阅 Token Endpoint 了解更多信息。

Userinfo 端点​

OpenID Connect UserInfo Endpoint。

总是颁发刷新令牌 (Refresh token)​

适用范围：传统 Web、SPA

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

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

刷新令牌 (Refresh token) 轮换​

默认值：true

启用后，Logto 会在以下情况下为令牌请求颁发新的刷新令牌 (Refresh token)：

  • 如果刷新令牌 (Refresh token) 已轮换（通过颁发新令牌延长其 TTL）一年；或
  • 如果刷新令牌 (Refresh token) 接近过期时间（已过去原始 TTL 的 >=70%）；或
  • 如果客户端是公共客户端，例如原生应用或单页应用 (SPA)。
备注:

对于公共客户端，启用此功能后，每当客户端使用刷新令牌 (Refresh token) 换取新的访问令牌 (Access token) 时，都会颁发新的刷新令牌 (Refresh token)。 虽然你仍然可以为这些公共客户端关闭该功能，但出于安全考虑，强烈建议保持启用状态。

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

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

适用范围：非 SPA；默认值：14 天

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

通常建议设置较低的值。

注意：出于安全原因，SPA（单页应用）不支持 TTL 刷新。这意味着 Logto 不会通过令牌请求延长 TTL。为提升用户体验，你可以启用“刷新令牌 (Refresh token) 轮换”功能，让 Logto 在必要时颁发新的刷新令牌 (Refresh token)。

刷新令牌 (Refresh token) 与会话绑定:

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

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

后端注销 URI​

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

自定义数据​

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