Policy Manager intro use cases & Relationship Manager scope

uma_policy_manager.md

@@ -30,21 +30,66 @@ This extension to UMA enables a resource owner to use a policy management servic
 
 ## 1. Introduction
 
-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 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 which is used by the Policy Manager to define resource owner policy rules.
+
+
+The specification of this API enables many new use cases and benefits to an UMA ecosystem. 
+By allowing The AS to delegate the policy management user experience and advice to another party
+
+- the best place to decide policy may be inline with a resource registration, such as directly at the RS (trusted claims example.) 
+
+- the RS can perform a more 'technical' or authority role to an ecosystem (ie less UX need)
+
+- The RO may manage resources protected by many AS's from a single client application
+  -  ie to have a complete view of their resources and policy
+- The RO may be able to set their preferred policy management client with the AS
+  - useful if AS is fixed to a service/resource ecosystem
+
+
+- In conjunction with the Relationship Manager API (Resource Manager API?), the RO may protect a resource server at many ASs (?)
+
+
+- select use cases
+
+Use Case (trusted claims example)
+
+Alice is using a photo sharing service to store her photo s online. Alice has already directed the service to use her AS to protect access to her photos. By requesting access to the policy API (ie when requesting a PAT...) the RS is able to provide the UX to allow Alice to share her photo with [email protected]. This is possible without Alice to login and use the AS provided management panel.
+
+
+Use Case (Authenticated Email)
+
+Alice's email service supports the AEMS specification, this allows her to upload files to the email service which are then stored and protected by her personal data store and authorization server respectively. Through the email client, Alice is able to attach files in her email to Bob, and create policy for the Bob to download the attached files. When Bob's email service receives the email, it will automatically assert control of Bob's email to Alice's AS, allowing the mail client to download the file. This entire flow takes place without Alice or Bob needing to interact with an authorization server.
+
+
+Use Case (Policy Advice)
+
+Alice is able to use select and use a service independent from her AS (or her many ASs) to manage her access policy. This service may help Alice to create default policies or understand the implications of different policies.
+
+
+Use Case (Domain AS)
+
+Alice has selected two authorization server services which specialize in maintain resource and client ecosystem withing specific domain. The first AS allows her to connect her banks OB API to several financial application The second AS allows her protect her health records from several sources to a single personal health record application. Alice is able to have a single view of all her resources and a single policy management  
+
+... Even if Alice is able to use her AS to protect all of her resources (ie trusted by RSs... and clients... and RqPs). This service does NOT need to be the primary user agent/experience that she interacts with. The policy manager API allows _any_ UI to allow Alice to manage resource access policy
+
+
+
+--- older
 
 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. 
 
 
 
+
+
 ### 1.1 Notational Conventions
 
 ### 1.2 Abstract Flow
@@ -67,11 +112,10 @@ For example, there are two UMA AS's, one being operated by the Alice's local hea
              |              
              |              
              v              
-       +-----------+   
-       |   policy  |   
-       |    API    |   
-       +-----------+   
-       +---------------+--+
+       +------------------+   
+       |   policy         |   
+       |    API           |   
+       +------------------+
        |                  |
        |   authorization  |
        |      server      |
@@ -164,13 +208,18 @@ Figure TDB illustrates the policy API operations, with requests and success resp
 
 
 
+*??* should Alice be able to see policy use/application. ie "this policy was used on Jan 1 using these claims, it resulted in a RPT with these scopes: []"
 
 ### 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
 
 
+There may be many policies registered against the same resource
+
+
+
 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
@@ -191,18 +240,33 @@ For example...
 
 ```
 {
-  resoruce_id: "KX3A-39WE",
+  resource_id: "KX3A-39WE",
   "resource_scopes": [
       "read-public",
       "post-updates",
   ],
-  required_claims: []
+  required_claims: [
+      {  
+         "claim_token_format":[  
+            "http://openid.net/specs/openid-connect-core-1_0.html#IDToken"
+         ],
+         "claim_type":"urn:oid:0.9.2342.19200300.100.1.3",
+         "friendly_name":"email",
+         "issuer":[  
+            "https://example.com/idp"
+         ],
+         "name":"email23423453ou453"
+      }
+
+
+  ]
 }
 ```
 
 
 
 
+
 ### Policy API 
 
 

uma_resource_manager.md

@@ -0,0 +1,69 @@
+UMA 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 the Resource Manager 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
+
+
+
+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)
+
+
+
+
+
+## Available Resources Endpoint
+
+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. 
+
+
+
+### 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
+
+
+
+
+
+
+## Authorization Server Endpoint
+
+
+The API available at the authorization server endpoint enables the resource manager to view and manage the authorization servers available for resource protection. The resource owner may allow resource protection only through the set of available authorization servers. 
+
+***note***: a challenge here is that it's quite difficult for this interface to create a relationship between an AS/RS because how the PAT is issued (ie could be interactive)
+
+
+
+### Authorization Server Description
+
+#### List Authorization Server Description
+