| Version: | 0.1 |
| Document Date: | 2020-07-30 |
| Editors: | Alec Laws |
| Contributors: | |
| Produced by: | |
| Status | |
| Abstract | |
| Suggested Citation |
IPR Option: Non-Assertion Covenant Copyright: The content of this document is copyright of Kantara Initiative, Inc.© 2020 Kantara Initiative, Inc.
This extension to UMA enables a resource owner to use a policy management service to manage the policy conditions, such as required requesting party claims, over their registered resources in order for the authorization server to grant access to a client.
This document extends [UMA Fedz] in order to specify the interface provided by the AS to the RO for policy management. This is achieved by introducing a Policy Management API specification and client type which represents the RO: the UMA Policy Manager.
This new client type is authorized to use the policy API after being authorized by the RO as the AS. THis is the same mechanism used by an RS to put resources under protection, the RS is issued a PAT by the AS.
This new client provides a few key benefits to an UMA ecosystems
- The AS may delegate policy management user expereince and advicce to another party
- The RO is able to choose this client, where they may not be able to choose an AS or RS. The RO receives a consistent policy management interface
- The RO may manage resources at many AS's to have a complete view of their resources and policy
For example, there are two UMA AS's, one being operated by the Alice's local health authority and one operated by Alice's personal Bank. Alice's resource servers are only able to accept authorization decisions from those RS, effectively Alice must use those RSs to protect her resources. When those AS's support this profile, they give back some agency to Alice in how she manages her resources and policy, and reduce their own need to provide this UX (maybe each AS provides on UMA Policy Manager by defaults, but also accept third party policy management services). Alice may then manage policy across all of her RS's and AS's from a single control panel.
+------------------+
| resource |
| owner |
+------------------+
|
|
v
+------------------+
| Policy |
| Manager |
+------+-----------+
|
|
manage (a PAT type authz?)
|
|
v
+-----------+
| policy |
| API |
+-----------+
+---------------+--+
| |
| authorization |
| server |
| |
+------------------+
This specification uses all of the terms and concepts in [UMAGrant] and [UMA Fedz]. This figure introduces the following new concepts:
- UMA Policy Manager
- Policy API The API presented by the AS to the Policy Manager. This API is OAuth protected
TBD
The API available at the registered resources endpoint enables the policy manager to have knowledge of the resources under protection for the resource owner.
A registered resource is a JSON document that extends the resource description from UMA Fedz 3.1 Resource Description with the following parameters:
resource_server REQUIRED A string identifying the resource server that hosts this resourcce
(1 https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-federated-authz-2.0.html#resource-set-desc)
The authorization server must support the following resource management options, and must require a value RMT for access to them. Here, regresuri stands for the registered resource endpoint and _id stands for the authorization server-assigned identifier for the web resource corresponding to the resource at the time it was created, included within the URL returned in the Location header.
- Read resource description: GET regresuri/_id
- List resource descriptions: GET regresuri/
Reads a previously registered resource description using the GET method. If the request is successful, the authorization server MUST respond with an HTTP 200 status message that includes a body containing the referenced resource description, along with an _id parameter.
Form of a read request, with a RMT in the header:
GET /regres/KX3A-39WE HTTP/1.1
Authorization: Bearer 4B7E-937E-FD64DA6F4C92
...
Form of a successful response, containing all the parameters that were registered as part of the description:
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"_id":"KX3A-39WE",
"resource_scopes":[
"read-public",
"post-updates",
"http://www.example.com/scopes/all"
],
"icon_uri":"http://www.example.com/icons/sharesocial.png",
"name":"Tweedl Social Service",
"type":"http://www.example.com/rsrcs/socialstream/140-compatible",
"resource_server": "https://tweedl.com"
}
Identical to the option defined in UMA Fedz 3.2.5 List Resource Descriptions
The API available at the policy endpoint enables the policy manger to register resource owner requirements for claims presentation in order for a requesting party to be granted access to a protected resource.
The policy manager uses a RESTful API at the authorization server's policy endpoint to create, read, update and delete policy descriptions, along with retrieving lists of such descriptions. The descriptions consist of JSON documents that are maintained as web resources at the authorization server.
[INSERT DIAGRAM HERE] Figure TDB illustrates the policy API operations, with requests and success responses shown.
A policy is a JSON document, that describes the a policy sufficiently for the authorization server to make a decision for a resource request. A policy document MAY be provided as a signed JWT to ensure it's integrity to the RS during enforcement. A policy description has the following parameters
resource_id REQUIRED The resource id registered at the AS that this policy applies to
resource_scopes REQUIRED The approved scopes if the claims requirements are met
required_claims REQUIRED An array of claims/attributes that must be presented by the RqP in order to access this resource under this policy. Claims may be presented to the AS through many token formats, or gathered through interactive claims gathering
optional/extension/discussion: sub The subject known by the RS for this RO (useful for general resource definitions) resource_server (again, useful for general resource definitions)
client_id The client application that may be used to access this resource
For example...
{
resoruce_id: "KX3A-39WE",
"resource_scopes": [
"read-public",
"post-updates",
],
required_claims: []
}
The authorization server must support the following policy management options, and must require a value RMT for access to them. Here, poluri stands for the policy endpoint and _id stands for the authorization server-assigned identifier for the web resource corresponding to the policcy at the time it was created, included within the URL returned in the Location header.
- Create policy: POST poluri/
- Read policy: GET poluri/_id
- Update policy: PUT poluri/_id
- Delete policy: DELETE poluri/_id
- List policy: GET poluri/