com.authlete.common.dto.CredentialJwtIssuerMetadataResponse 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;
/**
* Response from Authlete's {@code /vci/jwtissuer} API.
*
*
* The Authlete API is supposed to be called from within the implementation of
* the JWT VC issuer metadata endpoint ({@code /.well-known/jwt-vc-issuer}) of
* the credential issuer.
*
*
*
* Authlete's {@code /vci/jwtissuer} API returns JSON which can be mapped to
* this class. The credential issuer implementation should retrieve the value
* of the {@link #getAction() action} response parameter from
* the API response and take the following steps according to the value.
*
*
* OK
*
*
* When the value of the {@link #getAction() action} response
* parameter is {@link Action#OK OK}, it means that Authlete
* could prepare the metadata successfully.
*
*
*
* In this case, the implementation of the JWT issuer metadata endpoint
* ({@code /.well-known/jwt-vc-issuer}) of the credential issuer should return
* an HTTP response with the HTTP status code "{@code 200 OK}" and the content
* type "{@code application/json}". The message body of the response has been
* prepared by Authlete's {@code /vci/jwtissuer} API and it is available as
* the {@link #getResponseContent() responseContent} response
* parameter.
*
*
*
* The implementation of the JWT issuer metadata endpoint can construct an
* HTTP response by doing like below.
*
*
*
* 200 OK
* Content-Type: application/json
* (Other HTTP headers)
*
* (the value of the {@link #getResponseContent() responseContent} response parameter)
*
* NOT_FOUND
*
*
* When the value of the {@link #getAction() action} response
* parameter is {@link Action#NOT_FOUND NOT_FOUND}, it means
* that the service configuration has not enabled the feature of Verifiable
* Credentials and so the JWT issuer metadata endpoint should not be accessed.
*
*
*
* In this case, the implementation of the JWT issuer metadata endpoint of the
* credential issuer should return an HTTP response with the HTTP status code
* "{@code 404 Not Found}" and the content type "{@code application/json}".
* The message body (= error information in the JSON format) of the response
* has been prepared by Authlete's {@code /vci/jwtissuer} API and it is available
* as the {@link #getResponseContent() responseContent} response
* parameter.
*
*
*
* The implementation of the JWT issuer metadata endpoint can construct an HTTP
* response by doing like below.
*
*
*
* 404 Not Found
* Content-Type: application/json
* (Other HTTP headers)
*
* (the value of the {@link #getResponseContent() responseContent} response parameter)
*
* INTERNAL_SERVER_ERROR
*
*
* When the value of the {@link #getAction() action} response
* parameter is {@link Action#INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR},
* it means that an unexpected error has occurred on Authlete side or the
* service has not been set up properly yet.
*
*
*
* In this case, a simple implementation of the JWT issuer metadata endpoint
* would return an HTTP response with the HTTP status code
* "{@code 500 Internal Server Error}" and the content type
* "{@code application/json}". The message body (= error information in the
* JSON format) of the response has been prepared by Authlete's
* {@code /vci/jwtissuer} API and it is available as the
* {@link #getResponseContent() responseContent} response parameter.
*
*
*
* Such simple implementation of the JWT issuer metadata endpoint can construct
* an HTTP response by doing like below.
*
*
*
* 500 Internal Server Error
* Content-Type: application/json
* (Other HTTP headers)
*
* (the value of the {@link #getResponseContent() responseContent} response parameter)
*
*
* However, in real commercial deployments, it is rare for a credential issuer
* to return "{@code 500 Internal Server Error}" when it encounters an
* unexpected internal error. It's up to implementations of credential issuers
* what they actually return in the case of internal server error.
*
*
*
* NOTE: The well-known path has been changed from {@code /.well-known/jwt-issuer}
* to {@code /.well-known/jwt-vc-issuer} by a breaking change of the SD-JWT VC
* specification.
*
*
* @since 3.79
* @since Authlete 3.0
*
* @see CredentialJwtIssuerMetadataRequest
* @see SD-JWT-based Verifiable Credentials (SD-JWT VC)
*/
public class CredentialJwtIssuerMetadataResponse extends ApiResponse
{
private static final long serialVersionUID = 1L;
/**
* The next action that the implementation of the JWT issuer metadata
* endpoint ({@code /.well-known/jwt-vc-issuer}) should take after getting
* a response from Authlete's {@code /vci/jwtissuer} API.
*
* @since 3.79
* @since Authlete 3.0
*/
public enum Action
{
/**
* JWT issuer metadata has been prepared successfully. The
* implementation of the JWT issuer metadata endpoint should return
* an HTTP response with the HTTP status code "{@code 200 OK}" and
* the content type "{@code application/json}".
*/
OK,
/**
* The feature of Verifiable Credentials is not enabled. The
* implementation of the JWT issuer metadata endpoint should return
* an HTTP response with the HTTP status code "{@code 404 Not Found}"
* and the content type "{@code application/json}" to indicate that
* the endpoint should not be accessed.
*/
NOT_FOUND,
/**
* An unexpected error occurred on Authlete side or the service has
* not been set up properly yet. A simple implementation of the JWT
* issuer metadata endpoint would return an HTTP response with the
* HTTP status code "{@code 500 Internal Server Error}" and the
* content type "{@code application/json}".
*/
INTERNAL_SERVER_ERROR,
}
private Action action;
private String responseContent;
/**
* Get the next action that the implementation of the JWT issuer metadata
* endpoint should take after getting a response from Authlete's
* {@code /vci/jwtissuer} API.
*
* @return
* The next action.
*/
public Action getAction()
{
return action;
}
/**
* Set the next action that the implementation of the JWT issuer metadata
* endpoint should take after getting a response from Authlete's
* {@code /vci/jwtissuer} API.
*
* @param action
* The next action.
*
* @return
* {@code this} object.
*/
public CredentialJwtIssuerMetadataResponse setAction(Action action)
{
this.action = action;
return this;
}
/**
* Get the content that the implementation of the JWT issuer metadata
* endpoint should use when it constructs a response.
*
*
* In the successful case, the content is JSON like below.
*
*
*
*
* {
* "issuer": "{@link Service}.{@link Service#getCredentialIssuerMetadata()
* getCredentialIssuerMetadata()}.{@link CredentialIssuerMetadata#getCredentialIssuer()
* getCredentialIssuer()}",
* "jwks_uri": "{@link Service}.{@link Service#getCredentialJwksUri()
* getCredentialJwksUri()}"
* }
*
*
*
* @return
* The response content in the JSON format.
*/
public String getResponseContent()
{
return responseContent;
}
/**
* Set the content that the implementation of the JWT issuer metadata
* endpoint should use when it constructs a response.
*
*
* In the successful case, the content should be JSON like below.
*
*
*
*
* {
* "issuer": "{@link Service}.{@link Service#getCredentialIssuerMetadata()
* getCredentialIssuerMetadata()}.{@link CredentialIssuerMetadata#getCredentialIssuer()
* getCredentialIssuer()}",
* "jwks_uri": "{@link Service}.{@link Service#getCredentialJwksUri()
* getCredentialJwksUri()}"
* }
*
*
*
* @param content
* The response content in the JSON format.
*
* @return
* {@code this} object.
*/
public CredentialJwtIssuerMetadataResponse setResponseContent(String content)
{
this.responseContent = content;
return this;
}
}