UMA Permission Registration Extension

Abstract

This extension specification defines a mechanism for an UMA V1.0.1 resource server to register multiple requested permissions at an UMA authorization server, not just a single one.

Status of This Document

This draft extension specification was developed by the User-Managed Access Work Group.

Copyright Notice

Copyright (c) 2015 Kantara Initiative and the persons identified as the document authors. All rights reserved.

This document is subject to the Kantara IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non discriminatory (RAND) (HTML version).

Table of Contents

• 1.������Introduction
• 1.1������Notational Conventions
• 2.������Extension to How Resource Server Registers Requested Permissions With Authorization Server
• 2.1������Extension Summary and Identifying URI
• 2.2������Authorization Server Configuration Data Extension for Indicating Extension Support
• 2.3������Resource Server Request to Permission Registration Endpoint
• 2.4������Authorization Server Response to Resource Server on Permission Registration Success
• 2.5������Authorization Server Response to Resource Server on Permission Registration Failure
• 3.������Security Considerations
• 4.������Privacy Considerations
• 5.������IANA Considerations
• 6.������Normative References
• Author's Address

1.��Introduction

This extension specification defines a mechanism for a User-Managed Access ([UMA]) V1.0.1 resource server to register multiple requested permissions at an UMA authorization server, not just a single one.

1.1��Notational Conventions

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in [RFC2119].

Unless otherwise noted, all protocol properties and values are case sensitive. JSON [RFC7159] data structures defined by this specification MAY contain extension properties that are not defined in this specification. Any entity receiving or retrieving a JSON data structure SHOULD ignore extension properties it is unable to understand. Extension names that are unprotected from collisions are outside the scope of this specification.

2.��Extension to How Resource Server Registers Requested Permissions With Authorization Server

The resource server is assumed to need to use the protection API's permission registration endpoint under all the same circumstances as defined in the base UMA specification. This extension specification defines a mechanism for allowing an array of one or more requested permissions.

Note: A future minor revision of the UMA specification could potentially incorporate this extension as long as the non-array option is preserved; the non-array option could be eliminated only in a future major revision of the specification because it would be backwards incompatible.

2.1��Extension Summary and Identifying URI

Following is a summary of the extension defined in this specification.

• Identifying URI: https://docs.kantarainitiative.org/uma/extensions/perm-reg-1.0
• Extension author and contact information: Eve Maler (eve@xmlgrrl.com)
• Updates or obsoletes: None; this extension is new.
• Security considerations: None additional.
• Privacy considerations: None additional.
• Error states: See below.

2.2��Authorization Server Configuration Data Extension for Indicating Extension Support

An authorization server that supports the extension defined in this specification MUST provide a JSON property in its configuration data with a name that matches the identifying URI as defined in Section��2.1, and one of the following values:

supported

This is an authorization server that supports the extension form of requested permission registration in addition to the form defined in the UMA V1.0.1 specification.

extension-only

This is an authorization server that supports the extension form (arrays only), and not the singular form of requested permissions. Note that such an authorization server cannot conform to UMA V1.0 or V1.0.1.

2.3��Resource Server Request to Permission Registration Endpoint

Example of an HTTP request that registers a requested permission at the authorization server's permission registration endpoint, with a PAT in the header, containing an array of requested permissions with a single object in it:

POST /host/rsrc_uri HTTP/1.1

Content-Type: application/json

Host: as.example.com

Authorization: Bearer 426561726572

[

{ "resource_set_id": "7b727369647d",

�� "scopes": [ "view", "print" ]

}

]

Example of an HTTP request that registers a requested permission at the authorization server's permission registration endpoint, with a PAT in the header, containing an array of requested permissions with three objects in it:

POST /host/rsrc_uri HTTP/1.1

Content-Type: application/json

Host: as.example.com

Authorization: Bearer 426561726572

[

{ "resource_set_id": "7b727369647d",

�� "scopes": [ "view", "crop", "lightbox" ]

},

{ "resource_set_id": "7b72736964327d",

�� "scopes": [ "view", "layout", "print" ]

},

{ "resource_set_id": "7b72736964337d",

�� "scopes": [

�� �� �� "http://www.example.com/scopes/all"

�� ]

}

]

2.4��Authorization Server Response to Resource Server on Permission Registration Success

If the authorization server is successful in creating a permission ticket in response to all the elements of the resource server's request, it responds with an HTTP 201 (Created) status code and includes a ticket property in the JSON-formatted body that represents the entire set of the one or more requested permissions that were registered.

For example:

HTTP/1.1 201 Created

Content-Type: application/json

...

{

"ticket": "332d7273-6964732d-63726561-74656421"

}

2.5��Authorization Server Response to Resource Server on Permission Registration Failure

If the resource server's request is authenticated properly but fails because one or more of the requested permissions has an invalid resource set identifier or an invalid scope, then... [TO BE DISCUSSED: What should happen? Should a partial result be registered? If so, what should be the response? Or should the whole thing fail?]

3.��Security Considerations

None additional.

4.��Privacy Considerations

None additional.

5.��IANA Considerations

This document makes no request of IANA.

6. Normative References

Author's Address

Eve Maler
ForgeRock
EMail: eve.maler@forgerock.com