java.lang.Object
- com.authlete.common.dto.IntrospectionRequest

All Implemented Interfaces:

Serializable
```
public class IntrospectionRequest
extends Object
implements Serializable
```
Request to Authlete's /auth/introspection API.

token (REQUIRED)

An access token to introspect.

scopes (OPTIONAL)

Scopes that should be covered by the access token.

subject (OPTIONAL)

The subject that should be associated with the access token.

clientCertificate (OPTIONAL)

The client certificate used in the mutual TLS connection established between the client application and the protected resource endpoint. See RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens for details.

dpop (OPTIONAL)

The value of the DPoP HTTP header. See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

htm (OPTIONAL)

The HTTP method of the request to the protected resource endpoint. See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

htu (OPTIONAL)

The URL of the protected resource endpoint. See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

resources (OPTIONAL)

Resource indicators that should be covered by the access token. See RFC 8707 Resource Indicators for OAuth 2.0 for details.

uri (OPTIONAL; Authlete 2.3 onwards)

The full URL of the resource server.

headers (OPTIONAL; Authlete 2.3 onwards)

The HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature.

message (OPTIONAL; Authlete 2.3 onwards)

The HTTP message body of the request, if present. If supplied, this is used to validate the value of the Content-Digest header, which must in turn be covered in the HTTP Message Signature.

requiredComponents (OPTIONAL; Authlete 2.3 onwards)

The list of component identifiers required to be covered by the signature on this message. If this is omitted, the set defaults to including the @method and @target-uri derived components as well as all headers in the getHeaders() array.

acrValues (OPTIONAL; Authlete 2.3 onwards)

The list of Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy.

maxAge (OPTIONAL; Authlete 2.3 onwards)

The maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token.

dpopNonceRequired (OPTIONAL; Authlete 3.0 onwards)

The flag indicating whether to require the DPoP proof JWT to include the nonce claim. Even if the service's dpopNonceRequired property is false, calling the /auth/introspection API with this dpopNonceRequired parameter true will force the Authlete API to check whether the DPoP proof JWT includes the expected nonce value.

Author:

Takahiko Kawasaki

See Also:

RFC 6750 The OAuth 2.0 Authorization Framework: Bearer Token Usage, RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens, RFC 8707 Resource Indicators for OAuth 2.0, RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP), RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol, Serialized Form

Constructor Summary

Constructors
Constructor Description

IntrospectionRequest()

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`String[]`	`getAcrValues()`	Get the list of Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy.
`String`	`getClientCertificate()`	Get the client certificate used in the mutual TLS connection established between the client application and the protected resource endpoint.
`String`	`getDpop()`	Get the `DPoP` header presented by the client during the request to the resource server.
`Pair[]`	`getHeaders()`	Get the HTTP headers to be included in processing the signature.
`String`	`getHtm()`	Get the HTTP method of the request from the client to the protected resource endpoint.
`String`	`getHtu()`	Get the URL of the protected resource endpoint.
`int`	`getMaxAge()`	Get the maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token.
`String`	`getMessage()`	Get the HTTP message body, if present.
`String[]`	`getRequiredComponents()`	Get the list of component identifiers required to be covered by the signature on this message.
`URI[]`	`getResources()`	Get the resource indicators that the access token should cover.
`String[]`	`getScopes()`	Get the scopes which are required to access the protected resource endpoint.
`String`	`getSubject()`	Get the subject (= end-user ID managed by the service implementation) which is required to access the protected resource endpoint.
`String`	`getToken()`	Get the access token to introspect.
`String`	`getUri()`	Get the URL of the resource server.
`boolean`	`isDpopNonceRequired()`	Get the flag indicating whether to check if the DPoP proof JWT includes the expected `nonce` value.
`IntrospectionRequest`	`setAcrValues(String[] acrValues)`	Set the list of Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy.
`IntrospectionRequest`	`setClientCertificate(String clientCertificate)`	Set the client certificate used in the mutual TLS connection established between the client application and the protected resource endpoint.
`IntrospectionRequest`	`setDpop(String dpop)`	Set the `DPoP` header presented by the client during the request to the resource server.
`IntrospectionRequest`	`setDpopNonceRequired(boolean required)`	Set the flag indicating whether to check if the DPoP proof JWT includes the expected `nonce` value.
`IntrospectionRequest`	`setHeaders(Pair[] headers)`	Set the HTTP headers to be included in processing the signature.
`IntrospectionRequest`	`setHtm(String htm)`	Set the HTTP method of the request from the client to the protected resource endpoint.
`IntrospectionRequest`	`setHtu(String htu)`	Set the URL of the protected resource endpoint.
`IntrospectionRequest`	`setMaxAge(int maxAge)`	Set the maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token.
`IntrospectionRequest`	`setMessage(String message)`	Set the HTTP message body, if present.
`IntrospectionRequest`	`setRequiredComponents(String[] requiredComponents)`	Set the list of component identifiers required to be covered by the signature on this message.
`IntrospectionRequest`	`setResources(URI[] resources)`	Set the resource indicators that the access token should cover.
`IntrospectionRequest`	`setScopes(String[] scopes)`	Set the scopes which are required to access the protected resource endpoint.
`IntrospectionRequest`	`setSubject(String subject)`	Set the subject (= end-user ID managed by the service implementation) which is required to access the protected resource endpoint.
`IntrospectionRequest`	`setToken(String token)`	Set the access token to introspect.
`IntrospectionRequest`	`setUri(String uri)`	Set the URL of the resource server.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - IntrospectionRequest
```
public IntrospectionRequest()
```
- Method Detail
  - getToken
```
public String getToken()
```
    Get the access token to introspect.
    
    Returns:
    
    The access token.
  - setToken
```
public IntrospectionRequest setToken(String token)
```
    Set the access token to introspect.
    
    Parameters:
    
    token - The access token.
    
    Returns:
    
    this object.
  - getScopes
```
public String[] getScopes()
```
    Get the scopes which are required to access the protected resource endpoint.
    
    Returns:
    
    Required scopes.
  - setScopes
```
public IntrospectionRequest setScopes(String[] scopes)
```
    Set the scopes which are required to access the protected resource endpoint.
    If the array contains a scope which is not covered by the access token, Authlete's /auth/introspection API returns FORBIDDEN as the action and insufficent_scope as the error code.
    
    Parameters:
    
    scopes - Scopes required to access the protected resource endpoint. If null is given, the /auth/introspection API does not perform scope checking.
    
    Returns:
    
    this object.
  - getSubject
```
public String getSubject()
```
    Get the subject (= end-user ID managed by the service implementation) which is required to access the protected resource endpoint.
    
    Returns:
    
    Expected identifier of resource owner.
  - setSubject
```
public IntrospectionRequest setSubject(String subject)
```
    Set the subject (= end-user ID managed by the service implementation) which is required to access the protected resource endpoint.
    If the specified subject is different from the one associated with the access token, Authlete's /auth/introspection API returns FORBIDDEN as the action and invalid_request as the error code.
    
    Parameters:
    
    subject - Subject (= end-user ID managed by the service implementation) which is required to access the protected resource endpoint. If null is given, the /auth/introspection API does not perform subject checking.
    
    Returns:
    
    this object.
  - getClientCertificate
```
public String getClientCertificate()
```
    Get the client certificate used in the mutual TLS connection established between the client application and the protected resource endpoint.
    
    Returns:
    
    The client certificate in PEM format.
    
    Since:
    
    2.14
    
    See Also:
    
    RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens
  - setClientCertificate
```
public IntrospectionRequest setClientCertificate(String clientCertificate)
```
    Set the client certificate used in the mutual TLS connection established between the client application and the protected resource endpoint.
    If the access token is bound to a client certificate, this parameter is used for validation.
    
    Parameters:
    
    clientCertificate - The client certificate in PEM format.
    
    Returns:
    
    this object.
    
    Since:
    
    2.14
    
    See Also:
    
    RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens
  - getDpop
```
public String getDpop()
```
    Get the DPoP header presented by the client during the request to the resource server. This header contains a signed JWT which includes the public key that is paired with the private key used to sign it.
    
    Returns:
    
    The DPoP header string.
    
    Since:
    
    2.70
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
  - setDpop
```
public IntrospectionRequest setDpop(String dpop)
```
    Set the DPoP header presented by the client during the request to the resource server. This header contains a signed JWT which includes the public key that is paired with the private key used to sign it.
    If the access token is bound to a public key via DPoP, this parameter is used for validation.
    
    Parameters:
    
    dpop - The DPoP header string.
    
    Returns:
    
    this object.
    
    Since:
    
    2.70
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
  - getHtm
```
public String getHtm()
```
    Get the HTTP method of the request from the client to the protected resource endpoint. This field is used to validate the DPoP header.
    
    Returns:
    
    The HTTP method as a string. For example, "GET".
    
    Since:
    
    2.70
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
  - setHtm
```
public IntrospectionRequest setHtm(String htm)
```
    Set the HTTP method of the request from the client to the protected resource endpoint. This field is used to validate the DPoP header.
    If the access token is bound to a public key via DPoP, this parameter is used for validation.
    
    Parameters:
    
    htm - The HTTP method as a string. For example, "GET".
    
    Returns:
    
    this object.
    
    Since:
    
    2.70
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
  - getHtu
```
public String getHtu()
```
    Get the URL of the protected resource endpoint. This field is used to validate the DPoP header.
    
    Returns:
    
    The URL of the protected resource endpoint.
    
    Since:
    
    2.70
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
  - setHtu
```
public IntrospectionRequest setHtu(String htu)
```
    Set the URL of the protected resource endpoint. This field is used to validate the DPoP header.
    If the access token is bound to a public key via DPoP, this parameter is used for validation.
    
    Parameters:
    
    htu - The URL of the protected resource endpoint.
    
    Returns:
    
    this object.
    
    Since:
    
    2.70
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
  - getResources
```
public URI[] getResources()
```
    Get the resource indicators that the access token should cover.
    
    Returns:
    
    The resource indicators.
    
    Since:
    
    3.1
    
    See Also:
    
    RFC 8707 Resource Indicators for OAuth 2.0
  - setResources
```
public IntrospectionRequest setResources(URI[] resources)
```
    Set the resource indicators that the access token should cover.
    
    Parameters:
    
    resources - The resource indicators that the access token should cover to access the protected resource endpoint. If null is given, the /auth/introspection API does not perform resource indicator checking.
    
    Returns:
    
    this object.
    
    Since:
    
    3.3
    
    See Also:
    
    RFC 8707 Resource Indicators for OAuth 2.0
  - getUri
```
public String getUri()
```
    Get the URL of the resource server. This field is used to validate the HTTP Message Signature.
    
    Returns:
    
    The URL of the resource server.
    
    Since:
    
    3.38, Authlete 2.3
  - setUri
```
public IntrospectionRequest setUri(String uri)
```
    Set the URL of the resource server. This field is used to validate the HTTP Message Signature.
    
    Parameters:
    
    uri - The URL of the resource server.
    
    Returns:
    
    this object.
    
    Since:
    
    3.38, Authlete 2.3
  - getMessage
```
public String getMessage()
```
    Get the HTTP message body, if present. If provided, this will be used to calculate the expected value of the Content-Digest in the headers of the request covered by the HTTP Message Signature.
    
    Returns:
    
    The HTTP message body.
    
    Since:
    
    3.38, Authlete 2.3
  - setMessage
```
public IntrospectionRequest setMessage(String message)
```
    Set the HTTP message body, if present. If provided, this will be used to calculate the expected value of the Content-Digest in the headers of the request covered by the HTTP Message Signature.
    
    Parameters:
    
    message - The HTTP message body.
    
    Returns:
    
    this object.
    
    Since:
    
    3.38, Authlete 2.3
  - getHeaders
```
public Pair[] getHeaders()
```
    Get the HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature.
    
    Returns:
    
    The HTTP headers.
    
    Since:
    
    3.38, Authlete 2.3
  - setHeaders
```
public IntrospectionRequest setHeaders(Pair[] headers)
```
    Set the HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature.
    
    Parameters:
    
    headers - The HTTP headers.
    
    Returns:
    
    this object.
    
    Since:
    
    3.38, Authlete 2.3
  - getRequiredComponents
```
public String[] getRequiredComponents()
```
    Get the list of component identifiers required to be covered by the signature on this message. If this is omitted, the set defaults to including the @method and @target-uri derived components as well the Authorization header and, if present, the DPoP header.
    
    Returns:
    
    The component identifiers to cover in the signature.
    
    Since:
    
    3.38, Authlete 2.3
  - setRequiredComponents
```
public IntrospectionRequest setRequiredComponents(String[] requiredComponents)
```
    Set the list of component identifiers required to be covered by the signature on this message. If this is omitted, the set defaults to including the @method and @target-uri derived components as well the Authorization header and, if present, the DPoP header.
    
    Parameters:
    
    requiredComponents - The component identifiers to cover in the signature.
    
    Returns:
    
    this object.
    
    Since:
    
    3.38, Authlete 2.3
  - getAcrValues
```
public String[] getAcrValues()
```
    Get the list of Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy.
    
    Returns:
    
    The list of Authentication Context Class Reference values.
    
    Since:
    
    3.40, Authlete 2.3
    
    See Also:
    
    RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
  - setAcrValues
```
public IntrospectionRequest setAcrValues(String[] acrValues)
```
    Set the list of Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy.
    
    Parameters:
    
    acrValues - The list of Authentication Context Class Reference values. If null is given, the /auth/introspection API does not perform ACR checking.
    
    Returns:
    
    this object.
    
    Since:
    
    3.40, Authlete 2.3
    
    See Also:
    
    RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
  - getMaxAge
```
public int getMaxAge()
```
    Get the maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token.
    
    Returns:
    
    The maximum authentication age in seconds.
    
    Since:
    
    3.40, Authlete 2.3
    
    See Also:
    
    RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
  - setMaxAge
```
public IntrospectionRequest setMaxAge(int maxAge)
```
    Set the maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token.
    
    Parameters:
    
    maxAge - The maximum authentication age in seconds. If 0 or a negative value is given, the /auth/introspection API does not perform max age checking.
    
    Returns:
    
    this object.
    
    Since:
    
    3.40, Authlete 2.3
    
    See Also:
    
    RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol
  - isDpopNonceRequired
```
public boolean isDpopNonceRequired()
```
    Get the flag indicating whether to check if the DPoP proof JWT includes the expected nonce value.
    If this request parameter is true or if the service's dpopNonceRequired property (Service.isDpopNonceRequired()) is true, the /auth/introspection API checks if the DPoP proof JWT includes the expected nonce value. In this case, the response from the /auth/introspection API will include the dpopNonce response parameter, which should be used as the value of the DPoP-Nonce HTTP header.
    
    Returns:
    
    true if the /auth/introspection API checks whether the DPoP proof JWT includes the expected nonce value, even if the service's dpopNonceRequired property is false.
    
    Since:
    
    3.82, Authlete 3.0
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
  - setDpopNonceRequired
```
public IntrospectionRequest setDpopNonceRequired(boolean required)
```
    Set the flag indicating whether to check if the DPoP proof JWT includes the expected nonce value.
    If this request parameter is true or if the service's dpopNonceRequired property (Service.isDpopNonceRequired()) is true, the /auth/introspection API checks if the DPoP proof JWT includes the expected nonce value. In this case, the response from the /auth/introspection API will include the dpopNonce response parameter, which should be used as the value of the DPoP-Nonce HTTP header.
    
    Parameters:
    
    required - true to have the /auth/introspection API check whether the DPoP proof JWT includes the expected nonce value, even if the service's dpopNonceRequired property is false.
    
    Returns:
    
    this object.
    
    Since:
    
    3.82, Authlete 3.0
    
    See Also:
    
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

Class IntrospectionRequest

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

IntrospectionRequest

Method Detail

getToken

setToken

getScopes

setScopes

getSubject

setSubject

getClientCertificate

setClientCertificate

getDpop

setDpop

getHtm

setHtm

getHtu

setHtu

getResources

setResources

getUri

setUri

getMessage

setMessage

getHeaders

setHeaders

getRequiredComponents

setRequiredComponents

getAcrValues

setAcrValues

getMaxAge

setMaxAge

isDpopNonceRequired

setDpopNonceRequired