# UMA Relationship / Resource Server Management
 
This document extends [UMA Fedz] in order to specify the interface provided by the RS to the RO for resource management. This is achieved by introducing a Resource Management API which is used by a Resource Manager Client to view available resources and direct the AS to use for protection.
 
 
** This API could also allows the RO to
- view access history
- set direct policy (ie Adrian clause)
- establish credentials required in AS, (smarthealth.card)
 
 
Reqs:
 
- The RO must authenticate to the RS, in order to authorize access to this API
    - (this capability of the RS is implied by UMA)
 
- The RO can see a list of resources available at this RS (either protected or not)
- The RO can modify the protection of resources (ie which AS to protect)
 
- The RO can see AS's available for protection
    - can the RO direct the RS to get a PAT from a new AS? This is tricky depending on how PAT's are issued (ie may require end-user redirection)
 
 
 
Possible API Names:
- resource management
- resource declaration
- available resources
- resource access management (RAM)
 
 
 
This document introduces the following new concepts:
- Resource Management API   The API presented by the RS to the Resource Manager. This API is OAuth protected
- Resource Management Token (RMT) (what scope should this Access Token capture?) "uma_management"

- Resource Owner credentials    The credentials registered by the resource owner within the resource server
- Resource Owner Token (or Policies "the VC/VP")      A token signed using the resource owner credentials. Allows the resource server to independently verify the the resource owner's intention
 

- Policy Management API     The API presented by the AS to the Resource Manager. This API is OAuth protected
- Policy Management Token (PMT) (what scope should this Access Token capture?) "uma_policy"


- would also be great if during UMA Grant, the AS could send the RqP to their Relationship Manager in order for new policy to be created 'just in time' (ciba-ish...)
    - this has been the 'cascading AS' discussion is past. RM provides a OIDC interface to facilitate the redirect (could be SIOP now?)


 
### 1.3 HTTP Usage, API Security, and Identity Context
- add link between RM API and RM Token
 
informative
The use of the `uma_management` scope when requesting a RMT may indicate to the RS's authorization server that establishment of one or more PATs with an available UMA AS is 'useful'
 
 
 
 
#### The `Resource Management API` allows the Resource Owner to:
- View the available resources hosted at this RS, and their current protection
- Register a Resource Owner Credential
    - (eg dyn client registration, posting a DID)
- (for discussion) have verifiable credentials issued by the RS to the RO
    - not strictly necessary since the ROT can be created by the resource owner 
	- This is a good outcome, since the burden on the RP is moved to the RO. The RO can present/delegate these VC's further
	- Should this draft specify the framework or the specific tech (oauth client vs w3c) and further profiling of the technical (similar to the uma grant claims types)

- ~View the UMA Authorization Servers available to be used to protect~
- ~Manage the UMA protection of available resources~
 

 
Starting Conditions RMA:
- The RS hosts resources for the RO
- The RS supports resource protection from an UMA AS
- The RS has a UMA PAT at one or more UMA ASs 
    - **for discussion**A RS that support this profile does not need resource owner specific PATs. If the ROT is embedded in the RPT, no PAT or introspection is even required. One RS level PAT to allow introspection, and opaque RPTs to be issued
	- are situations where the RS doens't even know/trust the AS too far? No?
	- the RS implicitly trusts the AS since it includes the authority of the RO, outcome is RO can use any ASs, moves challenges for having an AS per RO


 
Step 0
The Resource Manager obtains an OAuth Access Token valid for use at the Resource API. The Access Token must allow the RS to determine the RO's resources.
- is there a purpose for NOT the RO to use this interface? Is this 'delegation' too early in

- *trying to stay away from defining the identity system. 
- not necessary to identify the person, instead the RS needs to know the rights over the resources
 
Step 1 (Get Info)
The RM obtains a list of available resources
 
Step 2 (Manage Credential)
The RM registers credentials with the RO
- Viewing and modifying registered credentials
- Registering a new credential

Step 3 (Optional?)
The RM requests resources to be issued as Verifiable Credentials against one of the registered resource owner credentials
- this would use something akin to https://mattrglobal.github.io/oidc-client-bound-assertions-spec/

RM->RS: POST /give-me-a-crednetial-for { my_credential(step2), the resource(step1) } -> issued VC
 


Ending Conditions RMA:
- The RM has a list of available resources for the RO at this RS
	- maybe, the RM has w3c VC's representing the resources
- The RS has attached the ROC(s) to the user account (public part / shared secret )
- The RM has the RO credentials (private part / shared secret )






 
#### The `Policy Management API ` allows the Resource Owner(or resource rights administrator??) to:
- (is this the general resource rights administrator?) doesn't need to be the same as the RO if there has been some RO->RRA delegation in the background
- view existing policies for them 
- create new policies for resources (registered or not?)


Starting Conditions PMA:
- the RMA start and end conditions
- The AS supports the policy management for the 
	- AS doesn't' need previous relationship with the RS. 


Step 0
The Resource Manager obtains an OAuth Access Token valid for use at the Policy API. The Access Token must allow the AS to determine the User(RO/RqP)'s policy.

 
Step 1 (Get Info)
The RM obtains a list of their existing policies and the AS supported policy claims(metadata)
	- suggest this is based on scopes, uma resource descriptions, claim token formats. find the smallest possible set to increase interop
	- can be an extension point, however customization here starts to reduce the ecosystem/interop circle size

 
Step 2 (Create Policy)
The RM uses a ROC + resource description + support policy to create the resource owner token. The ROT is registered at the AS


#### 
 


## The Resource Owner Token ( Verifiable Credential or Presentation )

resource owner credential has two part: a identifier and the actual credential (oauth client id and oauth client secret) (did + private key)
- multiple subject ids could be used against a single registered pub key @ RS

```
ROT = a JWT signed by the ROC {
	// required jwt type things, exp, iat

    id: rm create policy id?
    resource_owner_id : identifier portion of the ROC (should this just be sub)

	resources: [
    	resource_server:
    	resource_location: ??    are both required?

    	resource_id: (similar to how the path identifies the RO to the RS)
    	allowed_scope: [ out of the available scopes ]
	]

    allowed_rqp: client_id, other claims { email: bob@email.com } // this is the claim token format question?
}
```
 
 
## Available Resources Endpoint (RS)
 
The API available at the available resources endpoint enables the resource manager to have knowledge of the resources hosted by the resource server for the resource owner.
 
 
\_rs_id is a resource server defined identifier for a resource.
Before a resource is registered at an AS, there is no handle/reference available (unless the RS provides one)
 
 
 
GET /my-resources/
```
[
{
    "_resource_id" "ABC",
 
    "resource_scopes":[ 
      "view",
      "http://photoz.example.com/dev/scopes/print"
   ],
   "description":"Collection of digital photographs",
   "icon_uri":"http://www.example.com/icons/flower.png",
   "name":"Photo Album",
   "type":"http://www.example.com/rsrcs/photoalbum",
 
   // uri/location of the resource?
	"resource_location" : uri <- discovery/sharing to RqP
 

},
 
]
```
 
 
 
Protected Resources
```
[
{
    "_resource_id" "ABC",
    "authorization_sever_resource_id" : "_as_id"   
 
    "authorization_server" : "as_identifier",
    "registered_scopes" : [ "view" ]
},
{
    "_resource_id" "ABC",
    "authorization_sever_resource_id" : "_as_id_2" 
    "authorization_server" : "as_identifier_2",
    "registered_scopes" : [ "view", "http://photoz.example.com/dev/scopes/print" ]
}
]
 
```
 
 
In dashboard world, rs_id = PeI (pension identifier)
- to confirm, is the PeI the same as the as_id? ie is it created by the RS or the AS
 
RS_1 holds pension A with identifier a
RS_1 registers pension A
 
 
single person, single resource, single rs: can have multiple resource registration, eg with different scopes
 
Resource = Patient
Registered Resource 1: Just the Patient Object
Registered Resource 2: The Patient + Sub Objects
 
 
 
### Available Resource Description
 
A registered resource is a JSON document that extends the resource description from [UMA Fedz 3.1 Resource Description](1) with the following parameters:
 
authorization_server OPTIONAL A string identifying the authorization server that protects this resource
** could also be the AS policy uri from resource registration?
 
(1 https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-federated-authz-2.0.html#resource-set-desc)
 
#### List Available Resource Descriptions
 
 
 
#### Update Available Resources Description
 
 
 


## Resource Owner Credentials Endpoint (RS)

This API available at the Resource Owner Credentials Endpoint enables the resource manager to view and manage credentials registered for the resource owner. 




GET /my-credentials
```
[
{ 
    _id: cred_id,
    cred_type: did | client
    cred_value: {
        <a did >
        ...or
        <oauth_client metadata>
    }
}
]
 
```



## Resource Owner Policy Endpoint

This API available at the Resource Owner Policy Endpoint enables the resource manager to view and manager policy registered for the authorized user 



## [UMA Fedz] 5. Token Introspection Endpoint 

- needs modification to include the ROT, either to replace a permission, or an an 'authority' within a specific permission (to be bw compatible)


```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
...

{  
   "active":true,
   "exp":1256953732,
   "iat":1256912345,
   "permissions":[  
      {  
         "resource_id":"112210f47de98100",
         "resource_scopes":[  
            "view",
            "http://photoz.example.com/dev/actions/print"
         ],
         "exp":1256953732,

         "authority": ROT.JWT.VALUE
      }
   ]
}
```

## [UMA Grant] 3.3.4 Authorization Assessment and Results Determination

- describe set math changes