Package com.nimbusds.oauth2.sdk

Class TokenIntrospectionRequest

java.lang.Object
com.nimbusds.oauth2.sdk.AbstractRequest
com.nimbusds.oauth2.sdk.AbstractOptionallyAuthenticatedRequest
com.nimbusds.oauth2.sdk.TokenIntrospectionRequest
All Implemented Interfaces:
Message, Request
@Immutable public class TokenIntrospectionRequest extends AbstractOptionallyAuthenticatedRequest
Token introspection request. Used by a protected resource to get the authorisation for a received access token. May also be used by clients to get the authorisation for a refresh token.

The caller may be required to authenticate itself with a client authentication method, such as client_secret_basic, or to present a dedicated access token.

Example token introspection request, where the protected resource authenticates with a secret (the token type is also hinted): 

 POST /introspect HTTP/1.1
 Host: server.example.com
 Accept: application/json
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

 token=mF_9.B5f-4.1JqM&token_type_hint=access_token

Example token introspection request, where the protected resource presents a bearer token: 

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

 token=2YotnFZFEjr1zCsicMWpAA

Related specifications:

  • OAuth 2.0 Token Introspection (RFC 7662)

  • Constructor Details

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI endpoint, Token token)
      Creates a new token introspection request.
      Parameters:
      endpoint - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method is not going to be used.
      token - The access or refresh token to introspect. Must not be null.

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI endpoint, Token token, Map<String,List<String>> customParams)
      Creates a new token introspection request.
      Parameters:
      endpoint - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method is not going to be used.
      token - The access or refresh token to introspect. Must not be null.
      customParams - Optional custom parameters, null if none.

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI endpoint, ClientAuthentication clientAuth, Token token)
      Creates a new token introspection request, including a client authentication for the caller.
      Parameters:
      endpoint - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method is not going to be used.
      clientAuth - The client authentication, null if none.
      token - The access or refresh token to introspect. Must not be null.

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI endpoint, ClientAuthentication clientAuth, Token token, Map<String,List<String>> customParams)
      Creates a new token introspection request, including a client authentication for the caller.
      Parameters:
      endpoint - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method is not going to be used.
      clientAuth - The client authentication, null if none.
      token - The access or refresh token to introspect. Must not be null.
      customParams - Optional custom parameters, null if none.

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI endpoint, List<ClientAuthentication> clientAuthCandidates, Token token, Map<String,List<String>> customParams)
      Creates a new token introspection request, including client authentication candidates for the caller.
      Parameters:
      endpoint - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method is not going to be used.
      clientAuthCandidates - The client authentication candidates. Must not be null.
      token - The access or refresh token to introspect. Must not be null.
      customParams - Optional custom parameters, null if none.

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI endpoint, AccessToken clientAuthz, Token token)
      Creates a new token introspection request, including an access token to authorise the caller.
      Parameters:
      endpoint - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method is not going to be used.
      clientAuthz - The client authorisation, null if none.
      token - The access or refresh token to introspect. Must not be null.

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI endpoint, AccessToken clientAuthz, Token token, Map<String,List<String>> customParams)
      Creates a new token introspection request, including an access token to authorise the caller.
      Parameters:
      endpoint - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method is not going to be used.
      clientAuthz - The client authorisation, null if none.
      token - The access or refresh token to introspect. Must not be null.
      customParams - Optional custom parameters, null if none.

  • Method Details

    • getClientAuthorization

      public AccessToken getClientAuthorization()
      Returns the client authorisation.
      Returns:
      The client authorisation as an access token, null if none.

    • getToken

      public Token getToken()
      Returns the token to introspect. The instanceof operator can be used to infer the token type. If it's neither AccessToken nor RefreshToken the token_type_hint has not been provided as part of the token revocation request.
      Returns:
      The token.

    • getCustomParameters

      public Map<String,List<String>> getCustomParameters()
      Returns the custom request parameters.
      Returns:
      The custom request parameters, empty map if none.

    • toHTTPRequest

      public HTTPRequest toHTTPRequest()
      Description copied from interface: Request
      Returns the matching HTTP request.
      Returns:
      The HTTP request.

    • parse

      public static TokenIntrospectionRequest parse(HTTPRequest httpRequest) throws ParseException
      Parses a token introspection request from the specified HTTP request.
      Parameters:
      httpRequest - The HTTP request. Must not be null.
      Returns:
      The token introspection request.
      Throws:
      ParseException - If the HTTP request couldn't be parsed to a token introspection request.