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 obtain the authorisation for a submitted access token. May also be used by clients to query a refresh token.

The protected resource may be required to authenticate itself to the token introspection endpoint with a standard client authentication method, such as client_secret_basic, or with a dedicated access token.

Example token introspection request, where the protected resource authenticates itself 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 authenticates itself with 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 uri, Token token)
      Creates a new token introspection request. The request submitter is not authenticated.
      Parameters:
      uri - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method will not be used.
      token - The access or refresh token to introspect. Must not be null.

    • TokenIntrospectionRequest

      public TokenIntrospectionRequest(URI uri, Token token, Map<String,List<String>> customParams)
      Creates a new token introspection request. The request submitter is not authenticated.
      Parameters:
      uri - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method will not 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 uri, ClientAuthentication clientAuth, Token token)
      Creates a new token introspection request. The request submitter may authenticate with a secret or private key JWT assertion.
      Parameters:
      uri - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method will not 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 uri, ClientAuthentication clientAuth, Token token, Map<String,List<String>> customParams)
      Creates a new token introspection request. The request submitter may authenticate with a secret or private key JWT assertion.
      Parameters:
      uri - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method will not 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 uri, AccessToken clientAuthz, Token token)
      Creates a new token introspection request. The request submitter may authorise itself with an access token.
      Parameters:
      uri - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method will not 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 uri, AccessToken clientAuthz, Token token, Map<String,List<String>> customParams)
      Creates a new token introspection request. The request submitter may authorise itself with an access token.
      Parameters:
      uri - The URI of the token introspection endpoint. May be null if the toHTTPRequest() method will not 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.