public class IntrospectionResponse extends ApiResponse
/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.
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.
Modifier and Type | Class and Description |
---|---|
static class |
IntrospectionResponse.Action
The next action the service implementation should take.
|
Constructor and Description |
---|
IntrospectionResponse() |
Modifier and Type | Method and Description |
---|---|
URI[] |
getAccessTokenResources()
Get the target resources of the access token.
|
String |
getAcr()
Get the Authentication Context Class Reference of the user authentication
that the authorization server performed during the course of issuing the
access token.
|
IntrospectionResponse.Action |
getAction()
Get the next action the service implementation should take.
|
AuthzDetails |
getAuthorizationDetails()
Get the authorization details.
|
long |
getAuthTime()
Get the time when the user authentication was performed during the course
of issuing the access token.
|
String |
getCertificateThumbprint()
Get the client certificate thumbprint used to validate the access token.
|
Pair[] |
getClientAttributes()
Get the attributes of the client that the access token has been issued to.
|
URI |
getClientEntityId()
Get the entity ID of the client.
|
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.
|
String[] |
getConsentedClaims()
Get the claims that the user has consented for the client application
to know.
|
long |
getExpiresAt()
Get the time at which the access token expires in milliseconds
since the Unix epoch (1970-01-01).
|
Grant |
getGrant()
Get the grant that this access token has inherited.
|
String |
getGrantId()
Get the grant ID which this access token is tied to.
|
GrantType |
getGrantType()
Get the grant type that was used for issuance of the access token.
|
Property[] |
getProperties()
Get the extra properties associated with the access token.
|
URI[] |
getResources()
Get the target resources.
|
String |
getResponseContent()
Get the response content which can be used as a part of the
response to the client application.
|
Scope[] |
getScopeDetails()
Get the details of the scopes.
|
String[] |
getScopes()
Get the scopes covered by the access token.
|
Pair[] |
getServiceAttributes()
Get the attributes of the service that the client application belongs to.
|
String |
getSubject()
Get the subject (= resource owner's ID).
|
boolean |
isClientEntityIdUsed()
Get the flag which indicates whether the entity ID of the client was
used when the request for the access token was made.
|
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 |
isForExternalAttachment()
Get the flag which indicates whether the token is for an external attachment.
|
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 |
setAccessTokenResources(URI[] resources)
Set the target resources of the access token.
|
void |
setAcr(String acr)
Set the Authentication Context Class Reference of the user authentication
that the authorization server performed during the course of issuing the
access token.
|
void |
setAction(IntrospectionResponse.Action action)
Set the next action the service implementation should take.
|
void |
setAuthorizationDetails(AuthzDetails details)
Set the authorization details.
|
void |
setAuthTime(long authTime)
Set the time when the user authentication was performed during the course
of issuing the access token.
|
void |
setCertificateThumbprint(String thumbprint)
Set the client certificate thumbprint used to validate the access token.
|
void |
setClientAttributes(Pair[] attributes)
Set the attributes of the client that the access token has been issued to.
|
void |
setClientEntityId(URI entityId)
Set the entity ID of the client.
|
void |
setClientEntityIdUsed(boolean used)
Set the flag which indicates whether the entity ID of the client was
used when the request for the access token was made.
|
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 |
setConsentedClaims(String[] claims)
Set the claims that the user has consented for the client application
to know.
|
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 |
setForExternalAttachment(boolean forExternalAttachment)
Set the flag which indicates whether the token is for an external attachment.
|
void |
setGrant(Grant grant)
Set the grant that this access token has inherited.
|
void |
setGrantId(String grantId)
Set the grant ID which this access token is tied to.
|
void |
setGrantType(GrantType grantType)
Set the grant type that was used for issuance of the access token.
|
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 |
setResources(URI[] resources)
Set the target resources.
|
void |
setResponseContent(String responseContent)
Set the response content which can be used as a part of the
response to the client application.
|
void |
setScopeDetails(Scope[] details)
Set the details of the scopes.
|
void |
setScopes(String[] scopes)
Set the scopes covered by the access token.
|
void |
setServiceAttributes(Pair[] attributes)
Set the attributes of the service that the client application belongs to.
|
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.
|
getResultCode, getResultMessage, setResultCode, setResultMessage
public IntrospectionResponse.Action getAction()
public void setAction(IntrospectionResponse.Action action)
public long getClientId()
public void setClientId(long clientId)
public String getSubject()
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.
public void setSubject(String subject)
public String[] getScopes()
public void setScopes(String[] scopes)
public Scope[] getScopeDetails()
The scopes
property of this class is a list of scope names.
The property does not hold information about scope attributes.
This scopeDetails
property was newly created to convey
information about scope attributes.
public void setScopeDetails(Scope[] details)
The scopes
property of this class is a list of scope names.
The property does not hold information about scope attributes.
This scopeDetails
property was newly created to convey
information about scope attributes.
details
- The details of the scopes.public boolean isExistent()
true
if the access token exists.
false
if the access token does not exist.public void setExistent(boolean existent)
public boolean isUsable()
true
if the access token is usable. false
if the access token does not exist or has expired.public void setUsable(boolean usable)
public boolean isSufficient()
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.public void setSufficient(boolean sufficient)
public boolean isRefreshable()
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.public void setRefreshable(boolean refreshable)
public String getResponseContent()
public void setResponseContent(String responseContent)
public long getExpiresAt()
public void setExpiresAt(long expiresAt)
expiresAt
- The time at which the access token expires.public Property[] getProperties()
null
when
no extra property is associated with the access token.public void setProperties(Property[] properties)
properties
- Extra properties.public String summarize()
public String getClientIdAlias()
public void setClientIdAlias(String alias)
alias
- The client ID alias.public boolean isClientIdAliasUsed()
true
if the client ID alias was used when the
authorization request or the token request for the access
token was made.public void setClientIdAliasUsed(boolean used)
used
- true
if the client ID alias was used when the
authorization request or the token request for the access
token was made.public URI getClientEntityId()
"Entity ID" is a technical term defined in OpenID Connect Federation 1.0.
public void setClientEntityId(URI entityId)
"Entity ID" is a technical term defined in OpenID Connect Federation 1.0.
entityId
- The entity ID of the client.public boolean isClientEntityIdUsed()
"Entity ID" is a technical term defined in OpenID Connect Federation 1.0.
true
if the entity ID of the client was used when the
request for the access token was made.public void setClientEntityIdUsed(boolean used)
"Entity ID" is a technical term defined in OpenID Connect Federation 1.0.
used
- true
to indicate that the entity ID of the client was
used when the request for the access token was made.public String getCertificateThumbprint()
public void setCertificateThumbprint(String thumbprint)
thumbprint
- The certificate thumbprint, calculated as the SHA256 hash
of the DER-encoded certificate value.public URI[] getResources()
resource
request parameters or by the resource
property in the request object.
See "Resource Indicators for OAuth 2.0" for details.
getAccessTokenResources()
public void setResources(URI[] resources)
resource
request parameters or by the resource
property in the request object.resources
- Target resources.setAccessTokenResources(URI[])
public URI[] getAccessTokenResources()
The target resources returned by this method may be the same as or
different from the ones returned by getResources()
.
In some flows, the initial request and the subsequent token request
are sent to different endpoints. Example flows are the Authorization
Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll
Mode and the Device Flow. In these flows, not only the initial request
but also the subsequent token request can include the resource
request parameters. The purpose of the resource
request
parameters in the token request is to narrow the range of the target
resources from the original set of target resources requested by the
preceding initial request. If narrowing down is performed, the target
resources returned by getResources()
and the ones returned by
this method are different. This method returns the narrowed set of
target resources.
See "Resource Indicators for OAuth 2.0" for details.
getResources()
public void setAccessTokenResources(URI[] resources)
See the description of getAccessTokenResources()
for details
about the target resources of the access token.
resources
- The target resources of the access token.setResources(URI[])
public AuthzDetails getAuthorizationDetails()
"authorization_details"
request parameter which is defined in
"OAuth 2.0 Rich Authorization Requests".public void setAuthorizationDetails(AuthzDetails details)
"authorization_details"
request parameter which is defined in
"OAuth 2.0 Rich Authorization Requests".details
- Authorization details.public String getGrantId()
In Authlete, when an authorization request includes the
grant_management_action
request parameter, a grant ID (which
may be a newly-generated one or an existing one specified by the
grant_id
request parameter) is tied to the access token which
is created as a result of the authorization request.
public void setGrantId(String grantId)
In Authlete, when an authorization request includes the
grant_management_action
request parameter, a grant ID (which
may be a newly-generated one or an existing one specified by the
grant_id
request parameter) is tied to the access token which
is created as a result of the authorization request.
grantId
- The grant ID tied to this access token.public Grant getGrant()
When an authorization request includes grant_id
and
grant_management_action=update
, privileges identified by the
grant ID are additionally given to the access token which is created
as a result of the authorization request. This property represents
the grant.
public void setGrant(Grant grant)
When an authorization request includes grant_id
and
grant_management_action=update
, privileges identified by the
grant ID are additionally given to the access token which is created
as a result of the authorization request. This property represents
the grant.
grant
- The grant that this access token has inherited.public String[] getConsentedClaims()
The following Authlete APIs accept a consentedClaims
request
parameter (which is supported from Authlete 2.3).
/api/auth/authorization/issue
/api/backchannel/authentication/complete
/api/device/complete
The request parameter is used to convey consented claims to Authlete.
This property holds the consented claims. See the description of
AuthorizationIssueRequest.setConsentedClaims(String[])
for
details.
AuthorizationIssueRequest.setConsentedClaims(String[])
,
BackchannelAuthenticationCompleteRequest.setConsentedClaims(String[])
,
DeviceCompleteRequest.setConsentedClaims(String[])
public void setConsentedClaims(String[] claims)
The following Authlete APIs accept a consentedClaims
request
parameter (which is supported from Authlete 2.3).
/api/auth/authorization/issue
/api/backchannel/authentication/complete
/api/device/complete
The request parameter is used to convey consented claims to Authlete.
This property holds the consented claims. See the description of
AuthorizationIssueRequest.setConsentedClaims(String[])
for
details.
claims
- Consented claims.AuthorizationIssueRequest.setConsentedClaims(String[])
,
BackchannelAuthenticationCompleteRequest.setConsentedClaims(String[])
,
DeviceCompleteRequest.setConsentedClaims(String[])
public Pair[] getServiceAttributes()
This property is available since Authlete 2.2.
public void setServiceAttributes(Pair[] attributes)
This property is available since Authlete 2.2.
attributes
- The attributes of the service.public Pair[] getClientAttributes()
This property is available since Authlete 2.2.
public void setClientAttributes(Pair[] attributes)
This property is available since Authlete 2.2.
attributes
- The attributes of the client.public boolean isForExternalAttachment()
OpenID Provider implementations can make Authlete generate access tokens
for external attachments and embed them in ID tokens and userinfo responses
by setting true to the accessTokenForExternalAttachmentEmbedded
property of the service. If the token presented at Authlete's
/api/auth/introspection
API has been generated by the feature,
this forExternalAttachment
property in the response from the
Authlete API becomes true. See the description of
Service.isAccessTokenForExternalAttachmentEmbedded()
for details
about the feature.
true
if the token is for an external attachment.Service.isAccessTokenForExternalAttachmentEmbedded()
public void setForExternalAttachment(boolean forExternalAttachment)
OpenID Provider implementations can make Authlete generate access tokens
for external attachments and embed them in ID tokens and userinfo responses
by setting true to the accessTokenForExternalAttachmentEmbedded
property of the service. If the token presented at Authlete's
/api/auth/introspection
API has been generated by the feature,
this forExternalAttachment
property in the response from the
Authlete API becomes true. See the description of
Service.isAccessTokenForExternalAttachmentEmbedded()
for details
about the feature.
forExternalAttachment
- true
to indicate that the token is for an external attachment.Service.isAccessTokenForExternalAttachmentEmbedded()
public String getAcr()
public void setAcr(String acr)
acr
- The Authentication Context Class Reference.public long getAuthTime()
public void setAuthTime(long authTime)
authTime
- The time of the user authentication in seconds since the Unix epoch.public GrantType getGrantType()
public void setGrantType(GrantType grantType)
grantType
- The grant type.Copyright © 2023. All rights reserved.