com.authlete.common.dto.FederationConfigurationResponse Maven / Gradle / Ivy
Show all versions of authlete-java-common Show documentation
/*
* Copyright (C) 2022-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 /federation/configuration} API.
*
*
* Authlete's {@code /federation/configuration} API returns JSON which can
* be mapped to this class. The authorization server 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 an entity configuration successfully.
*
*
*
* In this case, the implementation of the entity configuration endpoint of the
* authorization server should return an HTTP response to the client application
* with the HTTP status code "{@code 200 OK}" and the content type
* "{@code application/entity-statement+jwt}". The message body (= an entity
* configuration in the JWT format) of the response has been prepared by
* Authlete's {@code /federation/configuration} API and it is available as the
* {@link #getResponseContent() responseContent} response parameter.
*
*
*
* The implementation of the entity configuration endpoint can construct an
* HTTP response by doing like below.
*
*
*
* 200 OK
* Content-Type: application/entity-statement+jwt
* (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 OpenID Federation 1.0
* and so the client application should have not access the entity configuration
* endpoint.
*
*
*
* In this case, the implementation of the entity configuration endpoint of the
* authorization server should return an HTTP response to the client application
* 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 /federation/configuration} API and it is available as the
* {@link #getResponseContent() responseContent} response parameter.
*
*
*
* The implementation of the entity configuration 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. For example, when a JWK Set
* for federation ({@code Service.}{@link Service#getFederationJwks()
* federationJwks}) has not been setup, when authority hints
* ({@code Service.}{@link Service#getAuthorityHints()
* authorityHints}) have not been setup, etc.
*
*
*
* In this case, a simple implementation of the entity configuration endpoint
* would return an HTTP response to the client application 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 /federation/configuration} API and it is available as the
* {@link #getResponseContent() responseContent} response parameter.
*
*
*
* Such simple implementation of the entity configuration 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 an authorization
* server to return "{@code 500 Internal Server Error}" when it encounters
* an unexpected internal error. It's up to implementations of authorization
* servers what they actually return to client applications in the case of
* internal server error.
*
*
* @since 3.31
* @since Authlete 2.3
*
* @see OpenID Federation 1.0
*/
public class FederationConfigurationResponse extends ApiResponse
{
private static final long serialVersionUID = 1L;
/**
* The next action that the implementation of the entity configuration
* endpoint should take after getting a response from Authlete's
* {@code /federation/configuration} API.
*
* @since 3.31
* @since Authlete 2.3
*/
public enum Action
{
/**
* An entity configuration has been prepared successfully. The
* implementation of the entity configuration endpoint should return
* an HTTP response to the client application with the HTTP status
* code "{@code 200 OK}" and the content type
* "{@code application/entity-statement+jwt}".
*/
OK,
/**
* The feature of OpenID Federation 1.0 is not enabled in this
* service. The implementation of the entity configuration endpoint
* should return an HTTP response to the client application with the
* HTTP status code "{@code 404 Not Found}" and the content type
* "{@code application/json}" to indicate that the client application
* should have not accessed the endpoint.
*/
NOT_FOUND,
/**
* An unexpected error occurred on Authlete side or the service has
* not been set up properly yet. A simple implementation of the entity
* configuration endpoint would return an HTTP response to the client
* application 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 entity configuration
* endpoint should take after getting a response from Authlete's
* {@code /federation/configuration} API.
*
* @return
* The next action.
*/
public Action getAction()
{
return action;
}
/**
* Set the next action that the implementation of the entity configuration
* endpoint should take after getting a response from Authlete's
* {@code /federation/configuration} API.
*
* @param action
* The next action.
*
* @return
* {@code this} object.
*/
public FederationConfigurationResponse setAction(Action action)
{
this.action = action;
return this;
}
/**
* Get the content that the implementation of the entity configuration
* endpoint should use when it constructs a response to the client
* application.
*
*
* The format of the content varies depending on the value of the
* {@code action} response parameter.
*
*
* @return
* The content that should be returned to the client application.
*/
public String getResponseContent()
{
return responseContent;
}
/**
* Set the content that the implementation of the entity configuration
* endpoint should use when it constructs a response to the client
* application.
*
*
* The format of the content varies depending on the value of the
* {@code action} response parameter.
*
*
* @param content
* The content that should be returned to the client application.
*
* @return
* {@code this} object.
*/
public FederationConfigurationResponse setResponseContent(String content)
{
this.responseContent = content;
return this;
}
}