Gluu Server API

#Swagger Documentation

Current Swagger documentation for Gluu Server APIs can be found in the oxAuth API doc.

#Token Introspection

This API defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token.

Configuration properties:

• introspectionAccessTokenMustHaveUmaProtectionScope - oxauth configuration which defines whether access_token used in Authorization header must have uma_protection scope or not. If set to true and access_token in Authorization header does not have uma_protection scope then request is rejected with 403 forbidden HTTP code with appropriate log message in oxauth.log file.
• introspectionRestrictBasicAuthnToOwnTokens - oxauth configuration which defines whether allow client request only own tokens introspection or all tokens. Default value is false (introspect all tokens).

#Path

/restv1/introspection

#introspect

GET or POST

/restv1/introspection

Client introspects OAuth 2 token.

URL http://sample.com/restv1/introspection

Parameters

• token - REQUIRED. The string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint.
• response_as_jwt - OPTIONAL. Boolean value with default value false. If true, returns introspection response as JWT (signed based on client configuration used for authentication to Introspection Endpoint).

Response

Sample request/response

POST /introspect HTTP/1.1
Host: sample.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483

token=2YotnFZFEjr1zCsicMWpAA
response_as_jwt=false

HTTP/1.1 200 OK
Content-Type: application/json

{
   "active": true,
   "client_id": "l238j323ds-23ij4",
   "username": "jdoe",
   "scope": "read write dolphin",
   "sub": "Z5O3upPC88QrAjx00dis",
   "aud": "https://protected.example.net/resource",
   "iss": "https://server.example.com/",
   "exp": 1419356238,
   "iat": 1419350238,
   "extension_field": "twenty-seven"
}

Errors

#Token Revocation

This API defines a method for a client to notify an OAuth 2.0 authorization server that a previously obtained refresh or access token is no longer needed, allowing the server to clean up security credentials.

When a token is revoked, all related tokens and the underlying authorization grant are also revoked. If the revoked token is a refresh token, the authorization server will also invalidate all access tokens based on the same authorization grant. If the revoked token is an access token, the server will also revoke the respective refresh token.

#Path

oxauth/restv1/revoke

#revoke

POST

oxauth/restv1/revoke

Client introspects OAuth 2 token.

URL

http://sample.com/oxauth/restv1/revoke

Parameters

• token - REQUIRED - The token that the client wants to get revoked
• token_type_hint - OPTIONAL - A hint about the type of the token submitted for revocation. Passing this parameter can help the authorization server optimize the token lookup. May be one of the following:
  • access_token
  • refresh_token

Response

Sample Request

POST /restv1/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: ce.gluu.info
Authorization: Basic JTQwJTIxOTBDQy4yRTM4Ljc3NEMuNjEwQiUyMTAwMDElMjFGRDNCLkIwQTAlMjEwMDA4JTIxMjc5MC40NzIwLjU3NUQuQTRBRjpjNzJiMjNiZC1lMjQ5LTRkZTktODBlMS02YTk1NGY1MTBiOGM=
token=0e175b7e-3ee8-4981-b32d-427f11f3d0d9&token_type_hint=access_token

Sample Response

HTTP/1.1 200
Cache-Control: no-store
Content-Length: 0
Pragma: no-cache

Errors

#ID Generation API

This section will discuss a few APIs used in the Gluu Server for ID generation.

#Path

/restv1/id

#Overview

The API convention is set as id followed by prefix and type or /id/{prefix}/{type}/. Please see the following table to specify what type you are generating. The prefix is used in the inum to make it possible to know the type of object just by looking at the identifier.

generateJsonInum
GET/id/{prefix}/{type}/

Generates ID for given prefix and type.

URL
http://gluu.org/id/{prefix}/{type}/

Parameters

• path

• header

|Parameter|Required|Description|Data Type| |Authorization|false||string|

Response
String[Response]

**generateHtmlInum GET/id/{prefix}/{type}/

Generates ID for given prefix and type.

URL
http://gluu.org/id/{prefix}/{type}/ Parameters

• path

• header

Response
String[Response] Errors

generateTextInum
GET/id/{prefix}/{type}/

Generates ID for given prefix and type.

URL
http://gluu.org/id/{prefix}/{type}/ Parameters

• path

• header

Response
String[Response]

Errors
generateXmlInum
GET/id/{prefix}/{type}/

Generates ID for given prefix and type.

URL
http://gluu.org/id/{prefix}/{type}/ Parameters

• path

• header

Response
String[Response]

Errors

generateHtmlInum
GET/id/{prefix}/{type}/

Generates ID for given prefix and type.

URL
http://gluu.org/id/{prefix}/{type}/ Parameters

• path

• header

Response
String[Response]

Errors

#Session Revocation Endpoint

Swagger description can be found here.