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