Package com.authlete.common.dto

Class 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). /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 /auth/token/update API), information returned by /auth/introspection API and information the given JWT-based access token holds may be different.

    DPoP Nonce (Authlete 3.0 onwards)

    Since version 3.0, Authlete recognizes the nonce claim in DPoP proof JWTs. If the presented access token is bound to a public key through the DPoP mechanism, and if the nonce claim is required (= if the service's dpopNonceRequired property is true, or the value of the dpopNonceRequired request parameter passed to the Authlete API is true), the Authlete API checks whether the nonce claim in the presented DPoP proof JWT is identical to the expected value.

    If the dpopNonce response parameter from the API is not null, its value is the expected nonce value for DPoP proof JWT. The expected value needs to be conveyed to the client application as the value of the DPoP-Nonce HTTP header. 

    DPoP-Nonce: (The value returned from getDpopNonce())

    See RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP) for details.

    Author:
    Takahiko Kawasaki
    See Also:
    RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP), Serialized Form

    • Nested Class Summary

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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 getCNonce()
      Get the c_nonce associated with the access token.
      long getCNonceExpiresAt()
      Get the time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).
      String[] getConsentedClaims()
      Get the claims that the user has consented for the client application to know.
      String getDpopNonce()
      Get the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.
      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.
      String getIssuableCredentials()
      Get the credentials that can be obtained by presenting 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 isForCredentialIssuance()
      Get the flag indicating whether the token is for credential issuance.
      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 setCNonce​(String nonce)
      Set the c_nonce associated with the access token.
      void setCNonceExpiresAt​(long expiresAt)
      Set the time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).
      void setConsentedClaims​(String[] claims)
      Set the claims that the user has consented for the client application to know.
      void setDpopNonce​(String dpopNonce)
      Set the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.
      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 setForCredentialIssuance​(boolean forCredentialIssuance)
      Set the flag indicating whether the token is for credential issuance.
      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 setIssuableCredentials​(String credentials)
      Set the credentials that can be obtained by presenting 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.

    • Constructor Detail

      • IntrospectionResponse

        public IntrospectionResponse()

    • Method Detail

      • 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.

      • getScopeDetails

        public Scope[] getScopeDetails()
        Get the details of the scopes.

        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.

        Returns:
        The details of the scopes.
        Since:
        3.16

      • setScopeDetails

        public void setScopeDetails​(Scope[] details)
        Set the details of the scopes.

        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.

        Parameters:
        details - The details of the scopes.
        Since:
        3.16

      • 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

      • getClientEntityId

        public URI getClientEntityId()
        Get the entity ID of the client.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Returns:
        The entity ID of the client.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • setClientEntityId

        public void setClientEntityId​(URI entityId)
        Set the entity ID of the client.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Parameters:
        entityId - The entity ID of the client.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • isClientEntityIdUsed

        public 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.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Returns:
        true if the entity ID of the client was used when the request for the access token was made.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • setClientEntityIdUsed

        public 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.

        "Entity ID" is a technical term defined in OpenID Federation 1.0.

        Parameters:
        used - true to indicate that the entity ID of the client was used when the request for the access token was made.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • 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

      • getResources

        public URI[] getResources()
        Get the target resources. This represents the resources specified by the resource request parameters or by the resource property in the request object.

        See "Resource Indicators for OAuth 2.0" for details.

        Returns:
        Target resources.
        Since:
        2.62
        See Also:
        getAccessTokenResources()

      • setResources

        public void setResources​(URI[] resources)
        Set the target resources. This represents the resources specified by the resource request parameters or by the resource property in the request object.
        Parameters:
        resources - Target resources.
        Since:
        2.62
        See Also:
        setAccessTokenResources(URI[])

      • getAccessTokenResources

        public URI[] getAccessTokenResources()
        Get the target resources of the access token.

        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.

        Returns:
        The target resources of the access token.
        Since:
        2.62
        See Also:
        getResources()

      • setAccessTokenResources

        public void setAccessTokenResources​(URI[] resources)
        Set the target resources of the access token.

        See the description of getAccessTokenResources() for details about the target resources of the access token.

        Parameters:
        resources - The target resources of the access token.
        Since:
        2.62
        See Also:
        setResources(URI[])

      • getAuthorizationDetails

        public AuthzDetails getAuthorizationDetails()
        Get the authorization details. This represents the value of the "authorization_details" request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".
        Returns:
        Authorization details.
        Since:
        2.56

      • setAuthorizationDetails

        public void setAuthorizationDetails​(AuthzDetails details)
        Set the authorization details. This represents the value of the "authorization_details" request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".
        Parameters:
        details - Authorization details.
        Since:
        2.56

      • getGrantId

        public String getGrantId()
        Get the grant ID which this access token is tied to.

        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.

        Returns:
        The grant ID tied to this access token.
        Since:
        3.1
        See Also:
        Grant Management for OAuth 2.0

      • setGrantId

        public void setGrantId​(String grantId)
        Set the grant ID which this access token is tied to.

        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.

        Parameters:
        grantId - The grant ID tied to this access token.
        Since:
        3.1
        See Also:
        Grant Management for OAuth 2.0

      • getGrant

        public Grant getGrant()
        Get the grant that this access token has inherited.

        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.

        Returns:
        The grant that this access token has inherited.
        Since:
        3.1
        See Also:
        Grant Management for OAuth 2.0

      • setGrant

        public void setGrant​(Grant grant)
        Set the grant that this access token has inherited.

        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.

        Parameters:
        grant - The grant that this access token has inherited.
        Since:
        3.1
        See Also:
        Grant Management for OAuth 2.0

      • getServiceAttributes

        public Pair[] getServiceAttributes()
        Get the attributes of the service that the client application belongs to.

        This property is available since Authlete 2.2.

        Returns:
        The attributes of the service.
        Since:
        2.88

      • setServiceAttributes

        public void setServiceAttributes​(Pair[] attributes)
        Set the attributes of the service that the client application belongs to.

        This property is available since Authlete 2.2.

        Parameters:
        attributes - The attributes of the service.
        Since:
        2.88

      • getClientAttributes

        public Pair[] getClientAttributes()
        Get the attributes of the client that the access token has been issued to.

        This property is available since Authlete 2.2.

        Returns:
        The attributes of the client.
        Since:
        2.88

      • setClientAttributes

        public void setClientAttributes​(Pair[] attributes)
        Set the attributes of the client that the access token has been issued to.

        This property is available since Authlete 2.2.

        Parameters:
        attributes - The attributes of the client.
        Since:
        2.88

      • isForExternalAttachment

        public boolean isForExternalAttachment()
        Get the flag which indicates whether the token is for an external attachment.

        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 /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.

        Returns:
        true if the token is for an external attachment.
        Since:
        3.16
        See Also:
        Service.isAccessTokenForExternalAttachmentEmbedded()

      • setForExternalAttachment

        public void setForExternalAttachment​(boolean forExternalAttachment)
        Set the flag which indicates whether the token is for an external attachment.

        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.

        Parameters:
        forExternalAttachment - true to indicate that the token is for an external attachment.
        Since:
        3.16
        See Also:
        Service.isAccessTokenForExternalAttachmentEmbedded()

      • getAcr

        public 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.
        Returns:
        The Authentication Context Class Reference.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol

      • setAcr

        public 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.
        Parameters:
        acr - The Authentication Context Class Reference.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol

      • getAuthTime

        public long getAuthTime()
        Get the time when the user authentication was performed during the course of issuing the access token.
        Returns:
        The time of the user authentication in seconds since the Unix epoch.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol

      • setAuthTime

        public void setAuthTime​(long authTime)
        Set the time when the user authentication was performed during the course of issuing the access token.
        Parameters:
        authTime - The time of the user authentication in seconds since the Unix epoch.
        Since:
        3.40, Authlete 2.3
        See Also:
        RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol

      • getGrantType

        public GrantType getGrantType()
        Get the grant type that was used for issuance of the access token.
        Returns:
        The grant type.
        Since:
        3.41, Authlete 2.1.24, Authlete 2.2.36, Authlete 2.3

      • setGrantType

        public void setGrantType​(GrantType grantType)
        Set the grant type that was used for issuance of the access token.
        Parameters:
        grantType - The grant type.
        Since:
        3.41, Authlete 2.1.24, Authlete 2.2.36, Authlete 2.3

      • isForCredentialIssuance

        public boolean isForCredentialIssuance()
        Get the flag indicating whether the token is for credential issuance.

        OpenID for Verifiable Credential Issuance defines flows to issue Verifiable Credentials. In the flows, a wallet presents an access token at the credential endpoint of a credential issuer and gets a Verifiable Credential in return.

        To get an access token for the purpose, a client application uses either the pre-authorized code flow or the authorization code flow with the authorization_details request parameter whose type is openid_credential.

        For access tokens obtained by the flows described above, this forCredentialIssuance flag is set.

        Returns:
        true if the token is for credential issuance.
        Since:
        3.62, Authlete 3.0
        See Also:
        OpenID for Verifiable Credential Issuance

      • setForCredentialIssuance

        public void setForCredentialIssuance​(boolean forCredentialIssuance)
        Set the flag indicating whether the token is for credential issuance.

        OpenID for Verifiable Credential Issuance defines flows to issue Verifiable Credentials. In the flows, a wallet presents an access token at the credential endpoint of a credential issuer and gets a Verifiable Credential in return.

        To get an access token for the purpose, a client application uses either the pre-authorized code flow or the authorization code flow with the authorization_details request parameter whose type is openid_credential.

        For access tokens obtained by the flows described above, this forCredentialIssuance flag should be set.

        Parameters:
        forCredentialIssuance - true to indicate that the token is for credential issuance.
        Since:
        3.62, Authlete 3.0
        See Also:
        OpenID for Verifiable Credential Issuance

      • getCNonce

        public String getCNonce()
        Get the c_nonce associated with the access token.

        c_nonce is issued from the token endpoint of an authorization server in the pre-authorized code flow, and from the credential endpoint and the batch credential endpoint of a credential issuer.

        In Authlete's implementation, c_nonce is managed in an access token record. Therefore, when the database record is deleted, the c_nonce is deleted together.

        See OpenID for Verifiable Credentials Issuance for details about c_nonce.

        Returns:
        The c_nonce.
        Since:
        3.63, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • setCNonce

        public void setCNonce​(String nonce)
        Set the c_nonce associated with the access token.

        c_nonce is issued from the token endpoint of an authorization server in the pre-authorized code flow, and from the credential endpoint and the batch credential endpoint of a credential issuer.

        In Authlete's implementation, c_nonce is managed in an access token record. Therefore, when the database record is deleted, the c_nonce is deleted together.

        See OpenID for Verifiable Credentials Issuance for details about c_nonce.

        Parameters:
        nonce - The c_nonce.
        Since:
        3.63, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • getCNonceExpiresAt

        public long getCNonceExpiresAt()
        Get the time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).
        Returns:
        The time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).
        Since:
        3.63, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • setCNonceExpiresAt

        public void setCNonceExpiresAt​(long expiresAt)
        Set the time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).
        Parameters:
        expiresAt - The time at which the c_nonce expires in milliseconds since the Unix epoch (1970-01-01).
        Since:
        3.63, Authlete 3.0
        See Also:
        OpenID for Verifiable Credentials Issuance

      • getIssuableCredentials

        public String getIssuableCredentials()
        Get the credentials that can be obtained by presenting the access token.

        The value of this property comes from one or more of the following sources.

        1. The "credentials" property in the credential offer that was used when the access token was issued. A credential offer may contain either or both an issuer state and a pre-authorized code. The issuer state can be used as the value of the "issuer_state" request parameter of an authorization request. The pre-authorized code can be used as the value of the "pre-authorized_code" request parameter of a token request whose "grant_type" is "urn:ietf:params:oauth:grant-type:pre-authorized_code".
        2. The content of a RAR object whose "type" is "openid_credential". RAR objects can be listed in the "authorization_details" request parameter, which is defined in RFC 9396 OAuth 2.0 Rich Authorization Requests.
        3. The content of an entry in the "credentials_supported" metadata of the credential issuer. The identifier of an entry in the "credentials_supported" metadata can be used as a value in the "scope" request parameter.

        The format of this property is a JSON array whose elements are JSON objects. The following is a simple example. 

         [
   {
     "format": "vc+sd-jwt",
     "credential_definition": {
       "vct": "https://credentials.example.com/identity_credential"
     }
   }
 ]
        Returns:
        The credentials that can be obtained by presenting the access token.
        Since:
        3.78, Authlete 3.0
        See Also:
        OpenID for Verifiable Credential Issuance

      • setIssuableCredentials

        public void setIssuableCredentials​(String credentials)
        Set the credentials that can be obtained by presenting the access token.

        See the description of the getIssuableCredentials() method for details about the content of this property.

        Parameters:
        credentials - The credentials that can be obtained by presenting the access token.
        Since:
        3.78, Authlete 3.0
        See Also:
        OpenID for Verifiable Credential Issuance

      • getDpopNonce

        public String getDpopNonce()
        Get the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the protected resource endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Returns:
        The expected nonce value for DPoP proof JWT.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

      • setDpopNonce

        public void setDpopNonce​(String dpopNonce)
        Set the expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

        When this response parameter is not null, the implementation of the protected resource endpoint should add the DPoP-Nonce HTTP header in the response from the endpoint to the client application, using the value of this response parameter as the value of the HTTP header. 

         DPoP-Nonce: (The value of this dpopNonce response parameter)
        Parameters:
        dpopNonce - The expected nonce value for DPoP proof JWT.
        Since:
        3.82, Authlete 3.0
        See Also:
        RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)