IntrospectionResponse (com.authlete:authlete-java-common 2.51 API)

java.lang.Object
- com.authlete.common.dto.ApiResponse
- - com.authlete.common.dto.IntrospectionResponse

All Implemented Interfaces:

Serializable
```
public class IntrospectionResponse
extends ApiResponse
```
Response from Authlete's /auth/introspection API.
Authlete's /auth/introspection API returns JSON which can be mapped to this class. The service implementation 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 the service implementation was wrong or that an error occurred in Authlete.

In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with the HTTP status of "500 Internal Server Error".

getResponseContent() returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() can be used as the value of WWW-Authenticate.

The following is an example response which complies with RFC 6750.
```
 HTTP/1.1 500 Internal Server Error
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
```
BAD_REQUEST
When the value of "action" is "BAD_REQUEST", it means that the request from the client application does not contain an access token (= the request from the service implementation to Authlete does not contain "token" parameter).

getResponseContent() returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() can be used as the value of WWW-Authenticate.

The following is an example response which complies with RFC 6750.
```
 HTTP/1.1 400 Bad Request
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
```
UNAUTHORIZED
When the value of "action" is "UNAUTHORIZED", it means that the access token does not exist or has expired. Or the client application associated with the access token does not exist any longer.

getResponseContent() returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() can be used as the value of WWW-Authenticate.

The following is an example response which complies with RFC 6750.
```
 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 does not cover the required scopes or that the subject associated with the access token is different from the subject contained in the request.

getResponseContent() returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() can be used as the value of WWW-Authenticate.

The following is an example response which complies with RFC 6750.
```
 HTTP/1.1 403 Forbidden
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
```
OK
When the value of "action" is "OK", it means that the access token which the client application presented is valid (= exists and has not expired).

The service implementation is supposed to return the protected resource to the client application.

When "action" is "OK", getResponseContent() returns "Bearer error=\"invalid_request\"". This is the simplest string which can be used as the value of WWW-Authenticate header to indicate "400 Bad Request". The service implementation may use this string to tell the client application that the request was bad. But in such a case, the service should generate a more informative error message to help developers of client applications.

The following is an example error response which complies with RFC 6750.
```
 HTTP/1.1 400 Bad Request
 WWW-Authenticate: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache
```
Basically, getResponseContent() returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage). So, if the service has selected "Bearer" as the token type, the string returned from getResponseContent() can be used directly as the value for WWW-Authenticate. However, if the service has selected another different token type, the service has to generate error messages for itself.

JWT-based access token

Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature can be enabled by setting a non-null value to the accessTokenSignAlg property of the service (see the description of the Service class for details). /api/auth/introspection API can accept access tokens in JWT format. However, note that the API does not return information contained in a given JWT-based access token but returns information stored in the database record which corresponds to the given JWT-based access token. Because attributes of the database record can be modified after the access token is issued (for example, by using /api/auth/token/update API), information returned by /api/auth/introspection API and information the given JWT-based access token holds may be different.
Author:

Takahiko Kawasaki

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class IntrospectionResponse.Action
The next action the service implementation should take.

Nested Classes
Modifier and Type	Class and Description
`static class`	`IntrospectionResponse.Action` The next action the service implementation should take.

Constructor Summary

Constructors
Constructor and Description

IntrospectionResponse()

Constructors
Constructor and Description
`IntrospectionResponse()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`IntrospectionResponse.Action`	`getAction()` Get the next action the service implementation should take.
`String`	`getCertificateThumbprint()` Get the client certificate thumbprint used to validate the access token.
`long`	`getClientId()` Get the client ID.
`String`	`getClientIdAlias()` Get the client ID alias when the authorization request or the token request for the access token was made.
`long`	`getExpiresAt()` Get the time at which the access token expires in milliseconds since the Unix epoch (1970-01-01).
`Property[]`	`getProperties()` Get the extra properties associated with the access token.
`String`	`getResponseContent()` Get the response content which can be used as a part of the response to the client application.
`String[]`	`getScopes()` Get the scopes covered by the access token.
`String`	`getSubject()` Get the subject (= resource owner's ID).
`boolean`	`isClientIdAliasUsed()` Get the flag which indicates whether the client ID alias was used when the authorization request or the token request for the access token was made.
`boolean`	`isExistent()` Get the flag which indicates whether the access token exists.
`boolean`	`isRefreshable()` Get the flag which indicates whether the access token can be refreshed using the associated refresh token.
`boolean`	`isSufficient()` Get the flag which indicates whether the access token covers the required scopes.
`boolean`	`isUsable()` Get the flag which indicates whether the access token is usable (= exists and has not expired).
`void`	`setAction(IntrospectionResponse.Action action)` Set the next action the service implementation should take.
`void`	`setCertificateThumbprint(String thumbprint)` Set the client certificate thumbprint used to validate the access token.
`void`	`setClientId(long clientId)` Set the client ID.
`void`	`setClientIdAlias(String alias)` Set the client ID alias when the authorization request or the token request for the access token was made.
`void`	`setClientIdAliasUsed(boolean used)` Set the flag which indicates whether the client ID alias was used when the authorization request or the token request for the access token was made.
`void`	`setExistent(boolean existent)` Set the flag which indicates whether the access token exists.
`void`	`setExpiresAt(long expiresAt)` Set the time at which the access token expires in milliseconds since the Unix epoch (1970-01-01).
`void`	`setProperties(Property[] properties)` Set the extra properties associated with the access token.
`void`	`setRefreshable(boolean refreshable)` Set the flag which indicates whether the access token can be refreshed using the associated refresh token.
`void`	`setResponseContent(String responseContent)` Set the response content which can be used as a part of the response to the client application.
`void`	`setScopes(String[] scopes)` Set the scopes covered by the access token.
`void`	`setSubject(String subject)` Set the subject (= resource owner's ID).
`void`	`setSufficient(boolean sufficient)` Set the flag which indicates whether the access token covers the required scopes.
`void`	`setUsable(boolean usable)` Set the flag which indicates whether the access token is usable (= exists and has not expired).
`String`	`summarize()` Get the summary of this instance.

Methods inherited from class com.authlete.common.dto.ApiResponse
getResultCode, getResultMessage, setResultCode, setResultMessage

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

- Constructor Detail
  - IntrospectionResponse
```
public IntrospectionResponse()
```
- Method Detail
  - getAction
```
public IntrospectionResponse.Action getAction()
```
    Get the next action the service implementation should take.
  - setAction
```
public void setAction(IntrospectionResponse.Action action)
```
    Set the next action the service implementation should take.
  - getClientId
```
public long getClientId()
```
    Get the client ID.
  - setClientId
```
public void setClientId(long clientId)
```
    Set the client ID.
  - getSubject
```
public String getSubject()
```
    Get the subject (= resource owner's ID).
    This method returns null if the access token was generated by Client Credentials Grant, which means that the access token is not associated with any specific end-user.
  - setSubject
```
public void setSubject(String subject)
```
    Set the subject (= resource owner's ID).
  - getScopes
```
public String[] getScopes()
```
    Get the scopes covered by the access token.
  - setScopes
```
public void setScopes(String[] scopes)
```
    Set the scopes covered by the access token.
  - isExistent
```
public boolean isExistent()
```
    Get the flag which indicates whether the access token exists.
    
    Returns:
    
    true if the access token exists. false if the access token does not exist.
  - setExistent
```
public void setExistent(boolean existent)
```
    Set the flag which indicates whether the access token exists.
  - isUsable
```
public boolean isUsable()
```
    Get the flag which indicates whether the access token is usable (= exists and has not expired).
    
    Returns:
    
    true if the access token is usable. false if the access token does not exist or has expired.
  - setUsable
```
public void setUsable(boolean usable)
```
    Set the flag which indicates whether the access token is usable (= exists and has not expired).
  - isSufficient
```
public boolean isSufficient()
```
    Get the flag which indicates whether the access token covers the required scopes.
    
    Returns:
    
    true if the access token covers all the required scopes. false if any one of the required scopes is not covered by the access token.
  - setSufficient
```
public void setSufficient(boolean sufficient)
```
    Set the flag which indicates whether the access token covers the required scopes.
  - isRefreshable
```
public boolean isRefreshable()
```
    Get the flag which indicates whether the access token can be refreshed using the associated refresh token.
    
    Returns:
    
    true if the access token can be refreshed using the associated refresh token. false if the refresh token for the access token has expired or the access token has no associated refresh token.
  - setRefreshable
```
public void setRefreshable(boolean refreshable)
```
    Set the flag which indicates whether the access token can be refreshed using the associated refresh token.
  - getResponseContent
```
public String getResponseContent()
```
    Get the response content which can be used as a part of the response to the client application.
  - setResponseContent
```
public void setResponseContent(String responseContent)
```
    Set the response content which can be used as a part of the response to the client application.
  - getExpiresAt
```
public long getExpiresAt()
```
    Get the time at which the access token expires in milliseconds since the Unix epoch (1970-01-01).
    
    Returns:
    
    The time at which the access token expires.
  - setExpiresAt
```
public void setExpiresAt(long expiresAt)
```
    Set the time at which the access token expires in milliseconds since the Unix epoch (1970-01-01).
    
    Parameters:
    
    expiresAt - The time at which the access token expires.
  - getProperties
```
public Property[] getProperties()
```
    Get the extra properties associated with the access token.
    
    Returns:
    
    Extra properties. This method returns null when no extra property is associated with the access token.
    
    Since:
    
    1.30
  - setProperties
```
public void setProperties(Property[] properties)
```
    Set the extra properties associated with the access token.
    
    Parameters:
    
    properties - Extra properties.
    
    Since:
    
    1.30
  - summarize
```
public String summarize()
```
    Get the summary of this instance.
  - getClientIdAlias
```
public String getClientIdAlias()
```
    Get the client ID alias when the authorization request or the token request for the access token was made. Note that this value may be different from the current client ID alias.
    
    Returns:
    
    The client ID alias when the authorization request or the token request for the access token was made.
    
    Since:
    
    2.3
  - setClientIdAlias
```
public void setClientIdAlias(String alias)
```
    Set the client ID alias when the authorization request or the token request for the access token was made.
    
    Parameters:
    
    alias - The client ID alias.
    
    Since:
    
    2.3
  - isClientIdAliasUsed
```
public boolean isClientIdAliasUsed()
```
    Get the flag which indicates whether the client ID alias was used when the authorization request or the token request for the access token was made.
    
    Returns:
    
    true if the client ID alias was used when the authorization request or the token request for the access token was made.
    
    Since:
    
    2.3
  - setClientIdAliasUsed
```
public void setClientIdAliasUsed(boolean used)
```
    Set the flag which indicates whether the client ID alias was used when the authorization request or the token request for the access token was made.
    
    Parameters:
    
    used - true if the client ID alias was used when the authorization request or the token request for the access token was made.
    
    Since:
    
    2.3
  - getCertificateThumbprint
```
public String getCertificateThumbprint()
```
    Get the client certificate thumbprint used to validate the access token.
    
    Returns:
    
    The certificate thumbprint, calculated as the SHA256 hash of the DER-encoded certificate value.
    
    Since:
    
    2.14
  - setCertificateThumbprint
```
public void setCertificateThumbprint(String thumbprint)
```
    Set the client certificate thumbprint used to validate the access token.
    
    Parameters:
    
    thumbprint - The certificate thumbprint, calculated as the SHA256 hash of the DER-encoded certificate value.
    
    Since:
    
    2.14

Class IntrospectionResponse

JWT-based access token

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class com.authlete.common.dto.ApiResponse

Methods inherited from class java.lang.Object

Constructor Detail

IntrospectionResponse

Method Detail

getAction

setAction

getClientId

setClientId

getSubject

setSubject

getScopes

setScopes

isExistent

setExistent

isUsable

setUsable

isSufficient

setSufficient

isRefreshable

setRefreshable

getResponseContent

setResponseContent

getExpiresAt

setExpiresAt

getProperties

setProperties

summarize

getClientIdAlias

setClientIdAlias

isClientIdAliasUsed

setClientIdAliasUsed

getCertificateThumbprint

setCertificateThumbprint