Package com.authlete.common.dto

Class StandardIntrospectionResponse

  • All Implemented Interfaces:
    Serializable
    public class StandardIntrospectionResponse
extends ApiResponse
    Response from Authlete's /api/auth/introspection/standard API. Note that the API and /api/auth/introspection API are different. /api/auth/introspection/standard API exists to help your authorization server provide its own introspection API which complies with RFC 7662 (OAuth 2.0 Token Introspection).

    Authlete's /api/auth/introspection/standard API returns JSON which can be mapped to this class. The implementation of the introspection endpoint of your authorization server should retrieve the value of "action" from the response and take the following steps according to the value.

    INTERNAL_SERVER_ERROR

    When the value of "action" is "INTERNAL_SERVER_ERROR", it means that the request from your system to Authlete (StandardIntrospectionRequest) was wrong or that an error occurred in Authlete.

    In either case, from the viewpoint of the resource server, it is an error on the server side. Therefore, the introspection endpoint of your authorization server should generate a response to the resource server with the HTTP status of "500 Internal Server Error".

    getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, RFC 7662 does not mention anything about the response body of error responses.

    The following illustrates an example response which the introspection endpoint of your authorization server generates and returns to the resource server. 

     HTTP/1.1 500 Internal Server Error
 Content-Type: application/json

 (The value returned from getResponseContent())
    BAD_REQUEST

    When the value of "action" is "BAD_REQUEST", it means that the request from the resource server is invalid. This happens when the request from the resource server did not include the token request parameter. See "2.1. Introspection Request" in RFC 7662 for details about requirements for introspection requests.

    The HTTP status of the response returned to the resource server should be "400 Bad Request".

    getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, RFC 7662 does not mention anything about the response body of error responses.

    The following illustrates an example response which the introspection endpoint of your authorization server generates and returns to the resource server. 

     HTTP/1.1 400 Bad Request
 Content-Type: application/json

 (The value returned from getResponseContent())
    OK

    When the value of "action" is "OK", it means that the request from the resource server is valid.

    The HTTP status of the response returned to the resource server must be "200 OK" and its content type must be "application/json".

    getResponseContent() returns a JSON string which complies with the introspection response defined in "2.2. Introspection Response" in RFC7662.

    The following illustrates the response which the introspection endpoint of your authorization server should generate and return to the resource server. 

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

 (The value returned from getResponseContent())
    JWT

    When the value of "action" is "JWT", it means that the request from the resource server is valid and a JWT is returned to the resource server as the introspection response.

    The HTTP status of the response returned to the resource server must be "200 OK" and its content type must be "application/token-introspection+jwt".

    getResponseContent() returns a JWT which complies with the introspection response defined in "JWT Response for OAuth Token Introspection".

    The following illustrates the response which the introspection endpoint of your authorization server should generate and return to the resource server. 

     HTTP/1.1 200 OK
 Content-Type: application/token-introspection+jwt

 (The value returned from getResponseContent())

    Note that RFC 7662 says "To prevent token scanning attacks, the endpoint MUST also require some form of authorization to access this endpoint". This means that you have to protect your introspection endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected. In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection request does not satisfy authorization requirements imposed by your introspection endpoint.

    Since:
    2.7, Authlete 1.1.7
    Author:
    Takahiko Kawasaki, Hideki Ikeda
    See Also:
    RFC 7662, OAuth 2.0 Token Introspection, JWT Response for OAuth Token Introspection, StandardIntrospectionRequest, AuthleteApi.standardIntrospection(StandardIntrospectionRequest), Serialized Form

    • Constructor Detail

      • StandardIntrospectionResponse

        public StandardIntrospectionResponse()

    • Method Detail

      • getResponseContent

        public String getResponseContent()
        Get the response content which can be used as the entity body of the response returned to the resource server.

      • setResponseContent

        public StandardIntrospectionResponse setResponseContent​(String responseContent)
        Set the response content which can be used as the entity body of the response returned to the resource server.

      • summarize

        public String summarize()
        Get the summary of this instance.