com.authlete.common.dto.CredentialDeferredIssueResponse Maven / Gradle / Ivy
Show all versions of authlete-java-common Show documentation
/*
* Copyright (C) 2023 Authlete, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.authlete.common.dto;
/**
* A response from Authlete's {@code /vci/deferred/issue} API.
*
*
* A response from the {@code /vci/deferred/issue} API can be mapped to this
* class. The API caller should extract the value of the {@code action}
* parameter from the API response and take the next action based on the
* value of the parameter.
*
*
*
* {@code action} = {@link Action#OK OK}
*
*
* The {@code action} value {@link Action#OK OK} means that a credential has
* been issued successfully. In this case, the implementation of the deferred
* credential endpoint should return a successful response to the request
* sender. The HTTP status code and the content type of the response should
* be 200 and {@code application/json}, respectively. The value of the
* {@code responseContent} parameter can be used as the message body of the
* response. It contains the "{@code credential}" parameter that conforms to
* the specification of "Deferred Credential Response".
*
*
*
* HTTP/1.1 200 OK
* Content-Type: application/json
* Cache-Control: no-store
*
* (Put the value of the "responseContent" parameter here.)
*
*
*
* {@code action} = {@link Action#OK_JWT OK_JWT}
*
*
* The {@code action} value {@link Action#OK_JWT OK_JWT} means that a
* credential has been issued successfully and the deferred credential
* response should be encrypted. In this case, the implementation of the
* deferred credential endpoint should return a successful response to the
* request sender. The HTTP status code and the content type of the response
* should be 200 and {@code application/jwt}, respectively. The value of the
* {@code responseContent} parameter is an encrypted JWT and can be used as
* the message body of the response.
*
*
*
* HTTP/1.1 200 OK
* Content-Type: application/jwt
* Cache-Control: no-store
*
* (Put the value of the "responseContent" parameter here.)
*
*
*
* {@code action} = {@link Action#BAD_REQUEST BAD_REQUEST}
*
*
* The {@code action} value {@link Action#BAD_REQUEST BAD_REQUEST} means
* that the original deferred credential request is wrong. In this case,
* the implementation of the deferred credential endpoint should return
* an error response to the request sender. The HTTP status code and the
* content type of the error response should be 400 and
* {@code application/json}, respectively. The value of the
* {@code responseContent} parameter can be used as the message body of
* the error response as it conforms to the specification of "Deferred
* Credential Error Response".
*
*
*
* HTTP/1.1 400 Bad Request
* Content-Type: application/json
* Cache-Control: no-store
*
* (Put the value of the "responseContent" parameter here.)
*
*
*
* {@code action} = {@link Action#FORBIDDEN FORBIDDEN}
*
*
* The {@code action} value {@link Action#FORBIDDEN FORBIDDEN} means that
* the use of the Authlete API is forbidden. In this case, the implementation
* of the deferred credential endpoint should return an error response to the
* request sender. The HTTP status code and the content type of the error
* response should be 403 and {@code application/json}, respectively. The
* value of the {@code responseContent} parameter can be used as the message
* body of the error response as it conforms to the specification of
* "Deferred Credential Error Response".
*
*
*
* HTTP/1.1 403 Forbidden
* Content-Type: application/json
* Cache-Control: no-store
*
* (Put the value of the "responseContent" parameter here.)
*
*
*
* Note that this happens either when the {@link Service#isVerifiableCredentialsEnabled()
* verifiableCredentialsEnabled} property of the {@link Service service} is
* false or when the Authlete server does not support the feature of
* "Verifiable Credentials". In either case, this "forbidden" issue should
* be solved before the service is deployed in a production environment.
*
*
*
* {@code action} = {@link Action#INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR}
*
*
* The {@code action} value {@link Action#INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR}
* means that something wrong happened on Authlete side. In this case, the
* implementation of the deferred credential endpoint should return an error
* response to the request sender. The HTTP status code and the content type
* of the error response should be 500 and {@code application/json},
* respectively. The value of the {@code responseContent} parameter can be
* used as the message body of the error response as it conforms to the
* specification of "Deferred Credential Error Response".
*
*
*
* HTTP/1.1 500 Internal Server Error
* Content-Type: application/json
* Cache-Control: no-store
*
* (Put the value of the "responseContent" parameter here.)
*
*
*
* Note that, however, in real production deployments, it may be better to
* return a vaguer error response instead of a bare one like above.
*
*
*
* {@code action} = {@link Action#CALLER_ERROR CALLER_ERROR}
*
*
* The {@code action} value {@link Action#CALLER_ERROR CALLER_ERROR} means
* that the API call is wrong. For example, the "{@code order}" request
* parameter is missing.
*
*
*
* Caller errors should be solved before the service is deployed in a
* production environment.
*
*
* @since 3.70
* @since Authlete 3.0
*/
public class CredentialDeferredIssueResponse extends ApiResponse
{
private static final long serialVersionUID = 2L;
/**
* The next action that the implementation of the deferred credential
* endpoint should take.
*/
public enum Action
{
/**
* A credential was issued successfully. The implementation of the
* deferred credential endpoint should return a successful response
* with the HTTP status code "200 OK" and the content type
* {@code application/json}.
*/
OK,
/**
* A credential was issued successfully and the deferred credential
* response should be encrypted. The implementation of the deferred
* credential endpoint should return a successful response with the
* TTP status code "200 OK" and the content type
* {@code application/jwt}.
*
* @since 3.86
*/
OK_JWT,
/**
* The original deferred credential request is wrong. This can happen,
* for example, when the process for encrypting the deferred credential
* response with the encryption parameters specified in the deferred
* credential request failed.
*
* @since 3.86
*/
BAD_REQUEST,
/**
* The feature of Verifiable Credentials is not enabled in the service
* configuration.
*/
FORBIDDEN,
/**
* An error occurred on Authlete side.
*/
INTERNAL_SERVER_ERROR,
/**
* The API call is invalid.
*/
CALLER_ERROR,
}
/**
* The next action that the implementation of the deferred credential
* endpoint should take.
*/
private Action action;
/**
* The content of the response that the implementation of the deferred
* credential endpoint should return.
*/
private String responseContent;
/**
* Get the next action that the implementation of the deferred credential
* endpoint should take.
*
* @return
* The next action.
*/
public Action getAction()
{
return action;
}
/**
* Set the next action that the implementation of the deferred credential
* endpoint should take.
*
* @param action
* The next action.
*
* @return
* {@code this} object.
*/
public CredentialDeferredIssueResponse setAction(Action action)
{
this.action = action;
return this;
}
/**
* Get the content of the response that the implementation of the deferred
* credential endpoint should return.
*
* @return
* The content of the response returned from the deferred credential
* endpoint.
*/
public String getResponseContent()
{
return responseContent;
}
/**
* Set the content of the response that the implementation of the deferred
* credential endpoint should return.
*
* @param responseContent
* The content of the response returned from the deferred credential
* endpoint.
*
* @return
* {@code this} object.
*/
public CredentialDeferredIssueResponse setResponseContent(String responseContent)
{
this.responseContent = responseContent;
return this;
}
}