OAuth 2.0 Resource Set Registration

There are various circumstances under which an OAuth 2.0 [RFC6749] resource server may need to communicate information about its protected resources to its authorization server:

• In some OAuth 2.0 deployments, the resource server and authorization server are operated by the same organization and deployed in the same domain, but many resource servers share a single authorization server (a security token service (STS) component). Thus, even though the trust between these two is typically tightly bound, there is value in defining a singular standardized resource protection communications interface between the authorization server and each of the resource servers.
• In some deployments of OpenID Connect [OpenIDConnect], which has a dependency on OAuth 2.0, the OpenID Provider (OP) component is a specialized version of an OAuth authorization server that brokers availability of user attributes by dealing with an ecosystem of attribute providers (APs). These APs effectively function as third-party resource servers. Thus, there is value in defining a mechanism by which all of the third-party APs can communicate with a central OP, as well as ensuring that trust between the authorization server and resource servers is able to be established in a dynamic, loosely coupled fashion.
• In some deployments of User-Managed Access [UMA], which has a dependency on OAuth 2.0, an end-user resource owner (the "user" in UMA) may choose their own authorization server as an independent cloud-based service, along with using any number of resource servers that make up their "personal cloud". Thus, there is value in defining a mechanism by which all of the third-party resource servers can outsource resource protection (and potentially discovery) to a central authorization server, as well as ensuring that trust between the authorization server and resource servers is able to be established by the resource owner in a dynamic, loosely coupled fashion.

This specification defines an API through which the resource server can register information about resource sets with the authorization server.

1.1�Notational Conventions

1.2�Terminology

1.3�Authorization Server Configuration Data

This specification defines a resource set registration API. The endpoint for this API SHOULD also require some form of authentication to access this endpoint, such as Client Authentication as described in [RFC6749] or a separate OAuth access token. The methods of managing and validating these authentication credentials are out of scope of this specification.

For any of the resource owner's sets of resources this authorization server needs to be aware of, the resource server MUST register these resource sets at the authorization server's registration endpoint.

Note: When a client attempts access to a presumptively protected resource without an access token, as occurs in [UMA], the resource server needs to derive the authorization server and resource set identifier associated with that resource from some other aspect of the client's request. This effectively means that the resource server’s API needs to be structured in such a way that the client's RPT-free request uniquely identifies the resource set. In practice, this information likely needs to be passed through the URI, headers, or body of the request.

2.1�Scope Descriptions

{
  "name" : "View",
  "icon_uri" : "http://www.example.com/icons/reading-glasses"
}

2.2�Resource Set Descriptions

{
  "name" : "Photo Album",
  "icon_uri" : "http://www.example.com/icons/flower.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ],
  "type" : "http://www.example.com/rsets/photoalbum"
}

2.3�Resource Set Registration API

POST /rs/resource_set HTTP/1.1
Content-Type: application/json
Authorization: Bearer MHg3OUZEQkZBMjcx
...

{
  "name" : "Tweedl Social Service",
  "icon_uri" : "http://www.example.com/icons/sharesocial.png",
  "scopes" : [
    "read-public",
    "post-updates",
    "read-private",
    "http://www.example.com/scopes/all"
  ],
  "type" : "http://www.example.com/rsets/socialstream/140-compatible"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /rs/resource_set/12345
...

{
  "_id" : "12345",
  "user_access_policy_uri" : "http://as.example.com/rs/222/resource/333/policy"
}

GET /rs/resource_set/12345 HTTP/1.1
Authorization: Bearer MHg3OUZEQkZBMjcx
...

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "_id" : "12345",
  "name" : "Tweedl Social Service",
  "icon_uri" : "http://www.example.com/icons/sharesocial.png",
  "scopes" : [
    "read-public",
    "post-updates",
    "read-private",
    "http://www.example.com/scopes/all"
  ],
  "type" : "http://www.example.com/rsets/socialstream/140-compatible"
}

PUT /rs/resource_set/12345 HTTP/1.1
Content-Type: application/json
Authorization: Bearer 204c69636b6c69
...

{
  "name" : "Photo Album",
  "icon_uri" : "http://www.example.com/icons/sky.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "public-read"
  ],
  "type" : "http://www.example.com/rsets/photoalbum"
}

HTTP/1.1 200 OK
...

{
  "_id": "12345"
}

DELETE /rs/resource_set/12345
Authorization: Bearer 204c69636b6c69
...

HTTP/1.1 204 No content
...

GET /rs/resource_set HTTP/1.1
Authorization: Bearer 204c69636b6c69
...

HTTP/1.1 200 OK
...

[ "12345", "54321" ]

When a resource server attempts to access the resource set registration endpoint at the authorization server, if the request is successfully authenticated by OAuth means, but is invalid for another reason, the authorization server produces an error response by adding the following properties to the entity body of the HTTP response:

error

REQUIRED. A single error code, as noted in the API definition. Value for this property is defined in the specific authorization server endpoint description.

error_description

OPTIONAL. A human-readable text providing additional information, used to assist in the understanding and resolution of the error occurred.

error_uri

OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the end-user with additional information about the error.

This specification largely relies on OAuth for API security and shares its security and vulnerability considerations.

Some form of trust relationship between the authorization server and resource server is presumed. However, where the trust relationship is weak or loosely coupled, for example, if dynamic client registration is supported for resource servers as OAuth clients of the resource set registration API, the authorization server must be extremely careful with any information supplied during resource set registration that may be displayed to the resource owner in a user interface or be used to drive authorization server-based workflows.

For example, a rogue resource server could register a resource set or scope with a reference to a drive-by download in icons returned by the "icon_uri", enticing the resource owner to click on the icon during the policy setting process. The authorization server SHOULD check to see if all URIs defined in the "icon_uri" and in the array of "redirect_uris" resolve to valid web pages. Since these are URI values that are intended to be displayed to the resource owner in a policy-setting interface, the authorization server SHOULD protect the resource owner from malicious content hosted at the URIs where possible.

Additionally, a rogue resource server could supply misleading names for a resource set or scope, or mislabel the type of a resource set, leading a resource owner to set policy incorrectly.

One approach to mitigating the threat of bad URIs is that, before presenting clickable icons, the authorization server could download the content hosted at the linked URIs, check the content against a malware scanner and blacklist filter, determine whether or not there is mixed secure and non-secure content at the URL, and other possible server-side mitigations. Note that the content in these URIs can change at any time and the authorization server cannot provide complete confidence in the safety of the URIs, but these practices could help. To further mitigate this kind of threat, the authorization server can also warn the user that the links have been provided by a third party, should be treated with caution, and are not hosted by the authorization server itself. For instance, instead of providing the links directly in an HTML anchor, the authorization server can direct the user to an interstitial warning page before allowing the user to continue to the target URI.

An alternative approach may be available in deployment ecosystems where trust relationships with resource servers may be weak but APIs, resource set semantics, and scopes have been standardized. A resource server could potentially increase the likelihood of an authorization server trusting the URIs it registers by using well-known and third-party-standardized URIs. This may benefit resource set type values as well, if these are represented as URIs.

The communication between the authorization server and resource server may expose personally identifiable information of a resource owner. The context in which this API is used SHOULD account for its own unique privacy considerations.

This document makes no request of IANA.

The following non-normative example illustrates the intent and usage of resource set descriptions and scope descriptions as part of resource set registration in the context of [UMA]. This example shows the use of scope strings that are URIs. See Section�2.3 for some examples of plain scope strings.

This example contains some steps that are exclusively in the realm of user experience rather than web protocol, to achieve realistic illustration. These steps are labeled "user experience only". Some other steps are exclusively internal to the operation of the entity being discussed. These are labeled "internal only".

A resource owner, Alice Adams, has just uploaded a photo of her new puppy to a resource server, Photoz.example.com, and wants to ensure that this specific photo is not publicly accessible.

Alice has already introduced this resource server to her authorization server, CopMonkey.example.com. However, Alice has not previously instructed Photoz to use CopMonkey to protect any photos of hers.

Alice has previously visited CopMonkey to map a default "do not share with anyone" policy to any resource sets registered by Photoz, until such time as she maps some other more permissive policies to those resources. (User experience only. This may have been done at the time Alice introduced the resource server to the authorization server, and/or it could have been a global or resource server-specific preference setting. A different constraint or no constraint at all might be associated with newly protected resources.) Other kinds of policies she may eventually map to particular photos or albums might be "Share only with husband@email.example.net" or "Share only with people in my 'family' group".

Photoz itself has a publicly documented application-specific API that offers two dozen different methods that apply to single photos, such as "addTags" and "getSizes", but rolls them up into two photo-related scopes of access: "view" (consisting of various read-only operations) and "all" (consisting of various reading, editing, and printing operations). It defines two scope descriptions that represent these scopes, which it is able to reuse for all of its users (not just Alice), and ensures that these scope description documents are available through HTTP GET requests that may be made by authorization servers.

The "name" property values are intended to be seen by Alice when she maps authorization constraints to specific resource sets and actions while visiting CopMonkey, such that Alice would see the strings "View Photo and Related Info" and "All Actions", likely accompanied by the referenced icons, in the CopMonkey interface. (Other users of Photoz might similarly see the same labels at CopMonkey or whatever other authorization server they use. Photoz could distinguish natural-language labels per user if it wishes, by pointing to scopes with differently translated names.)

{
  "name" : "View Photo and Related Info",
  "icon_uri" : "http://www.example.com/icons/reading-glasses.png"
}

{
  "name" : "All Actions",
  "icon_uri" : "http://www.example.com/icons/galaxy.png"
}

While visiting Photoz, Alice selects a link or button that instructs the site to "Protect" or "Share" this single photo (user experience only; Photoz could have made this a default or preference setting).

As a result, Photoz defines for itself a resource set that represents this photo (internal only; Photoz is the only application that knows how to map a particular photo to a particular resource set). Photoz also prepares the following resource set description, which is specific to Alice and her photo. The "name" property value is intended to be seen by Alice in mapping authorization policies to specific resource sets and actions when she visits CopMonkey. Alice would see the string "Steve the puppy!", likely accompanied by the referenced icon, in the CopMonkey interface. The possible scopes of access on this resource set are indicated with URI references to the scope descriptions, as shown just above.

{
  "name" : "Steve the puppy!",
  "icon_uri" : "http://www.example.com/icons/flower",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

Photoz uses the Create method of CopMonkey's standard OAuth resource set registration API, presenting its Alice-specific access token to use the API to register and assign an identifier to the resource set description.

POST /rs/resource_set HTTP/1.1
Content-Type: application/json
...

{
  "name" : "Steve the puppy!",
  "icon_uri" : "http://www.example.com/icons/flower.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

If the registration attempt succeeds, CopMonkey responds in the following fashion.

HTTP/1.1 201 Created
Content-Type: application/json
...

{
  "_id" : "112210f47de98100"
}

At the time Alice indicates she would like this photo protected, Photoz can choose to redirect Alice to CopMonkey for further policy setting, access auditing, and other authorization server-related tasks (user experience only).

Once it has successfully registered this description, Photoz is responsible for outsourcing protection to CopMonkey for access attempts made to this photo.

Over time, as Alice uploads other photos and creates and organizes photo albums, Photoz can use additional methods of the resource set registration API to ensure that CopMonkey's understanding of Alice's protected resources matches its own.

For example, if Photoz suspects that somehow its understanding of the resource set has gotten out of sync with CopMonkey's, it can ask to read the resource set description as follows.

GET /rs/resource_set/112210f47de98100 HTTP/1.1
Host: as.example.com
...

Example of an HTTP response to a "read resource set description" request, containing a resource set description from the authorization server:

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "_id" : "112210f47de98100",
  "name" : "Photo album",
  "icon_uri" : "http://www.example.com/icons/flower.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

GET /rs/resource_set HTTP/1.1
Host: as.example.com
...

HTTP/1.1 200 OK
...

[ "112210f47de98100", "34234df47eL95300" ]

If Alice later changes the photo's title (user experience only) on Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz would use the Update method to ensure that Alice's experience of policy-setting at CopMonkey remains consistent with what she sees at Photoz. Following is an example of this request. Note that the entire updated resource set description has to be included in the PUT request.

PUT /rs/resource_set/112210f47de98100 HTTP/1.1
Content-Type: application/json
Host: as.example.com
...

{
  "name" : "Steve on October 14, 2011",
  "icon_uri" : "http://www.example.com/icons/flower.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

CopMonkey would respond as follows.

HTTP/1.1 201 Created
Content-Type: application/json
...

{
  "_id" : "112210f47de98100"
}

There are other reasons Photoz might want to update resource set descriptions, having nothing to do with Alice's actions or wishes. For example, it might extend its API to include new features, and want to add new scopes to all of Alice's and other users' resource set descriptions.

DELETE /rs/resource_set/112210f47de98100 HTTP/1.1
Host: as.example.com
...

The following people made significant text contributions to the specification:

• Paul C. Bryan, ForgeRock US, Inc. (former editor)
• Mark Dobrinic, Cozmanova
• George Fletcher, AOL
• Lukasz Moren, Cloud Identity Ltd
• Christian Scholz, COMlounge GmbH (former editor)
• Mike Schwartz, Gluu
• Jacek Szpot, Newcastle University

Additional contributors to this specification include the Kantara UMA Work Group participants, a list of whom can be found at [UMAnitarians].