UMA Relationship Manager - draft spec text (aka UMA Wallet)
Please find some updated spec text below. Changes are mainly to: intro, policy api, AS metadata, add (empty) introspection section, add spec-is wrapper/formatting Perhaps should be pushed to the UMA GitHub (as Eve has been hinting at!) Cheers, - Alec Alec Laws 647 822 1529 alec@identos.ca # UMA Relationship Manager (aka Wallet) | | | |:---|:---| |Version:|0.1| |Document Date:|2020-07-30| |Editors:|Alec Laws| |Contributors:|| |Produced by:| |Status| | |Abstract| | |Suggested Citation| | #### Notice IPR Option: Non-Assertion Covenant Copyright: The content of this document is copyright of Kantara Initiative, Inc.© 2020 Kantara Initiative, Inc. ## 1. Introduction This document extends [UMA Fedz] in order to specify the management and control interfaces through an UMA Relationship Manager Client. This new client type defines how an Resource Owner may connect to Resource Servers, put those resources under protection and finally create and manage policy at an AS over those registered resources. This role is a Client application that may be accessible to the end-user through various user-agents (eg Browser, native app) This new client type provides the end-user a consistent consent management interface that may be used across multiple ASs, where the RO is able to choose an independent policy management service, or tightly coupled to a single AS. In some profiles, this extensions enables the AS to operate with a minimum of collected personal data. The UMA Wallet operates in two distinct modes, for the RO and the RqP. The UMA Wallet performs three major flows with other systems: 1. RO puts resources under protection 2. RO creates policy 3. RqP performs claims gathering, ### 1.1 Notational Conventions ### 1.2 Abstract Flow ``` +------------------+ +------------------+ | resource | | requesting | +---------- | owner | | party | | +------------------+ +------------ -----+ | | delegation | | +------------------+ | | | | +-----manage ---------- Wallet | | | +------+-----------+ | | | +-----------+ | | | | claims | | | | | gathering | | | | | API(OIDC)| | | protect +-----------+ | | | ^ | | | | | | | | | v v | | +-----------+ protection +-----------+ | | | manange | API access | policy | | | | API | token (PAT) | API | | + +-----------+ +-----------+ | +------------+ +----------+---------------+--+ | | |protection| | | resource | | API | authorization | | server |<-----prot---| (needs | server | | | | PAT) | | +------------+ +----------+------------------+ ``` This specification uses all of the terms and concepts in [UMAGrant] and [UMA Fedz]. This figure introduces the following new concepts: - UMA Wallet - Policy API The API presented by the AS to the Wallet. This API is OAuth(UMA?) protected - Manage API The API presented by the RS to the Wallet. This API is OAuth(OIDC?) protected ### 1.3 HTTP Usage, API Security, and Identity Context ## 2 Authorization Server Metadata This specification makes use of the authorization server discovery document structure and endpoint defined in [UMAGrant]. The relationship manager uses this discovery document to discover the endpoints it needs. In addition to the metadata defined in that specification and [UMA Fedz], this specification defines the following metadata for inclusion in the discovery document: policy_endpoint REQUIRED The endpoint URI at which the relationship manager modifies policy on the user's behalf The Authorization Server should indicates it's support of this profile by including the URI to the specification in the uma_profiles_supported metadata array ## 3 Manage Endpoint The management API allows the wallet to manage resources on behalf of the authenticated resource owner. The manage API allows the RO to register credentials (public keys... or otherwise) the RS will trust policy signed by. The policy is delivered by the AS to to RS in the RPT or through introspection. The manage API may be extended to allows the wallet - to read available resources, - direct the RS to register resources at a specific AS, and see ASs/registered resources - dynamic registration of an RO specific client ### 3.1 Create Credential Example ``` POST /credential Authorization: Bearer something { oauth dyn client reg with a embedded jwk } { a DIDDocument... } ``` ## 4 Policy API note: this API is very similar to the permission endpoint, expect the payload includes an RS sub, additional policy condition, and is signed by a RO-RS credential The API available at the policy_endpoint enables the relationship manager the modify policy over the RO's protected resources. These policies define the claims gathering requirements for an RqP to gain access to the resource, and should also indicate the intended purpose/use for resource access. Management of the policy beings on successful creation and ends on successful revocation. The relationship manager uses a RESTful API at the authorization server's policy endpoint tto create, read, update, and delete policy descriptions, along with retrieving lists of such descriptions. note: I think it's also useful to allow the RO to read a list of registered resources, I don't think woudl live under the policy_endpoint, it's essentially like the GET API from the resource_registration_endpoint with additional infomration about the RS? note: through the ` "user_access_policy_uri":"http://as.example.com/rs/222/resource/KX3A-39WE/policy"` the RS could also let the relationship manager know (though manage API) what path to use at the AS to modify policy for this resource?? This restricts Figure TDB illustrates the policy API operations, with requests and success responses shown. ``` FIGURE TDB ``` ### 4.1 Policy Description 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 claims REQUIRED An array of claims/attributes that must be presented by the RqP in order to access this resource under this policy 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 intent The purpose/intention of resource use the RqP must accept For example... ``` { resoruce_id: "KX3A-39WE", "resource_scopes": [ "read-public", "post-updates", ], claims: [ ??? ] } ``` --- updated to this point ### 4.1 Policy Description The policy is a JWT signed by a RO credential known to the RS that owns the resource_id Example Payload ``` { "sub": "a RO chosen sub to identify to the RS" "resource_scopes":[ "view", ], "resource_id": "resource_id", ...extension/optional "client_id": "resource_server": "req'd for res def profile" "other_conditions" "" } ``` ## 5 Claims Gathering (OIDC) THe claims gathering API allows the AS to delegate RqP authenticate and claim collection to the Wallet. The wallet allows the RqP to respond to a registered RO policy for the requested resource. ## 5 Introspection In some cases, policy should be conveyed through the AS back the RS for independent verification ## Security Considerations ## Privacy Considerations ## Acknowledgments ## References --- ## Authors' Addresses
Hi, not a ton of updates, just want to get the most recent version out before the call today - Alec Alec Laws 647 822 1529 alec@identos.ca Changes: 30 Jul 2020, intro, policy api, AS metadata, introspection in scope?, add spec formatting 13 Aug 2020, wallet -> relationship manager, typos, intro # UMA Relationship Manager (aka Wallet) | | | |:---|:---| |Version:|0.1| |Document Date:|2020-07-30| |Editors:|Alec Laws| |Contributors:|| |Produced by:| |Status| | |Abstract| | |Suggested Citation| | #### Notice IPR Option: Non-Assertion Covenant Copyright: The content of this document is copyright of Kantara Initiative, Inc.© 2020 Kantara Initiative, Inc. ## 1. Introduction This document extends [UMA Fedz] in order to specify the management and control interfaces through an UMA Relationship Manager Client. This new client type defines how an Resource Owner may connect to Resource Servers, put those resources under protection and finally create and manage policy at an AS over those registered resources. This role is a Client application that may be accessible to the end-user through various user-agents (eg Browser, native app) The purpose of the relationship manager is - to allow the AS and RS to delegate policy management UX to another system - to allow the RO to participate with many ASs and RSs through a single service - to allow the RqP to present claims and meet RO policy without necessarily disclosing those claims to the AS For example, Alice can choose a relationship manager service and connect to her (many) resource servers. Through the manage API, she can direct a resource server to protect specific resources at specific authorization servers. She can then set policy at those authorization servers indicating the claims required to be presented by requesting party during claims gathering. This new client type provides the end-user a consistent consent management interface that may be used across multiple ASs, where the RO is able to choose an independent policy management service, or tightly coupled to a single AS. In some profiles, this extensions enables the AS to operate with a minimum of collected personal data. The UMA Relationship Manager operates in two distinct modes, for the RO and the RqP, and performs three major flows with other components: 1. RO puts resources under protection 2. RO creates policy 3. RqP performs claims gathering, ### 1.1 Notational Conventions ### 1.2 Abstract Flow ``` +------------------+ +------------------+ | resource | | requesting | +---------- | owner | | party | | +------------------+ +------------ -----+ | | delegation | | +------------------+ | | Relationship | | +-----manage ---------- Manager | | | +------+-----------+ | | | +-----------+ | | | | claims | | | | | gathering | | | | | API(OIDC)| | | protect +-----------+ | | | ^ | | | | | | | | | v v | | +-----------+ protection +-----------+ | | | manange | API access | policy | | | | API | token (PAT) | API | | + +-----------+ +-----------+ | +------------+ +----------+---------------+--+ | | |protection| | | resource | | API | authorization | | server |<---protect--| (needs | server | | | | PAT) | | +------------+ +----------+------------------+ ``` This specification uses all of the terms and concepts in [UMAGrant] and [UMA Fedz]. This figure introduces the following new concepts: - UMA Relationship Manager - Policy API The API presented by the AS to the Relationship Manager. This API is OAuth protected - Manage API The API presented by the RS to the Relationship Manager. This API is OAuth protected ### 1.3 HTTP Usage, API Security, and Identity Context ## 2 Authorization Server Metadata This specification makes use of the authorization server discovery document structure and endpoint defined in [UMAGrant]. The relationship manager uses this discovery document to discover the endpoints it needs. In addition to the metadata defined in that specification and [UMA Fedz], this specification defines the following metadata for inclusion in the discovery document: policy_endpoint REQUIRED The endpoint URI at which the relationship manager modifies policy on the user's behalf The Authorization Server should indicates it's support of this profile by including the URI to the specification in the uma_profiles_supported metadata array ## 3 Manage Endpoint The management API allows the relationship manager to manage resources on behalf of the authenticated resource owner at the resource server. The manage API allows the RO to register credentials (public keys... or otherwise) the RS will trust policy signed by. The policy is delivered by the AS to to RS directed embedded in the RPT or through the introspection endpoint. The manage API may be extended to allows the relationship manager - to read available resources, - direct the RS to register resources at a specific AS, and see ASs/registered resources - dynamic registration of an RO specific client !!!: one challenge here is how the RS can get a PAT when directed to trust an AS. This wasn't a problem for the identos impl through the resource definitions (RS is the RO/generic resources). This would require a redirection to RS? ### 3.1 Create Credential Example ``` POST /credential Authorization: Bearer something { oauth dyn client reg with a embedded jwk } { a DIDDocument... } ``` ## 4 Policy API note: this API is very similar to the permission endpoint, expect the payload includes an RS sub, additional policy condition, and is signed by a RO-RS credential The API available at the policy_endpoint enables the relationship manager the modify policy over the RO's protected resources. These policies define the claims gathering requirements for an RqP to gain access to the resource, and should also indicate the intended purpose/use for resource access. Management of the policy beings on successful creation and ends on successful revocation. The relationship 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. note: I think it's also useful to allow the RO to read a list of registered resources, I don't think would live under the policy_endpoint, it's essentially like the GET API from the resource_registration_endpoint with additional information about the RS? note: through the ` "user_access_policy_uri":"http://as.example.com/rs/222/resource/KX3A-39WE/policy"` the RS could also let the relationship manager know (though manage API) what path to use at the AS to modify policy for this resource?? This restricts Figure TDB illustrates the policy API operations, with requests and success responses shown. ``` FIGURE TDB ``` ### 4.1 Policy Description 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 claims REQUIRED An array of claims/attributes that must be presented by the RqP in order to access this resource under this policy 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 intent The purpose/intention of resource use the RqP must accept For example... ``` { resoruce_id: "KX3A-39WE", "resource_scopes": [ "read-public", "post-updates", ], claims: [ ??? ] } ``` --- updated to this point ### 4.1 Policy Description The policy is a JWT signed by a RO credential known to the RS that owns the resource_id Example Payload ``` { "sub": "a RO chosen sub to identify to the RS" "resource_scopes":[ "view", ], "resource_id": "resource_id", ...extension/optional "client_id": "resource_server": "req'd for res def profile" "other_conditions" "" } ``` ## 5 Claims Gathering (OIDC) THe claims gathering API allows the AS to delegate RqP authenticate and claim collection to the relationship manager. The relationship manager allows the RqP to respond to a registered RO policy for the requested resource. ## 5 Introspection In some cases, policy will be conveyed through the back to the RS for independent verification ## Security Considerations ## Privacy Considerations ## Acknowledgments ## References --- ## Authors' Addresses
On Jul 30, 2020, at 12:29 PM, Alec L <alec@identos.ca> wrote:
Please find some updated spec text below. Changes are mainly to: intro, policy api, AS metadata, add (empty) introspection section, add spec-is wrapper/formatting
Perhaps should be pushed to the UMA GitHub (as Eve has been hinting at!)
Cheers, - Alec
Alec Laws 647 822 1529 alec@identos.ca <mailto:alec@identos.ca>
# UMA Relationship Manager (aka Wallet)
| | | |:---|:---| |Version:|0.1| |Document Date:|2020-07-30| |Editors:|Alec Laws| |Contributors:|| |Produced by:| |Status| | |Abstract| | |Suggested Citation| |
#### Notice IPR Option: Non-Assertion Covenant Copyright: The content of this document is copyright of Kantara Initiative, Inc.© 2020 Kantara Initiative, Inc.
## 1. Introduction
This document extends [UMA Fedz] in order to specify the management and control interfaces through an UMA Relationship Manager Client.
This new client type defines how an Resource Owner may connect to Resource Servers, put those resources under protection and finally create and manage policy at an AS over those registered resources. This role is a Client application that may be accessible to the end-user through various user-agents (eg Browser, native app)
This new client type provides the end-user a consistent consent management interface that may be used across multiple ASs, where the RO is able to choose an independent policy management service, or tightly coupled to a single AS.
In some profiles, this extensions enables the AS to operate with a minimum of collected personal data.
The UMA Wallet operates in two distinct modes, for the RO and the RqP.
The UMA Wallet performs three major flows with other systems: 1. RO puts resources under protection 2. RO creates policy 3. RqP performs claims gathering,
### 1.1 Notational Conventions
### 1.2 Abstract Flow
``` +------------------+ +------------------+ | resource | | requesting | +---------- | owner | | party | | +------------------+ +------------ -----+ | | delegation | | +------------------+ | | | | +-----manage ---------- Wallet | | | +------+-----------+ | | | +-----------+ | | | | claims | | | | | gathering | | | | | API(OIDC)| | | protect +-----------+ | | | ^ | | | | | | | | | v v | | +-----------+ protection +-----------+ | | | manange | API access | policy | | | | API | token (PAT) | API | | + +-----------+ +-----------+ | +------------+ +----------+---------------+--+ | | |protection| | | resource | | API | authorization | | server |<-----prot---| (needs | server | | | | PAT) | | +------------+ +----------+------------------+ ```
This specification uses all of the terms and concepts in [UMAGrant] and [UMA Fedz]. This figure introduces the following new concepts:
- UMA Wallet - Policy API The API presented by the AS to the Wallet. This API is OAuth(UMA?) protected - Manage API The API presented by the RS to the Wallet. This API is OAuth(OIDC?) protected
### 1.3 HTTP Usage, API Security, and Identity Context
## 2 Authorization Server Metadata
This specification makes use of the authorization server discovery document structure and endpoint defined in [UMAGrant]. The relationship manager uses this discovery document to discover the endpoints it needs.
In addition to the metadata defined in that specification and [UMA Fedz], this specification defines the following metadata for inclusion in the discovery document:
policy_endpoint REQUIRED The endpoint URI at which the relationship manager modifies policy on the user's behalf
The Authorization Server should indicates it's support of this profile by including the URI to the specification in the uma_profiles_supported metadata array
## 3 Manage Endpoint
The management API allows the wallet to manage resources on behalf of the authenticated resource owner.
The manage API allows the RO to register credentials (public keys... or otherwise) the RS will trust policy signed by. The policy is delivered by the AS to to RS in the RPT or through introspection.
The manage API may be extended to allows the wallet - to read available resources, - direct the RS to register resources at a specific AS, and see ASs/registered resources - dynamic registration of an RO specific client
### 3.1 Create Credential
Example
``` POST /credential Authorization: Bearer something
{ oauth dyn client reg with a embedded jwk } { a DIDDocument... } ```
## 4 Policy API
note: this API is very similar to the permission endpoint, expect the payload includes an RS sub, additional policy condition, and is signed by a RO-RS credential
The API available at the policy_endpoint enables the relationship manager the modify policy over the RO's protected resources. These policies define the claims gathering requirements for an RqP to gain access to the resource, and should also indicate the intended purpose/use for resource access. Management of the policy beings on successful creation and ends on successful revocation.
The relationship manager uses a RESTful API at the authorization server's policy endpoint tto create, read, update, and delete policy descriptions, along with retrieving lists of such descriptions.
note: I think it's also useful to allow the RO to read a list of registered resources, I don't think woudl live under the policy_endpoint, it's essentially like the GET API from the resource_registration_endpoint with additional infomration about the RS?
note: through the ` "user_access_policy_uri":"http://as.example.com/rs/222/resource/KX3A-39WE/policy <http://as.example.com/rs/222/resource/KX3A-39WE/policy>"` the RS could also let the relationship manager know (though manage API) what path to use at the AS to modify policy for this resource?? This restricts
Figure TDB illustrates the policy API operations, with requests and success responses shown. ``` FIGURE TDB ```
### 4.1 Policy Description
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
claims REQUIRED An array of claims/attributes that must be presented by the RqP in order to access this resource under this policy
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
intent The purpose/intention of resource use the RqP must accept
For example...
``` { resoruce_id: "KX3A-39WE", "resource_scopes": [ "read-public", "post-updates", ], claims: [ ??? ] } ```
--- updated to this point
### 4.1 Policy Description
The policy is a JWT signed by a RO credential known to the RS that owns the resource_id
Example Payload ``` { "sub": "a RO chosen sub to identify to the RS" "resource_scopes":[ "view", ], "resource_id": "resource_id",
...extension/optional "client_id": "resource_server": "req'd for res def profile" "other_conditions" "" } ```
## 5 Claims Gathering (OIDC)
THe claims gathering API allows the AS to delegate RqP authenticate and claim collection to the Wallet. The wallet allows the RqP to respond to a registered RO policy for the requested resource.
## 5 Introspection
In some cases, policy should be conveyed through the AS back the RS for independent verification
## Security Considerations
## Privacy Considerations
## Acknowledgments
## References
---
## Authors' Addresses
participants (1)
-
Alec L