Package com.authlete.common.dto

Class GMResponse

  • All Implemented Interfaces:
    Serializable
    public class GMResponse
extends ApiResponse
    Response from Authlete's /api/gm API.

    Authlete's /api/gm API returns JSON which can be mapped to this class. The implementation of the grant management endpoint should retrieve the value of "action" from the response and take the following steps according to the value.

    OK

    When the value of "action" is "OK", it means that the access token which the client application presented is valid and information about the grant has been retrieved successfully. In this case, the implementation of the endpoint should return an HTTP response with the status code 200 OK and the content type application/json to the client application.

    getResponseContent() returns a response in JSON format when "action" is "OK", so a response to the client application can be built like below. 

     HTTP/1.1 200 OK
 Cache-Control: no-store
 Pragma: no-cache
 Content-Type: application/json

 (The value returned from getResponseContent())
    NO_CONTENT

    When the value of "action" is "NO_CONTENT", it means that the access token which the client application presented is valid and the grant was revoked successfully. In this case, the implementation of the endpoint should return an HTTP response with the status code 204 No Content to the client application.

    UNAUTHORIZED

    When the value of "action" is "UNAUTHORIZED", it means that the grant management request includes no access token or the access token is invalid. In this case, the implementation of the endpoint should return an HTTP response with the status code 401 Unauthorized.

    The specification does not describe details about error response format, but in error cases, getResponseContent() returns information about the error in the format suitable as a value for the WWW-Authenticate HTTP header. The implementation of the endpoint may use the string when building an error response. The following is an example. 

     HTTP/1.1 401 Unauthorized
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
    FORBIDDEN

    When the value of "action" is "FORBIDDEN", it means that the access token cannot be used to manage the grant ID. In this case, the implementation of the endpoint should return an HTTP response with the status code 403 Forbidden. The error response can be built like below in the same way for the case of UNAUTHORIZED. 

     HTTP/1.1 403 Forbidden
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
    NOT_FOUND

    When the value of "action" is "NOT_FOUND", it means that the grant ID was not found. In this case, the implementation of the endpoint should return an HTTP response with the status code 404 Not Found. The error response can be built like below in the same way for the case of UNAUTHORIZED. 

     HTTP/1.1 404 Not Found
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
    CALL_ERROR

    When the value of "action" is "CALLER_ERROR", it means that the API call is wrong. For example, the gmAction request parameter, which is mandatory, is missing. The implementation of the endpoint should be fixed. In this case, it's up to the implementation how to respond to the client application. A simple implementation would return an HTTP response with the status code 500 Internal Server Error like below. 

     HTTP/1.1 500 Internal Server Error
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
    AUTHLETE_ERROR

    When the value of "action" is "AUTHLETE_ERROR", it means that an error occurred on Authlete side. In this case, it's up to the implementation how to respond to the client application. A simple implementation would return an HTTP response with the status code 500 Internal Server Error like below. 

     HTTP/1.1 500 Internal Server Error
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache

    DPoP Nonce (Authlete 3.0 onwards)

    Since version 3.0, Authlete recognizes the nonce claim in DPoP proof JWTs. If the presented access token is bound to a public key through the DPoP mechanism, and if the nonce claim is required (= if the service's dpopNonceRequired property is true, or the value of the dpopNonceRequired request parameter passed to the Authlete API is true), the Authlete API checks whether the nonce claim in the presented DPoP proof JWT is identical to the expected value.

    If the dpopNonce response parameter from the API is not null, its value is the expected nonce value for DPoP proof JWT. The expected value needs to be conveyed to the client application as the value of the DPoP-Nonce HTTP header. 

    DPoP-Nonce: (The value returned from getDpopNonce())

    See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    Since:
    3.1, Authlete 2.3.0
    See Also:
    Grant Management for OAuth 2.0, Serialized Form

    • Constructor Detail

      • GMResponse

        public GMResponse()

    • Method Detail

      • getAction

        public GMResponse.Action getAction()
        Get the next action that the authorization server should take.
        Returns:
        The next action that the authorization server should take.

      • setAction

        public GMResponse setAction​(GMResponse.Action action)
        Set the next action that the authorization server should take.
        Parameters:
        action - The next action that the authorization server should take.
        Returns:
        this object.

      • getResponseContent

        public String getResponseContent()
        Get the response content which can be used to build a response to the client application.
        Returns:
        The content of the response to the client application.

      • setResponseContent

        public GMResponse setResponseContent​(String content)
        Set the response content which can be used to build a response to the client application.
        Parameters:
        content - The content of the response to the client application.
        Returns:
        this object.

      • getDpopNonce

        public String getDpopNonce()
        Get the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the grant management endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Returns:
        The expected nonce value for DPoP proof JWT.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

      • setDpopNonce

        public GMResponse setDpopNonce​(String dpopNonce)
        Set the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the grant management endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Parameters:
        dpopNonce - The expected nonce value for DPoP proof JWT.
        Returns:
        this object.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)