Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

8.4. 保护 API

Protection API 提供了与 UMA 兼容的端点集合：

  • 资源管理

    使用这个端点，资源服务器可以远程管理其资源，并启用 策略强制 程序查询服务器是否有需要保护的资源。

  • 权限管理

    在 UMA 协议中，资源服务器访问此端点以创建权限票据。Red Hat Single Sign-On 还提供端点来管理权限状态和查询权限。

  • Policy API

    Red Hat Single Sign-On 利用 UMA Protection API 允许资源服务器管理其用户的权限。除了 Resource 和 Permission API 外，Red Hat Single Sign-On 还提供了 Policy API，其中权限可以通过代表他们的用户的资源服务器设置为资源。

此 API 的一个重要要求是，仅允许 资源服务器使用名为保护 API 令牌(PAT)的特殊 OAuth2 访问令牌访问其端点。在 UMA 中，PAT 是范围为 uma_protection 的令牌。

8.4.1. 什么是 PAT 以及如何获取它
复制链接

保护 API 令牌 (PAT)是一种特殊的 OAuth2 访问令牌，其范围定义为 uma_protection。当您创建资源服务器时，Red Hat Single Sign-On 会自动创建一个角色 uma_protection （对应的客户端应用程序），并将它与客户端的服务帐户相关联。

通过 uma_protection 角色授予的服务帐户

Service Account granted with uma_protection role

与任何其他 OAuth2 访问令牌一样，资源服务器可以从 Red Hat Single Sign-On 获取 PAT。例如，使用 curl： 

curl -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d 'grant_type=client_credentials&client_id=${client_id}&client_secret=${client_secret}' \
    "http://localhost:8080/auth/realms/${realm_name}/protocol/openid-connect/token"
Copy to Clipboard Toggle word wrap

上面的示例是使用 client_credentials 授权类型从服务器获取 PAT。因此，服务器会返回类似如下的响应： 

{
  "access_token": ${PAT},
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": ${refresh_token},
  "token_type": "bearer",
  "id_token": ${id_token},
  "not-before-policy": 0,
  "session_state": "ccea4a55-9aec-4024-b11c-44f6f168439e"
}
Copy to Clipboard Toggle word wrap
注意

Red Hat Single Sign-On 可以以不同的方式验证您的客户端应用程序。为了简单起见，此处使用了 client_credentials 授权类型，它需要一个 client_id 和 client_secret。您可以选择使用任何支持的身份验证方法。

8.4.2. 管理资源
复制链接

资源服务器可以使用兼容 UMA 的端点远程管理其资源。 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set
Copy to Clipboard Toggle word wrap

此端点提供如下操作（为清晰起见，忽略路径）：

  • 创建资源限制描述：POST /resource_set
  • 读取资源设置描述： GET /resource_set/{_id}
  • 更新资源设置描述： PUT /resource_set/{_id}
  • Delete resource set description: DELETE /resource_set/{_id}
  • 列出资源集合描述： GET /resource_set

有关这些操作的合同的更多信息，请参阅 UMA 资源注册 API。

8.4.2.1. 创建资源
复制链接

要创建资源，您必须发送 HTTP POST 请求，如下所示： 

curl -v -X POST \
  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set \
  -H 'Authorization: Bearer '$pat \
  -H 'Content-Type: application/json' \
  -d '{
     "name":"Tweedl Social Service",
     "type":"http://www.example.com/rsrcs/socialstream/140-compatible",
     "icon_uri":"http://www.example.com/icons/sharesocial.png",
     "resource_scopes":[
         "read-public",
         "post-updates",
         "read-private",
         "http://www.example.com/scopes/all"
      ]
  }'
Copy to Clipboard Toggle word wrap

默认情况下，资源的所有者是资源服务器。如果要定义不同的所有者，如特定用户，您可以按照以下方式发送请求： 

curl -v -X POST \
  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set \
  -H 'Authorization: Bearer '$pat \
  -H 'Content-Type: application/json' \
  -d '{
     "name":"Alice Resource",
     "owner": "alice"
  }'
Copy to Clipboard Toggle word wrap

可以使用用户名或用户标识符来设置属性 所有者。

8.4.2.2. 创建用户管理的资源
复制链接

默认情况下，通过保护 API 创建的资源不能由资源所有者通过 用户帐户 服务进行管理。

要创建资源并允许资源所有者管理这些资源，您必须按照如下所示设置 ownerManagedAccess 属性： 

curl -v -X POST \
  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set \
  -H 'Authorization: Bearer '$pat \
  -H 'Content-Type: application/json' \
  -d '{
     "name":"Alice Resource",
     "owner": "alice",
     "ownerManagedAccess": true
  }'
Copy to Clipboard Toggle word wrap

8.4.2.3. 更新资源
复制链接

要更新现有资源，请按如下所示发送 HTTP PUT 请求： 

curl -v -X PUT \
  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set/{resource_id} \
  -H 'Authorization: Bearer '$pat \
  -H 'Content-Type: application/json' \
  -d '{
     "_id": "Alice Resource",
     "name":"Alice Resource",
     "resource_scopes": [
        "read"
     ]
  }'
Copy to Clipboard Toggle word wrap

8.4.2.4. 删除资源
复制链接

要删除现有资源，请按如下所示发送 HTTP DELETE 请求： 

curl -v -X DELETE \
  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set/{resource_id} \
  -H 'Authorization: Bearer '$pat
Copy to Clipboard Toggle word wrap

8.4.2.5. 查询资源
复制链接

要根据 id 查询资源，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set/{resource_id}
Copy to Clipboard Toggle word wrap

要查询 名称 的资源，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set?name=Alice Resource
Copy to Clipboard Toggle word wrap

默认情况下，名称 过滤器将与给定模式匹配的任何资源。要把查询限制为只返回具有相同匹配项的资源，请使用： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set?name=Alice Resource&exactName=true
Copy to Clipboard Toggle word wrap

要查询一个 uri 的资源，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set?uri=/api/alice
Copy to Clipboard Toggle word wrap

要查询一个 所有者 的资源，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set?owner=alice
Copy to Clipboard Toggle word wrap

要查询某个 类型的资源，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set?type=albums
Copy to Clipboard Toggle word wrap

要查询 范围 的资源，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set?scope=read
Copy to Clipboard Toggle word wrap

查询服务器以获取权限时，使用 前 和 最大 结果的参数来限制结果。

8.4.3. 管理权限请求
复制链接

使用 UMA 协议的资源服务器可以使用特定的端点来管理权限请求。此端点提供了一个与 UMA 兼容的流，用于注册权限请求并获取一个权限票据。 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission
Copy to Clipboard Toggle word wrap

权限票据 是一个代表权限请求的特殊安全令牌类型。根据 UMA 规格，权限 ticket 为：

关联句柄，该处理从授权服务器发布到资源服务器（从资源服务器到客户端），并最终从客户端返回到授权服务器，以启用授权服务器来评估正确的策略以应用到授权数据请求。

在大多数情况下，您不需要直接处理此端点。Red Hat Single Sign-On 提供了一个 策略强制 程序，它为您的资源服务器启用 UMA，以便它从授权服务器获取权限票据，返回此票据到客户端应用程序，并根据最终请求方令牌(RPT)强制授权决策。

从 Red Hat Single Sign-On 获取权限票据的过程由资源服务器而不是常规客户端应用程序执行，当客户端试图访问受保护的资源时，则会获得权限票据，而无需必要授权访问该资源。使用 UMA 时，权限问题单是一个重要事项，因为它允许资源服务器实现：

  • 来自与资源服务器保护的资源相关的数据的客户端摘要
  • 在 Red Hat Single Sign-On 授权请求中注册，稍后可在工作流中使用，以根据资源的所有者同意授予访问权限
  • 将资源服务器与授权服务器分离，并允许使用不同的授权服务器保护和管理其资源

客户端明智之，权限票据也很重要，需要强调：

  • 客户端不需要了解授权数据如何与受保护的资源关联。对客户端而言完全不透明权限票据。
  • 客户端可以访问不同资源服务器上的资源，并由不同的授权服务器进行保护

这些仅仅是 UMA 带来的一些好处，其中 UMA 的其他方面很严重基于权限票据，特别考虑隐私和用户控制对其资源的访问。

8.4.3.1. 创建权限票据
复制链接

要创建权限 ticket，请按如下所示发送 HTTP POST 请求： 

curl -X POST \
  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission \
  -H 'Authorization: Bearer '$pat \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "resource_id": "{resource_id}",
    "resource_scopes": [
      "view"
    ]
  }
]'
Copy to Clipboard Toggle word wrap

在创建问题单时，您还可以推送任意声明，并将这些声明与 ticket 关联： 

curl -X POST \
  http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission \
  -H 'Authorization: Bearer '$pat \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "resource_id": "{resource_id}",
    "resource_scopes": [
      "view"
    ],
    "claims": {
        "organization": ["acme"]
    }
  }
]'
Copy to Clipboard Toggle word wrap

在评估与权限票据关联的资源和范围时，这些声明可用于您的策略。

8.4.3.2. 其他兼容 UMA 的端点
复制链接

8.4.3.2.1. 创建权限票据
复制链接

将带有 id {resource_id} 的特定资源的权限授予具有 id {user_id} 的用户，作为资源发送 HTTP POST 请求的所有者，如下所示： 

curl -X POST \
     http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission/ticket \
     -H 'Authorization: Bearer '$access_token \
     -H 'Content-Type: application/json' \
     -d '{
       "resource": "{resource_id}",
       "requester": "{user_id}",
       "granted": true,
       "scopeName": "view"
     }'
Copy to Clipboard Toggle word wrap
8.4.3.2.2. 获取权限问题单
复制链接
curl http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission/ticket \
     -H 'Authorization: Bearer '$access_token
Copy to Clipboard Toggle word wrap

您可以使用任何这些查询参数：

  • scopeId
  • resourceId
  • owner
  • requester
  • 授权
  • returnNames
  • First
  • max
8.4.3.2.3. 更新权限票据
复制链接
curl -X PUT \
     http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission/ticket \
     -H 'Authorization: Bearer '$access_token \
     -H 'Content-Type: application/json' \
     -d '{
       "id": "{ticket_id}"
       "resource": "{resource_id}",
       "requester": "{user_id}",
       "granted": false,
       "scopeName": "view"
     }'
Copy to Clipboard Toggle word wrap
8.4.3.2.4. 删除权限票据
复制链接
curl -X DELETE http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission/ticket/{ticket_id} \
     -H 'Authorization: Bearer '$access_token
Copy to Clipboard Toggle word wrap

8.4.4. 使用 Policy API 管理资源权限
复制链接

Red Hat Single Sign-On 利用 UMA Protection API 允许资源服务器管理其用户的权限。除了 Resource 和 Permission API 外，Red Hat Single Sign-On 还提供了 Policy API，其中权限可以通过代表他们的用户的资源服务器设置为资源。

Policy API 位于： 

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/uma-policy/{resource_id}
Copy to Clipboard Toggle word wrap

此 API 受一个 bearer 令牌保护，该令牌必须表示用户授权给资源服务器以代表其管理权限。bearer 令牌可以是从令牌端点获取的定期访问令牌：

  • 资源所有者密码凭证授予类型
  • 令牌交换，为使用者是资源服务器的令牌（公共客户端）交换授予某些客户端（公共客户端）的访问令牌

8.4.4.1. 将权限与资源关联
复制链接

要将权限与特定资源关联，您必须发送 HTTP POST 请求，如下所示： 

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"roles": ["people-manager"]
}'
Copy to Clipboard Toggle word wrap

在上面的示例中，我们会创建新权限并将其与 resource_id 表示的资源关联，其中任何具有 role people-manager 的用户都应该被 读取 范围授予。

您还可以使用其他访问控制机制创建策略，比如使用组： 

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"groups": ["/Managers/People Managers"]
}'
Copy to Clipboard Toggle word wrap

或者一个特定的客户端： 

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"clients": ["my-client"]
}'
Copy to Clipboard Toggle word wrap

或者使用 JavaScript 来使用自定义策略：

注意

上传脚本 已弃用，并将在以后的版本中删除。此功能默认为禁用。

使用 -Dkeycloak.profile.feature.upload_scripts=enabled 来启用服务器。如需了解更多详细信息，请参阅 配置文件。 

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"condition": "my-deployed-script.js"
}'
Copy to Clipboard Toggle word wrap

也可以设置这些访问控制机制的任意组合。

要更新现有权限，请按如下所示发送 HTTP PUT 请求： 

curl -X PUT \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{permission_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "21eb3fed-02d7-4b5a-9102-29f3f09b6de2",
    "name": "Any people manager",
    "description": "Allow access to any people manager",
    "type": "uma",
    "scopes": [
        "album:view"
    ],
    "logic": "POSITIVE",
    "decisionStrategy": "UNANIMOUS",
    "owner": "7e22131a-aa57-4f5f-b1db-6e82babcd322",
    "roles": [
        "user"
    ]
}'
Copy to Clipboard Toggle word wrap

8.4.4.2. 删除权限
复制链接

要删除与资源关联的权限，请按如下所示发送 HTTP DELETE 请求： 

curl -X DELETE \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{permission_id} \
  -H 'Authorization: Bearer '$access_token
Copy to Clipboard Toggle word wrap

8.4.4.3. 查询权限
复制链接

要查询与资源关联的权限，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm}/authz/protection/uma-policy?resource={resource_id}
Copy to Clipboard Toggle word wrap

要查询给定其名称的权限，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm}/authz/protection/uma-policy?name=Any people manager
Copy to Clipboard Toggle word wrap

要查询与特定范围关联的权限，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm}/authz/protection/uma-policy?scope=read
Copy to Clipboard Toggle word wrap

要查询所有权限，请按如下所示发送 HTTP GET 请求： 

http://${host}:${port}/auth/realms/${realm}/authz/protection/uma-policy
Copy to Clipboard Toggle word wrap

查询服务器以获取权限时，使用 前 和 最大 结果的参数来限制结果。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat