Package com.authlete.common.dto

Class IntrospectionRequest

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

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

      • 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

        @Deprecated
public String getUri()
        Deprecated.
        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

        @Deprecated
public IntrospectionRequest setUri​(String uri)
        Deprecated.
        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

      • getTargetUri

        public URI getTargetUri()
        Get the target URI of the resource request, including the query part, if any.

        This parameter is used as the value of the @target-uri derived component for HTTP message signatures (RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI). Additionally, other derived components such as @authority, @scheme, @path, @query and @query-param are computed from this parameter.

        When this parameter is omitted, the value of the htu parameter is used. The htu parameter represents the URL of the resource endpoint, which is identical to the target URI of the resource request as long as the request does not include a query component. Conversely, if the resource request includes a query component, the value of the htu parameter will not match the target URI, and in that case, the HTTP message signature verification will fail.

        If neither this targetUri parameter nor the htu parameter is specified, the target URI is considered unavailable. If HTTP message signing requires the target-uri derived component or other derived components computed based on the target URI, the HTTP message signature verification will fail.

        Returns:
        The target URI of the resource request.
        Since:
        4.13, Authlete 2.3.27
        See Also:
        RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI

      • setTargetUri

        public IntrospectionRequest setTargetUri​(URI targetUri)
        Set the target URI of the resource request, including the query part, if any.

        This parameter is used as the value of the @target-uri derived component for HTTP message signatures (RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI). Additionally, other derived components such as @authority, @scheme, @path, @query and @query-param are computed from this parameter.

        When this parameter is omitted, the value of the htu parameter is used. The htu parameter represents the URL of the resource endpoint, which is identical to the target URI of the resource request as long as the request does not include a query component. Conversely, if the resource request includes a query component, the value of the htu parameter will not match the target URI, and in that case, the HTTP message signature verification will fail.

        If neither this targetUri parameter nor the htu parameter is specified, the target URI is considered unavailable. If HTTP message signing requires the target-uri derived component or other derived components computed based on the target URI, the HTTP message signature verification will fail.

        Parameters:
        targetUri - The target URI of the resource request.
        Returns:
        this object.
        Since:
        4.13, Authlete 2.3.27
        See Also:
        RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI

      • getMessage

        @Deprecated
public String getMessage()
        Deprecated.
        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

        @Deprecated
public IntrospectionRequest setMessage​(String message)
        Deprecated.
        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 included in the resource request. They are used to compute component values, which will be part of the signature base for HTTP message signatures.
        Returns:
        The HTTP headers.
        Since:
        3.38, Authlete 2.3

      • setHeaders

        public IntrospectionRequest setHeaders​(Pair[] headers)
        Set the HTTP headers included in the resource request. They are used to compute component values, which will be part of the signature base for HTTP message signatures.
        Parameters:
        headers - The HTTP headers.
        Returns:
        this object.
        Since:
        3.38, Authlete 2.3

      • isRequestBodyContained

        public boolean isRequestBodyContained()
        Get the flag indicating whether the resource request contains a request body.

        When the resource request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the "content-digest" component identifier must be included in the signature base of the HTTP message signature (see RFC 9421 HTTP Message Signatures) if the resource request contains a request body.

        When this requestBodyContained parameter is true, Authlete checks whether "content-digest" is included in the signature base, if the FAPI profile applies to the resource request.

        Returns:
        true if the resource request contains a request body.
        Since:
        4.13, Authlete 2.3.27

      • setRequestBodyContained

        public IntrospectionRequest setRequestBodyContained​(boolean contained)
        Set the flag indicating whether the resource request contains a request body.

        When the resource request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the "content-digest" component identifier must be included in the signature base of the HTTP message signature (see RFC 9421 HTTP Message Signatures) if the resource request contains a request body.

        When this requestBodyContained parameter is true, Authlete checks whether "content-digest" is included in the signature base, if the FAPI profile applies to the resource request.

        Parameters:
        contained - true to indicate that the resource request contains a request body.
        Returns:
        this object.
        Since:
        4.13, Authlete 2.3.27

      • getRequiredComponents

        @Deprecated
public String[] getRequiredComponents()
        Deprecated.
        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

        @Deprecated
public IntrospectionRequest setRequiredComponents​(String[] requiredComponents)
        Deprecated.
        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)