保护组织（非 API）权限
使用组织模板在 Logto 中管理和强制执行组织级别的角色和权限，控制用户在组织上下文内对应用内功能和工作流的访问。
什么是组织（非 API）权限？
组织权限（非 API）控制用户在组织上下文内可以做什么，但不会在 API 层面强制执行。它们主要用于管理对应用功能、UI 元素、工作流或业务操作的访问，而不是后端 API。
使用场景包括
- 在组织内邀请或管理成员
- 分配或更改组织角色
- 管理组织的账单、设置或管理功能
- 访问没有 API 端点的仪表盘、分析或内部工具
Logto 允许你使用 OAuth 2.1 和基于角色的访问控制 (RBAC) 保护这些组织权限，同时支持多租户 SaaS 架构。
这些权限通过在 组织模板 中定义的组织角色进行管理。每个组织都使用相同的模板，确保所有组织拥有一致的权限模型。
在 Logto 中的工作原理
- 组织级别 RBAC：角色和权限在组织模板中定义。当用户加入组织时，会被分配一个或多个角色，从而获得特定权限。
- 非 API 强制执行：权限在你的应用 UI、工作流或后端逻辑中检查和强制执行，不一定由 API 网关处理。
- 与 API 保护分离：组织（非 API）权限与 API 资源权限是分开的。你可以结合两者用于高级场景。
实现概览
- 在 Logto 的组织模板下定义组织权限。
- 创建组织角色，将所需权限打包用于组织特定操作。
- 在每个组织内为用户或客户端分配角色。
- 通过刷新令牌 (Refresh token) 或客户端凭据流获取当前组织的组织令牌 (JWT)。
- 在应用 UI 或后端验证访问令牌，以强制执行组织权限。
授权 (Authorization) 流程：认证 (Authentication) 并保护组织权限
以下流程展示了客户端（Web、移动端或后端）如何获取并使用组织令牌来强制执行非 API 权限。
请注意，该流程未包含所有必需参数或请求头的详细信息，重点展示关键步骤。继续阅读以了解实际流程。
用户认证 (Authentication) = 浏览器/应用。M2M = 使用客户端凭据 + 组织上下文的后端服务或脚本。
实现步骤
注册组织权限
- 前往 控制台 → 组织模板 → 组织权限。
- 定义你需要的组织权限（如
invite:member、manage:billing、view:analytics）。
完整配置步骤见 定义组织权限。
设置组织角色
- 前往 控制台 → 组织模板 → 组织角色。
- 创建包含你之前定义的组织权限的角色（如
admin、member、billing）。 - 在每个组织内为用户或客户端分配这些角色。
完整配置步骤见 使用组织角色。
获取组织令牌（非 API）
你的客户端/应用应获取组织令牌（非 API）以访问组织权限。Logto 以 JSON Web Token (JWT) 形式签发组织令牌。你可以通过 刷新令牌流程 或 客户端凭据流程 获取。
刷新令牌流程
几乎所有 Logto 官方 SDK 都原生支持通过刷新令牌流程获取组织令牌。标准 OAuth 2.0 / OIDC 客户端库也可实现该流程。
- Logto SDK
- OAuth 2.0 / OIDC 客户端库
初始化 Logto SDK 时，在 scopes 参数中添加 urn:logto:scope:organizations 以及所需的组织权限（scopes）。
部分 Logto SDK 预定义了组织相关 scope，如 JavaScript SDK 中的 UserScope.Organizations。
检查 ID 令牌 (ID token) 中的 organizations 声明 (Claim)，以获取用户所属组织 (Organization) 的 ID 列表。该声明 (Claim) 会列出用户作为成员的所有组织 (Organization)，方便你在应用中枚举或切换组织 (Organization)。
使用 getOrganizationToken 或类似方法（如带组织 ID 的 getAccessToken）为指定组织请求组织令牌。
各 SDK 详情见 快速上手。
配置 OAuth 2.0 客户端或初始化授权码流程时，确保包含以下参数：
resource：设置为urn:logto:resource:organizations，表示你需要组织令牌。scope：包含预定义的组织 scope（urn:logto:scope:organizations）、offline_access（获取刷新令牌），以及你需要的具体组织权限（如invite:member、manage:billing）。
部分库可能不原生支持 resource 参数，但通常允许你在授权请求中传递额外参数。请查阅你的库文档。
以下是授权请求的非规范示例：
GET /oidc/auth?response_type=code
&client_id=your-client-id
&redirect_uri=https://your-app.com/callback
&scope=openid profile offline_access urn:logto:scope:organizations invite:member manage:billing
&resource=urn:logto:resource:organizations
&code_challenge=abc123
&code_challenge_method=S256
&state=xyz
HTTP/1.1
Host: your.logto.endpoint
用户认证 (Authentication) 后，你将收到授权码。使用该授权码向 Logto 的 /oidc/token 端点发起 POST 请求。
以下是令牌请求的非规范示例：
POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)
grant_type=authorization_code
&code=authorization-code-received
&redirect_uri=https://your-app.com/callback
目前，Logto 不支持直接通过授权码流程获取组织令牌 (Organization token)。你需要使用刷新令牌 (Refresh token) 流程来获取组织令牌 (Organization token)。
你将获得一个刷新令牌，可用于获取组织令牌。
检查 ID 令牌 (ID token) 中的 organizations 声明 (Claim)，以获取用户所属组织 (Organization) 的 ID 列表。该声明 (Claim) 会列出用户作为成员的所有组织 (Organization)，方便你在应用中枚举或切换组织 (Organization)。
最后，使用刷新令牌向 Logto 的 /oidc/token 端点发起 POST 请求以获取组织令牌。记得包含：
organization_id参数，设置为目标组织 ID。- （可选）
scope参数，进一步缩小所需权限范围（如manage:members view:reports）。
以下是令牌请求的非规范示例：
POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)
grant_type=refresh_token
&refresh_token=your-refresh-token
&organization_id=your-organization-id
客户端凭据流程
对于机器对机器 (M2M) 场景，你可以使用客户端凭据流程获取组织权限的访问令牌。通过携带组织参数向 Logto 的 /oidc/token 端点发起 POST 请求，使用你的客户端 ID 和密钥请求组织令牌。
请求中需包含的关键参数：
organization_id：你想获取令牌的组织 ID。scope：你想请求的组织权限（如invite:member、manage:billing）。
以下是使用客户端凭据授权类型的令牌请求非规范示例：
POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)
grant_type=client_credentials
&organization_id=your-organization-id
&scope=invite:member manage:billing
验证组织令牌
Logto 签发的组织令牌（JWT）包含你的应用/UI/后端可用于强制执行组织级访问控制的声明 (Claims)。
当你的应用收到组织令牌时，你应：
- 验证令牌签名（使用 Logto 的 JWKs）。
- 确认令牌未过期（
exp声明）。 - 检查
iss（发行者 (Issuer)）是否与你的 Logto 端点匹配。 - 确保
aud（受众 (Audience)）与格式化的组织标识符匹配（如urn:logto:organization:{organization_id}）。 - 拆分
scope声明（以空格分隔），检查所需权限。
分步和特定语言指南见 如何验证访问令牌。
Optional: Handle user permission change
User permissions can change at any time. Because Logto issues JWTs for RBAC, permission updates only appear in newly issued tokens, and never modify existing JWTs.
An access token can only include scopes that were requested in the original OAuth authorization flow. Even if a user gains new permissions, the token issued later can only contain a subset of the originally requested scopes. To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow.
Downscoped permissions
When a user loses permissions:
- Newly issued tokens immediately reflect the reduced scopes.
- Existing JWTs keep the old scopes until they expire.
- Your API should always validate scopes and rely on short token lifetimes.
If you need faster reactions, implement your own signal that tells clients to refresh their tokens.
Enlarged permissions
For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.
Recommendations
- Validate scopes in your API on every call.
- Keep token expiration short.
- Add optional notifications if you need immediate permission-change propagation.
最佳实践与安全提示
- 切勿仅依赖 UI 层强制执行：关键操作务必在后端验证权限。
- 使用受众 (Audience) 限制：始终检查
aud声明，确保令牌属于目标组织。 - 保持权限业务驱动：使用清晰的名称映射实际操作；每个组织角色只授予所需权限。
- 尽量区分 API 与非 API 权限（但两者可在同一角色中）。
- 定期审查组织模板，随产品发展不断优化。
常见问题
我可以在一个角色中混合组织和非组织权限吗？
不可以，组织权限（包括组织级 API 权限）由组织模板定义，不能与全局 API 权限混合。但你可以创建同时包含组织权限和组织级 API 权限的角色。
我应该在哪里强制执行非 API 权限？
在 UI 层（用于功能开关）和服务端逻辑（针对敏感操作）都要检查非 API 权限。
延伸阅读
如何验证访问令牌 自定义令牌声明 (Claims)用例：构建多租户 SaaS 应用