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