Project: RTOI - ForgeRock/frdp-uma-resource-server GitHub Wiki

Why

A typical User Managed Access (UMA 2.0) scenario involves the sharing of a resource. The Resource Owner (RO) decides who can access the resource and what operations are allowed. The Resource Owner (RO) will typically use an application to manage their resources. After the Resource Owner (RO) creates, registers and shares a resource ... "information" about the resource needs to be transferred to the Requesting Party (RqP). The Requesting Party (RqP) uses the "information" to access the resource via a different Client Application (CA). The transfer of "information" needs to be secure and support data privacy for both the Resource Owner (RO) and Requesting Party (RqP).

The UMA 2.0 specification does not cover how resource "information" is communicated between the Resource Owner (RO) and the Requesting Party (RqP).

How

This design will define what mechanisms, protocols and formats shall be used within the UMA Reference Implementation (UMA-RI) project to transfer resource "information".

When the Resource Owner (RO) has decided to share a resource, the following will be known:

  • What resource is being shared
  • Who is allowed to access the resource
  • What operations are allowed

The Resource Owner (RO) may not know:

  • The external / public identifier for the resource
  • What application(s) the Requesting Party (RqP) will use (to access the resource)

Scenarios

The following scenarios describe how the resource information can be communicated from the Resource Owner (RO) to the Requesting Party (RqP).

Raw data

The Resource Owner Application (ROA) provides "raw data" in JSON format to the Resource Owner (RO).  The Resource Owner (RO) extracts the "raw data" and delivers it to the Requesting Party (RqP) ... email, text message, chat, etc.  The Requesting Party (RqP) provides the "raw data" to the Client Application (CA) to access the resource.

Client Application URL

The Resource Owner Application (ROA) generates a "sharable link" URL.  The URL references the Client Application (CA) that the Requesting Party (RqP) would use.  The URL contains the resource information as a query parameter.  The Requesting Party (RqP) would open the URL in a browser to access the Client Application (CA) and access the shared resource.

Resolver Service

Ideally, the Resource Owner Application (ROA) should know which application a Requesting Party (RqP) will / can use to access a resource.  The Resource Owner (RO) should be able to communicate the resource "information" to the Requesting Party (RqP) and  allow them to choose the appropriate Client Application (CA).

A "well know" resolver service (simple web site) could be used.  The Resource Owner (RO) could share a link, containing resource information, to the resolver service.  The Requesting Party (RqP) would open the link in a browser.  The resolver service would have knowledge about all of the Client Applications (CA) and present a chooser type interface.  When the user selects a Client Application (CA), the user is forwarded to that Client Application (CA), along with the resource information.  The resolver service could automatically route the user when there is only one Client Application (CA).

Relationship Model

The Resource Owner Application (ROA), or a service it uses, could derive the proper URI to the intended Requesting Party (RqP).  The proper URI is a sharable link to an application that the Requesting Party (RqP) should already have access to and the application is configured with the Authorization Server (AS) as a valid OAuth client.

When the Client Application (CA) is "on-boarded", it would be registered as a OAuth client with the Authorization Server (AS).  The Client Application (CA) would be associated with an Organization.  The Client Application (CA) would have a URI attribute which indicates how to access the application.

The Requesting Party (RqP) will ultimately need to be provisioned to the Authorization Server (AS) to access the resource.  The Requesting Party (RqP) is "on-boarded" through the Identity Manager (IdM) and a relationship would be established with one or more Organizations via the email attribute.

At run-time, the Resource Owner (RO) chooses to share a resource and searches / selects a Requesting Party (RqP).  If the Requesting Party (RqP) is affiliated with multiple Organizations (via multiple emails) the Resource Owner (RO) would need to select an Organization.  The Resource Owner Application (ROA) would now be able to dynamically obtain the Requesting Party's (RqP) affiliate email address and associated application URI.

RO -> ROA -> RqP -> email -> Org -> CA URI

Information

The "information" will include an identifier for the resource. The "information" may include scopes that apply to the resource, for the given Requesting Party (RqP). The transferred "information" does not include who the Resource Owner (RO) is and does not include who the Requesting Party (RqP) is.

  • The identifier MUST be unique and obfuscated as to not indicate inferences to the resource's type, title, name or content.
    • The identifier may follow the UUID format: 123e4567-e89b-12d3-a456-426655440000
    • The identifier may be different than the "primary key" in the Resource Servers (RS) data store
  • The scopes are a collection of "operations" or "actions" that the Requesting Party (RqP) can perform against the resource. Scopes may changed at any time, by the Resource Owner (RO), and may not match the scopes provided during a given RTOI.

The identifier and scopes can be formatted, structured, encoded to support the specific requirements of a give transportation solution.

Client Application

The Requesting Party (RqP) must use a registered Client Application (CA) to access a resource. A Requesting Party (RqP) may use multiple Client Applications (CA). example: A doctor (RqP) may need to use an application unique to the patients (RO) insurance organization. If the Resource Owner Application (ROA) can determine which Client Application (CA) will be used, the transferred information could contain data (sharable link URL) which would enable the Requesting Party (RqP) to easily access the resource.

Option 1: Authorization Server / Resource Server

All of the authorized Client Applications(CA) are known by the Authorization Server (AS) as OAuth 2.0 clients.

The Resource Source (RS) could be extended to obtain Client Application (CA) data. The Resource Server (RS) could expose an interface (REST) to share Client Application (CA) data with Resource Owner Applications (ROA). The Resource Owner Application (ROA) could enable the Resource Owner (RO) to choose a Client Application (CA) that the Requesting Party (RqP) will use. After selecting a Client Application (CA), a URI would be generated that can be shared with the Requesting Party (RqP).

Option 2: Resource Owner Application

The Resource Owner Application (ROA) could be configured to store a collection of known Client Applications (CA). The Resource Owner (RO) would select the Client Application (CA) when the resource is being shared.

Instead of requiring the Resource Owner (RO) to select the Client Application (CA), the Resource Type could be leveraged and associate each one to a specific Client Application (CA). The Resource Owner Application (ROA) meta data would need to be updated and maintained to the associated Client Application (CA) data.

This solution would require on-going maintenance to track changes to Client Applications (CA).

Transportation options