Skip to content

UMA API

UMA API Document#

User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how resource owners can manipulate to protect the resources. The client can have access by arbitrary requesting parties, which means the requesting resource can be any number of resource servers and a centralized authorization server managing the access based on protected resource rules and policies defined.

In order to increase interoperable communication among the authorization server, resource server, and client, UMA leverages two purpose-built APIs related to the outsourcing of authorization, themselves protected by OAuth (or an OAuth-based authentication protocol) in embedded fashion.

The UMA protocol has three broad phases as below

                                          +--------------+
                                           |   resource   |
          +---------manage (A)------------ |     owner    |
          |                                +--------------+
          |         Phase 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) |
   +------------+                          +--------------+
          ^                                       |
          |         Phases 2 and 3:         authorize (D)
          |         get authorization,            |
          |         access a resource             v
          |                                +--------------+
          +---------access (E)-------------|    client    |
                                           +--------------+

                                           requesting party
The Three Phases of the UMA.

  • Protect a resource

  • Get Authorization

  • Access a Resource

UMA Discovery API#

/.well-known/uma-configuration

Overview#

PATH#

/oxauth/uma-configuration

getConfiguration#

GET /oxauth/uma-configuration

Provides configuration data as JSON document. It contains options and endpoints supported by the authorization server.

URL#
http://gluu.org/oxauth/uma-configuration
Parameters#
Access Type required Description
Scopes Array(string) required -
Claims string required -
Response#

UmaConfiguration

Errors#
Status Code Reason
500 Failed to build UMA configuration JSON object.

Data Types#

UmaConfiguration#

type required access description notes
string required version The version of the UMA core protocol to which this authorization server conforms. The value MUST be the string "1.0". -
string required issuer A URI indicating the party operating the authorization server. -
Array[string] required patProfilesSupported OAuth access token profiles supported by this authorization server for PAT issuance. The property value is an array of string values, where each string value is either a reserved keyword defined in this specification or a URI identifying an access token profile defined elsewhere. The reserved keyword "bearer" as a value for this property stands for the OAuth bearer token profile [OAuth-bearer]. The authorization server is REQUIRED to support this profile, and to supply this string value explicitly. The authorization server MAY declare its support for additional access token profiles for PATs. -
Array[string] required aatProfilesSupported OAuth access token profiles supported by this authorization server for AAT issuance. The property value is an array of string values, where each string value is either a reserved keyword defined in this specification or a URI identifying an access token profile defined elsewhere. The reserved keyword "bearer" as a value for this property stands for the OAuth bearer token profile [OAuth-bearer]. The authorization server is REQUIRED to support this profile, and to supply this string value explicitly. The authorization server MAY declare its support for additional access token profiles for AATs. -
Array[string] required rptProfilesSupported UMA RPT profiles supported by this authorization server for RPT issuance. The property value is an array of string values, where each string value is either a reserved keyword defined in this specification or a URI identifying an RPT profile defined elsewhere. The reserved keyword "bearer" as a value for this property stands for the UMA bearer RPT profile defined in Section 3.3.2. The authorization server is REQUIRED to support this profile, and to supply this string value explicitly. The authorization server MAY declare its support for additional RPT profiles. -
Array[string] required patGrantTypesSupported OAuth grant types supported by this authorization server in issuing PATs. The property value is an array of string values. Each string value MUST be one of the grant_type values defined in [OAuth2], or alternatively a URI identifying a grant type defined elsewhere. -
Array[string] required aatGrantTypesSupported OAuth grant types supported by this authorization server in issuing AATs. The property value is an array of string values. Each string value MUST be one of the grant_type values defined in [OAuth2], or alternatively a URI identifying a grant type defined elsewhere. -
Array[string] optional claimTokenProfilesSupported Claim formats and associated sub-protocols for gathering claims from requesting parties, as supported by this authorization server. The property value is an array of string values, which each string value is either a reserved keyword defined in this specification or a URI identifying a claim profile defined elsewhere. -
Array[string] optional umaProfilesSupported UMA profiles supported by this authorization server. The property value is an array of string values, where each string value is a URI identifying an UMA profile. Examples of UMA profiles are the API extensibility profiles defined in Section 5. -
string required dynamicClientEndpoint The endpoint to use for performing dynamic client registration. Usage of this endpoint is defined by [DynClientReg]. The presence of this property indicates authorization server support for the dynamic client registration feature and its absence indicates a lack of support. -
string required tokenEndpoint The endpoint URI at which the resource server or client asks the authorization server for a PAT or AAT, respectively. A requested scope of "uma_protection" results in a PAT. A requested scope of "uma_authorization" results in an AAT. Usage of this endpoint is defined by [OAuth2]. -
string required resourceSetRegistrationEndpoint The endpoint URI at which the resource server introspects an RPT presented to it by a client. Usage of this endpoint is defined by [OAuth-introspection] and Section 3.3.1. A valid PAT MUST accompany requests to this protected endpoint. -
string required introspectionEndpoint The endpoint URI at which the resource server introspects an RPT presented to it by a client. Usage of this endpoint is defined by [OAuth-introspection] and Section 3.3.1. A valid PAT MUST accompany requests to this protected endpoint. -
string required permissionRegistrationEndpoint The endpoint URI at which the resource server registers a client-requested permission with the authorization server. Usage of this endpoint is defined by Section 3.2. A valid PAT MUST accompany requests to this protected endpoint. -
string required rptEndpoint The endpoint URI at which the client asks the authorization server for an RPT. Usage of this endpoint is defined by Section 3.4.1. A valid AAT MUST accompany requests to this protected endpoint. -
string required gatEndpoint The endpoint URI at which the client asks the authorization server for an GAT. Usage of this endpoint is defined by Gluu documentation. -
string required authorizationEndpoint The endpoint URI at which the client asks to have authorization data associated with its RPT. Usage of this endpoint is defined in Section 3.4.2. A valid AAT MUST accompany requests to this protected endpoint. -
string required scopeEndpoint Scope endpoint -
string required requestingPartyClaimsEndpoint The endpoint URI at which the authorization server interacts with the end-user requesting party to gather claims. If this property is absent, the authorization server does not interact with the end-user requesting party for claims gathering. -
string optional rptAsJwt RPT as JWT -
string optional rptAsJwt RPT as JWT -

UMA Authorization API#

Overview#

PATH#

/requester/perm

requestRptPermissionAuthorization#

POST

/requester/perm

Client Requests Authorization Data Once in possession of a permission ticket and an AAT for this authorization server, the client asks the authorization server to give it authorization data corresponding to that permission ticket. It performs a POST on the RPT endpoint, supplying its own AAT in the header and a JSON object in the body with a "ticket" property containing the ticket as its value.

If the client had included an RPT in its failed access attempt, It MAY also provide that RPT in an "rpt" property in its request to the authorization server.

In circumstances where the client needs to provide requesting party claims to the authorization server, it MAY also include a "claim_tokens" property in its request; see Section 3.4.1.2.1 for more information. The authorization server uses the ticket to look up the details of the previously registered requested permission, maps the requested permission to operative resource owner policies based on the resource set identifier and scopes associated with it, potentially requests additional information, and ultimately responds positively or negatively to the request for authorization data.

The authorization server bases the issuing of authorization data on resource owner policies. These policies thus amount to an asynchronous OAuth authorization grant. The authorization server is also free to enable the resource owner to set policies that require the owner to interact with the server in near-real time to provide consent subsequent to an access attempt. All such processes are outside the scope of this specification.

URL#
http://gluu.org/requester/perm
Parameters#
  • body

    Parameter Required Description Data Type
    body false RptAuthorizationRequest
    - header

    Parameter Required Description Data Type
    Authorization false the resource server will receive an error of any kind from the authorization server when trying to register a requested permission such that it did not receive a permission ticket, then assuming the resource server chooses to respond to the client string
    Host false The Client Host seeking access string

Response#

Errors#
Status Code Reason
403 Forbidden. Example of a "need_info" respo nse with a full set of "error_details" hints: HTTP/1.1 403 Forbidden Content-Type: application/json Cache-Control: no-store ... { "error": "need_info", "error_details": { "authentication_context": { "required_acr": ["https://example.com/acrs/LOA3.14159"] }, "requesting_party_claims": { "required_claims": [ { "name": "email23423453ou453", "friendly_name": "email", "claim_type": "urn:oid:0.9.2342.19200300.100.1.3", "claim_token_format": ["http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken"], "issuer": ["https://example.com/idp"] } ], "redirect_user": true, "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" } } }
401 Unauthorized
400 Bad request

Data Types#

ClaimTokenList#

type required access description notes
string required format A string specifying the format of the accompanying claim tokens. The string MAY be a URI. -
string required token A string containing the claim information in the indicated format, base64url encoded if it is not already so encoded. If claim token format features are included that require special interpretation, the client and authorization server are assumed to have a prior relationship that establishes how to interpret these features. -

RptAuthorizationRequest#

type required access description notes
ClaimTokenList required claims -
string required rpt Requesting party token -
string required ticket The same permission ticket value that the client provided in the request. It MUST be present if and only if the authorization_state is need_info. -

UMA Create rpt API#

/requester/rpt

Overview#

The endpoint at which the requester asks the AM to issue an RPT.

PATH#

/requester/rpt

PermissionToken#

POST

/requester/rpt

URL#
http://gluu.org/requester/rpt
Parameters#
  • header

    Parameter Required Description Data Type
    ticket required - string

Response#

Errors#
Status Code Reason
401 Unauthorized

UMA Resource Registration API#

/host/rsrc/resource_set

Overview#

Resource set is defined by the resource server, which is required by the authorization server to register the resource set description.

Resource set description is a JSON document with the following properties described in ResourceSet

RESTful API is used by Resource Server at the authorization server's resource set registration endpoint to create, read, update, and delete resource set description.

Request to the resource set is registration is incorrect, the authorization server responds with an with error message by including the below error codes in the response. Discussed detail in unsupported methods

  • unsupported_method_type: The resource server request used an unsupported HTTP method. The authorization server MUST respond with the HTTP 405 (Method Not Allowed) status code.
  • not_found: The resource set requested from the authorization server cannot be found. The authorization server MUST respond with HTTP 404 (Not Found) status code.

PATH#

/host/rsrc/resource_set{rsid}

deleteResourceSet#

DELETE /host/rsrc/resource_set{rsid}

Deletes a previously registered resource set description using the DELETE method, thereby removing it from the authorization server's protection regime.

URL#
http://gluu.org/host/rsrc/resource_set{rsid}
Parameters#
  • path

    Parameter Required Description Data Type
    rsid true Resource set description ID string
    - header

    Parameter Required Description Data Type
    Authorization false string

Response#

ResourceSet

JSON body of a successful response will contain the following properties

Parameter Required Description Data Type
_id required A string value repeating the authorization server-defined identifier for the web resource corresponding to the resource set. Its appearance in the body makes it readily available as an object identifier for various resource set management tasks. string
user_access_policy_uri optional A URI that allows the resource server to redirect an end-user resource owner to a specific user interface within the authorization server where the resource owner can immediately set or modify access policies subsequent to the resource set registration action just completed. The authorization server is free to choose the targeted user interface. string
Errors#
Status Code Reason
401 Unauthorized

getResourceSet#

GET

/host/rsrc/resource_set{rsid}

Reads a previously registered resource set description using the GET method. If the request is successful, the authorization server MUST respond with a status message that includes a body containing the referenced resource set description, along with an "_id" property.

URL#
http://gluu.org/host/rsrc/resource_set{rsid}
Parameters#
  • path

    Parameter Required Description Data Type
    rsid true Resource set description object ID string
    - header

    Parameter Required Description Data Type
    Authorization false string

Response#

ResourceSet

Errors#
Status Code Reason
401 Unauthorized

updateResourceSet#

PUT /host/rsrc/resource_set{rsid}

Updates a previously registered resource set description using the PUT method. If the request is successful, the authorization server MUST respond with a status message that includes an "_id" property.

URL#
http://gluu.org/host/rsrc/resource_set{rsid}
Parameters#
  • body

    Parameter Required Description Data Type
    body true Resource set description JSON object ResourceSet
    - path

    Parameter Required Description Data Type
    rsid true Resource set description ID string
    - header

    Parameter Required Description Data Type
    Authorization false string

Response#

Errors#
Status Code Reason
401 Unauthorized

ResourceSetList#

Path#

/host/rsrc/resource_set

GET

/host/rsrc/resource_set

Lists all previously registered resource set identifiers for this user using the GET method. The authorization server MUST return the list in the form of a JSON array of {rsid} string values.

The resource server uses this method as a first step in checking whether its understanding of protected resources is in full synchronization with the authorization server's understanding.

URL#
http://gluu.org/host/rsrc/resource_set
Parameters#
  • query

    Parameter Required Description Data Type
    Name required A human-readable string describing some scope (extent) of access. The authorization server MAY use this name in any user interface it presents to the resource owner. string
    icon_uri optional A URI for a graphic icon representing the scope. The authorization server MAY use the referenced icon in any user interface it presents to the resource owner. string

  • header

    Parameter Required Description Data Type
    Authorization required access token in the header, response from the authorization server , if the request is successful. Along with the properties below string
    _id required Obtained the request is successful, from the authroization server string
    Name required A human-readable string describing some scope (extent) of access. The authorization server MAY use this name in any user interface it presents to the resource owner. string
    icon_uri optional A URI for a graphic icon representing the scope. The authorization server MAY use the referenced icon in any user interface it presents to the resource owner. string
    scopes required string

Response#

ResourceSet

Errors#
Status Code Reason
401 Unauthorized

createResourceSet#

POST /host/rsrc/resource_set

Adds a new resource set description using the POST method. If the request is successful, the authorization server MUST respond with a status message that includes an _id property.

URL#
http://gluu.org/host/rsrc/resource_set
Parameters#
  • body

    Parameter Required Description Data Type
    body true Resource set description ResourceSet
    - header

    Parameter Required Description Data Type
    Authorization required string

Response#

Errors#
Status Code Reason
401 Unauthorized

unsupportedHeadMethod#

HEAD /host/rsrc/resource_set

Not allowed

URL#

http://gluu.org/host/rsrc/resource_set

Parameters#

Parameter Required Description
error required A single error code. Values for this property are defined throughout this specification.
error_description optional A URI identifying a human-readable web page with information about the error.
error_uri optional A single error code. Values for this property are defined throughout this specification.

Errors#

Status Code Reason

unsupportedOptionsMethod#

OPTIONS

/host/rsrc/resource_set

Not allowed

URL#

http://gluu.org/host/rsrc/resource_set

Parameters#

[unsupported methods]

Errors#

Status Code Reason

Data Types#

ResourceSet#

Type Required Access Description Notes
string required name A human-readable string describing a set of one or more resources. The authorization server MAY use this name in any user interface it presents to the resource owner. -
string optional uri A URI that provides the network location for the resource set being registered. For example, if the resource set corresponds to a digital photo, the value of this property could be an HTTP-based URI identifying the location of the photo on the web. The authorization server MAY use this information in various ways to inform clients about a resource set's location. When a client attempts access to a presumptively protected resource without an access token, the resource server needs to ascertain the authorization server and resource set identifier associated with that resource without any context to guide it. In practice, this likely means that the URI reference used by the client needs to be unique per resource set.
string optional type A string uniquely identifying the semantics of the resource set. For example, if the resource set consists of a single resource that is an identity claim that leverages standardized claim semantics for "verified email address", the value of this property could be an identifying URI for this claim. The authorization server MAY use this information in processing information about the resource set or displaying information about it in any user interface it presents to the resource owner. -
Array[string] required scopes An array of strings indicating the available scopes for this resource set. Any of the strings MAY be either a plain string or a URI -
string optional icon_uri A URI for a graphic icon representing the resource set. The authorization server MAY use the referenced icon in any user interface it presents to the resource owner. -

UMA Permission Registration API#

/host/rsrc_pr

Overview#

PATH#

/host/rsrc_pr

registerResourceSetPermission#

POST

/host/rsrc_pr

Registers permission using the POST method. The resource server uses the POST method at the endpoint. The body of the HTTP request message contains a JSON object providing the requested permission, using a format derived from the scope description format specified in [OAuth-resource-reg], as follows. The object has the following properties:

URL#
http://gluu.org/host/rsrc_pr
Parameters#
  • body

    Parameter Required Description Data Type
    body true The identifier for a resource set to which this client is seeking access. The identifier MUST correspond to a resource set that was previously registered. UmaPermission
    - header

    Parameter Required Description Data Type
    Authorization false string
    Host false string

Response#

Errors#
Status Code Reason
401 Unauthorized
400 Bad Request

Data Types#

UmaPermission#

type required access description notes
Date optional issuedAt Issued date of the permission request -
Array[string] required scopes - -
Date optional expiresAt Expiry of the permission request -
string required resourceSetId - -
Date optional nbf not before -

UMA rpt Status API#

/rpt/status

Overview#

PATH#

/rpt/status

requestRptStatusGet#

GET /rpt/status

Not allowed

URL#
http://gluu.org/rpt/status
Parameters#
  • form

    Parameter Required Description Data Type
    token required string
    token_type_hint required string
    - header

    Parameter Required Description Data Type
    Authorization false string

Response#

Errors#
Status Code Reason
405 Introspection of RPT is not allowed by GET HTTP method.

requestRptStatus#

POST /rpt/status

The resource server MUST determine a received RPT's status, including both whether it is active and, if so, its associated authorization data, before giving or refusing access to the client. An RPT is associated with a set of authorization data that governs whether the client is authorized for access.

The token's nature and format are dictated by its profile. The profile might allow it to be self-contained, such that the resource server is able to determine its status locally, or might require or allow the resource server to make a run-time introspection request of the authorization server that issued the token.

The endpoint MAY allow other parameters to provide further context to the query. For instance, an authorization service may need to know the IP address of the client accessing the protected resource in order to determine the appropriateness of the token being presented.

To prevent unauthorized token scanning attacks, the endpoint MUST also require some form of authorization to access this endpoint, such as client authentication as described in OAuth 2.0 [RFC6749] or a separate OAuth 2.0 access token such as the bearer token described in OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and validating these authentication credentials are out of scope of this specification.

URL#
http://gluu.org/rpt/status
Parameters#
  • form

    Parameter Required Description Data Type
    token true The string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint as defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, this is the "refresh_token" value returned from the token endpoint as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types are outside the scope of this specification. string
    token_type_hint false A hint about the type of the token submitted for introspection. The protected resource MAY pass this parameter in order to help the authorization server to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. An authorization server MAY ignore this parameter, particularly if it is able to detect the token type automatically. Values for this field are defined in OAuth Token Revocation [RFC7009]. string
    - header

    Parameter Required Description Data Type
    Authorization false string

Response#

Errors#
Status Code Reason
401 Unauthorized