Skip to content

UMA API

UMA API Document#

Attention

The official support end-of-life (EOL) date for Gluu Server 2.4.4 is December 31, 2018. Starting January 1, 2019, no further security updates or bug-fixes will be provided for Gluu Server 2.X. We strongly recommend upgrading to the newest version.

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#
Response#

UmaConfiguration

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

Data Types#

UmaConfiguration#

type required access description notes
Array[string] optional - - -
string optional - - -
Array[string] optional - - -
Array[string] optional - - -
string optional - - -
string optional - - -
Array[string] optional - - -
string optional - - -
string optional - - -
string optional - - -
string required - An uri indicating the party operating the authorization server. An uri indicating the party operating the authorization server.
string optional - - -
string optional - - -
Array[string] optional - - -
string optional - - -
string optional - - -
Array[string] optional - - -
string required - The version of the UMA core protocol to which this authorization server conforms. The value MUST be the string "1.0". The version of the UMA core protocol to which this authorization server conforms. The value MUST be the string "1.0".

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 string
    Host false string

Response#

Errors#
Status Code Reason
403 Forbidden. Example of a "need_info" response 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
boolean optional - - -
int optional - - -

RptAuthorizationRequest#

type required access description notes
ClaimTokenList optional - - -
string optional - - -
string optional - - -

UMA Create rpt API#

/requester/rpt

Overview#

PATH#

/requester/rpt

##### getRequesterPermissionToken POST /requester/rpt

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

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

    Parameter Required Description Data Type
    Authorization false string
    Host false string

Response#

Errors#
Status Code Reason
401 Unauthorized

UMA Resource Registration API#

/host/rsrc/resource_set

Overview#

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

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

/host/rsrc/resource_set#

getResourceSetList#

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
    scope false Scope uri string
    - header

    Parameter Required Description Data Type
    Authorization false 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 false 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#
Response#

Errors#
Status Code Reason

unsupportedOptionsMethod#

OPTIONS /host/rsrc/resource_set

Not allowed

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

Errors#
Status Code Reason

Data Types#

ResourceSet#

type required access description notes
string optional - - -
string optional - - -
string optional - - -
Array[string] optional - - -
string optional - - -

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. RegisterPermissionRequest
    - header

    Parameter Required Description Data Type
    Authorization false string
    Host false string

Response#

Errors#
Status Code Reason
401 Unauthorized
400 Bad Request

Data Types#

RegisterPermissionRequest#

type required access description notes
Date optional - - -
Array[string] optional - - -
Date optional - - -
string optional - - -
Date optional - - -

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 false string
    token_type_hint false 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