Implements User-Managed Access (UMA) Profile of OAuth 2.0
User-Managed Access (UMA) is a profile of OAuth 2.0 RFC6749. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policies. The User endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. These Claims are represented by a JSON (or XML) object that contains a collection of name and value pairs for the Claims.
The User endpoint accepts Access Tokens as OAuth 2.0 Bearer Token Usage RFC 6749 and supports Cross Origin Resource Sharing to enable Java Script Clients to access the endpoint.
The UMA profile of OAuth is implemented in to three steps:
These are illustrated below.
+--------------+ | resource | +---------manage (A)------------ | owner | | +--------------+ | Step 1: | | protect a control (C) | resource | v v +------------+ +----------+--------------+ | | |protection| | | resource | | API | authorization| | server |<-protect (B)--| (needs | server | | | | PAT) | | +------------+ +----------+--------------+ | protected | | authorization| | resource | | API | |(needs RPT) | | (needs AAT) | +------------+ +--------------+ ^ | | Steps 2 and 3: authorize (D) | get authorization, | | access a resource v | +--------------+ +---------access (E)-------------| client | +--------------+ requesting party
The Three steps of the UMA profile of OAuth
The authorization server orchestrates and controls clients' access on their requesting parties' behalf to a resource owner's protected resources at a resource server, under conditions specified by that resource owner through policy.
Scope values
OpenID Connect Clients use scope values, as defined in Section 3.3 of OAuth 2.0 RFC 6749, to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. Protected Resource endpoints MAY perform different actions and return different information based on the scope values and other parameters used when requesting the presented Access Token.
OpenID Connect defines the following scope values that are used to request Claims:
profile | OPTIONAL | This scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at. |
OPTIONAL | This scope value requests access to the email and email_verified Claims. | |
address | OPTIONAL | This scope value requests access to the address Claim. |
phone | OPTIONAL | This scope value requests access to the phone_number and phone_number_verified Claims. |
scope | OPTIONAL | A Key Bridge proprietary extension. Provides a user name and group assignments. This is used by J2EE server authentication modules and supports integration of OpenID into J2EE application servers. |
Request and response examples
Key Bridge proprietary implementation
OpenID Connect Core 1.0, Section 5.3. specifies that the UserInfo Endpoint MUST support the use of the HTTP GET and HTTP POST methods. Key Bridge only supports the GET method to retrieve UserInfo.
The following is a non-normative example of a UserInfo request:
GET /user/info HTTP/1.1
Host: server.example.com
Authorization: Bearer SlAV32hkKG
The following is a non-normative example of a UserInfo Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "248289761001",
"name": "Jane Doe",
"given_name": "Jane",
"family_name": "Doe",
"preferred_username": "j.doe",
"email": "janedoe@example.com",
"picture": "http://example.com/janedoe/me.jpg"
}
Other User services follow a similar pattern.
Error response
When an error condition occurs the User endpoint returns an Error Response as defined in Section 3 of OAuth 2.0 Bearer Token Usage [RFC6750]. (HTTP errors unrelated to RFC 6750 are returned to the User Agent using the appropriate HTTP status code.)
The following is a non-normative example of a User Error Response:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
API resources
API resources
This is a Key Bridge proprietary extension of UMA.
Get the User Address Claim. The Address Claim represents a physical mailing address. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the End-User's privacy preferences. For example, the country and region might be returned without returning more fine-grained address information. Implementations MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields are combined.
Headers and URI patternAuthorization | string | HEADER | Basic authorization header encoding the client_id and client_secret values. | |
sub | string | TEMPLATE | The subject UID; this should reference an individual party record |
This is a Key Bridge proprietary extension of UMA.
Request information about an authorized End User. The Client may send a UserInfo request using either HTTP GET or HTTP POST. GET is strongly preferred. The End User Access Token, encoded in the OpenID session cookie and obtained from an OpenID Connect Authentication request MUST be sent as a Bearer Token, per Section 2 of OAuth 2.0 Bearer Token Usage [RFC6750].
Headers and URI patternAuthorization | string | HEADER | Basic authorization header encoding the client_id and client_secret values. | |
sub | string | TEMPLATE | The subject UID; this should reference an individual party record |
This is a Key Bridge proprietary extension of UMA.
Retrieve an End User's settings specific to a particular Client. In addition to a user profile, which is available via the getUserInfo endpoint, an End User's settings and preferences may also be centrally stored, set and updated on the Key Bridge OpenId service. User settings and preferences are conveyed and stored as arbitrary key/value pairs and are specific to the Client.
Headers and URI patternAuthorization | string | HEADER | Basic authorization header encoding the client_id and client_secret values. | |
sub | string | TEMPLATE | The subject UID; this should reference an individual party record |
User-Managed Access (UMA) Profile
Get the User Address Claim. The Address Claim represents a physical mailing address. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the End-User's privacy preferences. For example, the country and region might be returned without returning more fine-grained address information. Implementations MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields are combined.
Headers and URI patternAuthorization | string | HEADER | The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client. |
User-Managed Access (UMA) Profile
Request information about an authorized End User. The Client may send a UserInfo request using either HTTP GET or HTTP POST. GET is strongly preferred. The End User Access Token, encoded in the OpenID session cookie and obtained from an OpenID Connect Authentication request MUST be sent as a Bearer Token, per Section 2 of OAuth 2.0 Bearer Token Usage [RFC6750].
Headers and URI patternAuthorization | string | HEADER | The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client. |
User-Managed Access (UMA) Profile
Provides the username and scope information to enable basic OpenId authorization. This enables J2EE Clients to authorize (as opposed to authenticate) End Users based upon the End User's assigned scope, which is synonymous with J2EE group association.
Headers and URI patternAuthorization | string | HEADER | The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client. |
User-Managed Access (UMA) Profile
Retrieve an End User's settings specific to a particular Client. In addition to a user profile, which is available via the getUserInfo endpoint, an End User's settings and preferences may also be centrally stored, set and updated on the Key Bridge OpenId service. User settings and preferences are conveyed and stored as arbitrary key/value pairs and are specific to the Client.
Headers and URI patternAuthorization | string | HEADER | The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client. |
This is a Key Bridge proprietary extension of UMA.
Set or update an End User's settings on the OpenId provider. This method allows registered (and enabled / authorized) Client applications to store End User settings and preferences on the OpenId service provider system.
Headers and URI patternAuthorization | string | HEADER | Basic authorization header encoding the client_id and client_secret values. | |
sub | string | TEMPLATE | The subject UID; this should reference an individual party record |
UserSettings | application/json | A data transfer object allowing a Client (service provider) to exchange (upload and download) End User settings with an OpenId provider or central user management server. This follows the same transaction format as a UserInfo Request under UMA. |
Response | application/json | On success: a simple HTTP code 200 OK. |