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

8.4. 保护 API

Protection API 提供了一组与 UMA 兼容的端点，提供：

  • 资源管理

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

  • 权限管理

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

  • Policy API

    Red Hat build of Keycloak 利用 UMA Protection API 来允许资源服务器为其用户管理权限。除了 Resource 和 Permission API 外，红帽构建的 Keycloak 还提供了一个 Policy API，其中可通过资源服务器代表其用户将权限设置为资源。

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

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

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

使用 uma_protection 角色授予的服务帐户

Service Account granted with uma_protection role

资源服务器可以从红帽构建的 Keycloak 获取 PAT，就像任何其他 OAuth2 访问令牌一样。例如，使用 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://${host}:${port}/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
注意

红帽构建的 Keycloak 可以不同的方式验证您的客户端应用程序。为了简单起见，这里使用 client_credentials 授权类型，这需要 client_id 和 client_secret。您可以选择使用任何支持的身份验证方法。

8.4.2. 管理资源
复制链接

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

http://${host}:${port}/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/{_id}
  • 列出资源设置描述：GET /resource_set

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

8.4.2.1. 创建资源
复制链接

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

curl -v -X POST \
  http://${host}:${port}/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}/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}/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}/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}/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}/realms/${realm-name}/authz/protection/resource_set/{resource_id}
Copy to Clipboard Toggle word wrap

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

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

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

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

要查询给定的 uri 资源，请发送 HTTP GET 请求，如下所示： 

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

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

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

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

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

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

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

当查询服务器以获取权限时，首先使用 参数，最大 结果来限制结果。

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

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

http://${host}:${port}/realms/${realm-name}/authz/protection/permission
Copy to Clipboard Toggle word wrap

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

关联处理从授权服务器到资源服务器，从资源服务器到客户端，最终从客户端重新发送到授权服务器，以便授权服务器评估正确的策略以应用到授权数据的请求。

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

从红帽构建的 Keycloak 获取权限票据的过程由资源服务器执行，而不是常规客户端应用程序，当客户端试图访问受保护的资源时获得权限票据，而无需必要授予访问该资源。使用 UMA 时，权限票据的颁发是允许资源服务器进行的重要方面：

  • 从与资源服务器保护的资源关联的数据摘要
  • 在 Red Hat build of Keycloak 授权请求中注册，稍后可以在工作流中使用它们来根据资源的所有者同意授予访问权限
  • 将资源服务器与授权服务器分离，并允许它们使用不同的授权服务器保护和管理其资源

客户而言，权限票据也很重要的方面，需要强调：

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

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

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

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

curl -X POST \
  http://${host}:${port}/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}/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}/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}/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}/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}/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 build of Keycloak 利用 UMA Protection API 来允许资源服务器为其用户管理权限。除了 Resource 和 Permission API 外，红帽构建的 Keycloak 还提供了一个 Policy API，其中可通过资源服务器代表其用户将权限设置为资源。

Policy API 位于： 

http://${host}:${port}/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/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 代表的资源，其中任何拥有角色 people-manager 的用户都应 授予读取 范围。

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

curl -X POST \
  http://localhost:8180/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/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 的自定义策略： 

curl -X POST \
  http://localhost:8180/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/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/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}/realms/${realm-name}/authz/protection/uma-policy?resource={resource_id}
Copy to Clipboard Toggle word wrap

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

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

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

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

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

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

当查询服务器以获取权限时，首先使用 参数，最大 结果来限制结果。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat