Re: [WG-UMA] UMA Relationship Manager - draft spec text (aka UMA Wallet)

13 Aug 2020

      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