Package com.authlete.common.dto

Class BackchannelAuthenticationCompleteResponse

  • All Implemented Interfaces:
    Serializable
    public class BackchannelAuthenticationCompleteResponse
extends ApiResponse
    Response from Authlete's /api/backchannel/authentication/complete API.

    Authlete's /api/backchannel/authentication/complete API returns JSON which can be mapped to this class. The authorization server implementation should retrieve the value of action from the response and take the following steps according to the value.

    NOTIFICATION

    When the value of action is NOTIFICATION, it means that the authorization server must send a notification to the client notification endpoint.

    According to the CIBA Core specification, the notification is an HTTP POST request whose request body is JSON and whose Authorization header contains the client notification token, which was included in the backchannel authentication request as the value of the client_notification_token request parameter, as a bearer token.

    When the backchannel token delivery mode is "ping", the request body of the notification is JSON which contains the auth_req_id property only. When the backchannel token delivery mode is "push", the request body will additionally contain an access token, an ID token and other properties. Note that when the backchannel token delivery mode is "poll", a notification does not have to be sent to the client notification endpoint.

    In error cases, in the "ping" mode, however, the content of a notification is not different from the content in successful cases. That is, the notification contains the auth_req_id property only. The client will know the error when it accesses the token endpoint. On the other hand, in the "push" mode, in error cases, the content of a notification will include the error property instead of an access token and an ID token. The client will know the error by detecting that error is included in the notification.

    In any case, the getResponseContent() method returns JSON which can be used as the request body of the notification.

    The client notification endpoint that the notification should be sent to can be obtained by calling the getClientNotificationEndpoint() method. Likewise, the client notification token that the notification should include as a bearer token can be obtained by calling the getClientNotificationToken() method. With these methods, the notification can be built like the following. 

     POST (The path of getClientNotificationEndpoint()) HTTP/1.1
 HOST: (The host of getClientNotificationEndpoint())
 Authorization: Bearer (The value returned from getClientNotificationToken())
 Content-Type: application/json

 (The value returned from getResponseContent())

    NO_ACTION

    When the value of action is NO_ACTION, it means that the authorization server does not have to take any immediate action.

    NO_ACTION is returned when the backchannel token delivery mode is "poll". In this case, the client will receive the final result at the token endpoint.


    SERVER_ERROR

    When the value of action is SERVER_ERROR, it means either (1) that the request from the authorization server to Authlete was wrong, or (2) that an error occurred on Authlete side.

    When the backchannel token delivery mode is "ping" or "push", SERVER_ERROR is used only when an error is detected before the record of the ticket (which is included in the API call to /api/backchannel/authentication/complete) is retrieved from the database successfully. If an error is detected after the record of the ticket is retrieved from the database, NOTIFICATION is used instead of SERVER_ERROR.

    When the backchannel token delivery mode is "poll", SERVER_ERROR is used regardless of whether it is before or after the record of the ticket is retrieved from the database.


    Since:
    2.32
    See Also:
    Serialized Form

    • Constructor Detail

      • BackchannelAuthenticationCompleteResponse

        public BackchannelAuthenticationCompleteResponse()

    • Method Detail

      • getResponseContent

        public String getResponseContent()
        Get the content of the notification.

        When getAction() returns NOTIFICATION, this method returns JSON which should be used as the request body of the notification.

        In successful cases, when the backchannel token delivery mode is "ping", the JSON contains "auth_req_id". On the other hand, when the backchannel token delivery mode is "push", the JSON contains an access token, an ID token, and optionally a refresh token (and some other properties).

        Returns:
        The content of the notification.

      • setResponseContent

        public BackchannelAuthenticationCompleteResponse setResponseContent​(String responseContent)
        Set the content of the notification.
        Parameters:
        responseContent - The content of the notification.
        Returns:
        this object.

      • getClientId

        public long getClientId()
        Get the client ID of the client application that has made the backchannel authentication request.
        Returns:
        The client ID of the client application.

      • setClientId

        public BackchannelAuthenticationCompleteResponse setClientId​(long clientId)
        Set the client ID of the client application that has made the backchannel authentication request.
        Parameters:
        clientId - The client ID of the client application.
        Returns:
        this object.

      • getClientIdAlias

        public String getClientIdAlias()
        Get the client ID alias of the client application that has made the backchannel authentication request.
        Returns:
        The client ID alias of the client application.

      • setClientIdAlias

        public BackchannelAuthenticationCompleteResponse setClientIdAlias​(String alias)
        Set the client ID alias of the client application that has made the backchannel authentication request.
        Parameters:
        alias - The client ID alias of the client application.
        Returns:
        this object.

      • isClientIdAliasUsed

        public boolean isClientIdAliasUsed()
        Get the flag which indicates whether the client ID alias was used in the backchannel authentication request.
        Returns:
        true if the client ID alias was used in the request.

      • setClientIdAliasUsed

        public BackchannelAuthenticationCompleteResponse setClientIdAliasUsed​(boolean used)
        Set the flag which indicates whether the client ID alias was used in the backchannel authentication request.
        Parameters:
        used - true to indicate that the client ID alias was used in the request.
        Returns:
        this object.

      • 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

      • isClientEntityIdUsed

        public boolean isClientEntityIdUsed()
        Get the flag which indicates whether the entity ID of the client was used in the backchannel authentication request as a client ID.

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

        Returns:
        true if the entity ID of the client was used in the request as a client ID.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • setClientEntityIdUsed

        public BackchannelAuthenticationCompleteResponse setClientEntityIdUsed​(boolean used)
        Set the flag which indicates whether the entity ID of the client was used in the backchannel authentication request as a client ID.

        "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 in the request as a client ID.
        Returns:
        this object.
        Since:
        3.37, Authlete 2.3
        See Also:
        OpenID Federation 1.0

      • getClientIdentifier

        public String getClientIdentifier()
        Get the client identifier used in the backchannel authentication request.

        When isClientIdAliasUsed() returns true, this method returns the same value as getClientIdAlias() does. Otherwise, if isClientEntityIdUsed() returns true, this method returns the same value as getClientEntityId().toString() does. In other cases, this method returns the string representation of the value returned from getClientId().

        Returns:
        The client identifier used in the backchannel authentication request.

      • getClientName

        public String getClientName()
        Get the name of the client application which has made the backchannel authentication request.
        Returns:
        The name of the client application.

      • setClientName

        public BackchannelAuthenticationCompleteResponse setClientName​(String name)
        Set the name of the client application which has made the backchannel authentication request.
        Parameters:
        name - The name of the client application.
        Returns:
        this object.

      • getDeliveryMode

        public DeliveryMode getDeliveryMode()
        Get the backchannel token delivery mode.
        Returns:
        The backchannel token delivery mode.

      • getClientNotificationEndpoint

        public URI getClientNotificationEndpoint()
        Get the client notification endpoint to which a notification needs to be sent.

        This corresponds to the "client_notification_endpoint" metadata of the client application.

        Returns:
        The client notification endpoint.

      • setClientNotificationEndpoint

        public BackchannelAuthenticationCompleteResponse setClientNotificationEndpoint​(URI endpoint)
        Set the client notification endpoint to which a notification needs to be sent.

        This corresponds to the "client_notification_endpoint" metadata of the client application.

        Parameters:
        endpoint - The client notification endpoint.
        Returns:
        this object.

      • getClientNotificationToken

        public String getClientNotificationToken()
        Get the client notification token which needs to be embedded as a Bearer token in the Authorization header in the notification.

        This is the value of the "client_notification_token" request parameter included in the backchannel authentication request.

        Returns:
        The client notification token.

      • setClientNotificationToken

        public BackchannelAuthenticationCompleteResponse setClientNotificationToken​(String token)
        Set the client notification token which needs to be embedded as a Bearer token in the Authorization header in the notification.
        Parameters:
        token - The client notification token.
        Returns:
        this object.

      • getAuthReqId

        public String getAuthReqId()
        Get the value of the "auth_req_id" which is associated with the ticket.
        Returns:
        The value of the "auth_req_id".

      • setAuthReqId

        public BackchannelAuthenticationCompleteResponse setAuthReqId​(String authReqId)
        Set the value of the "auth_req_id" which is associated with the ticket.
        Parameters:
        authReqId - The value of the "auth_req_id".
        Returns:
        this object.

      • getAccessToken

        public String getAccessToken()
        Get the issued access token. This method returns a non-null value only when the backchannel token delivery mode is "push" and an access token has been issued successfully.
        Returns:
        The issued access token.

      • getRefreshToken

        public String getRefreshToken()
        Get the issued refresh token. This method returns a non-null value only when the backchannel token delivery mode is "push" and a refresh token has been issued successfully.

        Note that refresh tokens are not issued if the service does not support the refresh token flow.

        Returns:
        The issued refresh token.

      • getIdToken

        public String getIdToken()
        Get the issued ID token. This method returns a non-null value only when the backchannel token delivery mode is "push" and an ID token has been issued successfully.
        Returns:
        The issued ID token.

      • getAccessTokenDuration

        public long getAccessTokenDuration()
        Get the duration of the access token in seconds. If an access token has not been issued, this method returns 0.
        Returns:
        The duration of the access token in seconds.

      • setAccessTokenDuration

        public BackchannelAuthenticationCompleteResponse setAccessTokenDuration​(long duration)
        Set the duration of the access token in seconds.
        Parameters:
        duration - The duration of the access token in seconds.
        Returns:
        this object.

      • getRefreshTokenDuration

        public long getRefreshTokenDuration()
        Get the duration of the refresh token in seconds. If a refresh token has not been issued, this method returns 0.
        Returns:
        The duration of the refresh token in seconds.

      • setRefreshTokenDuration

        public BackchannelAuthenticationCompleteResponse setRefreshTokenDuration​(long duration)
        Set the duration of the refresh token in seconds.
        Parameters:
        duration - The duration of the refresh token in seconds.
        Returns:
        this object.

      • getIdTokenDuration

        public long getIdTokenDuration()
        Get the duration of the ID token in seconds. If an ID token has not been issued, this method returns 0.
        Returns:
        The duration of the ID token in seconds.

      • setIdTokenDuration

        public BackchannelAuthenticationCompleteResponse setIdTokenDuration​(long duration)
        Set the duration of the ID token in seconds.
        Parameters:
        duration - The duration of the ID token in seconds.
        Returns:
        this object.

      • getJwtAccessToken

        public String getJwtAccessToken()
        Get the newly issued access token in JWT format.

        If the authorization server is configured to issue JWT-based access tokens (= if Service.getAccessTokenSignAlg() returns a non-null value), a JWT-based access token is issued along with the original random-string one.

        Regarding the detailed format of the JWT-based access token, see the description of the Service class.

        Returns:
        The newly issued access token in JWT format. If the service is not configured to issue JWT-based access tokens, this method always returns null.
        Since:
        2.37
        See Also:
        getAccessToken()

      • setJwtAccessToken

        public BackchannelAuthenticationCompleteResponse setJwtAccessToken​(String jwtAccessToken)
        Set the newly issued access token in JWT format.
        Parameters:
        jwtAccessToken - The newly issued access token in JWT format.
        Returns:
        this object.
        Since:
        2.37

      • getResources

        public URI[] getResources()
        Get the resources specified by the resource request parameters or by the resource property in the request object in the preceding backchannel authentication request. If both are given, the values in the request object take precedence. See "Resource Indicators for OAuth 2.0" for details.
        Returns:
        Target resources.
        Since:
        2.62

      • setResources

        public BackchannelAuthenticationCompleteResponse setResources​(URI[] resources)
        Set the resources specified by the resource request parameters or by the resource property in the request object in the preceding backchannel authentication request. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details.
        Parameters:
        resources - Target resources.
        Returns:
        this object.
        Since:
        2.62

      • 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 BackchannelAuthenticationCompleteResponse 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.
        Returns:
        this object.
        Since:
        2.56

      • getGrantId

        public String getGrantId()
        Get the value of the grant_id parameter in the response.

        This property may hold a non-null value only when the backchannel token delivery mode is "push".

        Returns:
        The value of the grant_id response parameter.
        Since:
        3.1
        See Also:
        Grant Management for OAuth 2.0

      • setGrantId

        public BackchannelAuthenticationCompleteResponse setGrantId​(String grantId)
        Set the value of the grant_id parameter in the response.

        This property may hold a non-null value only when the backchannel token delivery mode is "push".

        Parameters:
        grantId - The value of the grant_id response parameter.
        Returns:
        this object.
        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 BackchannelAuthenticationCompleteResponse 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.
        Returns:
        this object.
        Since:
        2.88

      • getClientAttributes

        public Pair[] getClientAttributes()
        Get the attributes of the client.

        This property is available since Authlete 2.2.

        Returns:
        The attributes of the client.
        Since:
        2.88

      • setClientAttributes

        public BackchannelAuthenticationCompleteResponse setClientAttributes​(Pair[] attributes)
        Set the attributes of the client.

        This property is available since Authlete 2.2.

        Parameters:
        attributes - The attributes of the client.
        Returns:
        this object.
        Since:
        2.88