com.authlete.common.dto.UserInfoIssueResponse Maven / Gradle / Ivy
/*
* Copyright (C) 2015-2022 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 /auth/userinfo/issue} API.
*
*
* Authlete's {@code /auth/userinfo/issue} API returns JSON which can be
* mapped to this class. The service implementation should retrieve the
* value of {@code "action"} from the response and take the following
* steps according to the value.
*
*
*
* - {@link Action#INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR}
* -
*
* When the value of {@code "action"} is {@code "INTERNAL_SERVER_ERROR"},
* it means that the request from the service implementation was wrong or
* that an error occurred in Authlete.
*
*
*
* In either case, from the viewpoint of the client application, it is an
* error on the server side. Therefore, the service implementation should
* generate a response to the client application with the HTTP status of
* {@code "500 Internal Server Error"}.
*
*
*
* {@link #getResponseContent()} returns a string which describes the error
* in the format of RFC 6750
* (OAuth 2.0 Bearer Token Usage), so the UserInfo
* Endpoint implementation of your service can use the string returned
* from the method as the value of {@code WWW-Authenticate} header.
*
*
*
* The following is an example response which complies with RFC 6750.
* Note that OpenID Connect Core 1.0 requires that an error response from
* UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
*
*
*
* HTTP/1.1 500 Internal Server Error
* WWW-Authenticate: (The value returned from {@link #getResponseContent()})
* Cache-Control: no-store
* Pragma: no-cache
*
*
*
*
* - {@link Action#BAD_REQUEST BAD_REQUEST}
* -
*
* When the value of {@code "action"} is {@code "BAD_REQUEST"}, it means
* that the request from the client application does not contain an access
* token (= the request from the service implementation to Authlete does
* not contain {@code "token"} parameter).
*
*
*
* {@link #getResponseContent()} returns a string which describes the error
* in the format of RFC 6750
* (OAuth 2.0 Bearer Token Usage), so the UserInfo
* Endpoint implementation of your service can use the string returned
* from the method as the value of {@code WWW-Authenticate} header.
*
*
*
* The following is an example response which complies with RFC 6750.
* Note that OpenID Connect Core 1.0 requires that an error response from
* UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
*
*
*
* HTTP/1.1 400 Bad Request
* WWW-Authenticate: (The value returned from {@link #getResponseContent()})
* Cache-Control: no-store
* Pragma: no-cache
*
*
*
*
* - {@link Action#UNAUTHORIZED UNAUTHORIZED}
* -
*
* When the value of {@code "action"} is {@code "UNAUTHORIZED"}, it means
* that the access token does not exist, has expired, or is not associated
* with any subject (= any user account).
*
*
*
* {@link #getResponseContent()} returns a string which describes the error
* in the format of RFC 6750
* (OAuth 2.0 Bearer Token Usage), so the UserInfo
* Endpoint implementation of your service can use the string returned
* from the method as the value of {@code WWW-Authenticate} header.
*
*
*
* The following is an example response which complies with RFC 6750.
* Note that OpenID Connect Core 1.0 requires that an error response from
* UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
*
*
*
* HTTP/1.1 401 Unauthorized
* WWW-Authenticate: (The value returned from {@link #getResponseContent()})
* Cache-Control: no-store
* Pragma: no-cache
*
*
*
*
* - {@link Action#FORBIDDEN FORBIDDEN}
* -
*
* When the value of {@code "action"} is {@code "FORBIDDEN"}, it means
* that the access token does not include the {@code "openid"} scope.
*
*
*
* {@link #getResponseContent()} returns a string which describes the error
* in the format of RFC 6750
* (OAuth 2.0 Bearer Token Usage), so the UserInfo
* Endpoint implementation of your service can use the string returned
* from the method as the value of {@code WWW-Authenticate} header.
*
*
*
* The following is an example response which complies with RFC 6750.
* Note that OpenID Connect Core 1.0 requires that an error response from
* UserInfo endpoint comply with RFC 6750. See 5.3.3. UserInfo Error Response for details.
*
*
*
* HTTP/1.1 403 Forbidden
* WWW-Authenticate: (The value returned from {@link #getResponseContent()})
* Cache-Control: no-store
* Pragma: no-cache
*
*
*
*
* - {@link Action#JSON JSON}
* -
*
* When the value of {@code "action"} is {@code "JSON"}, it means that the
* access token which the client application presented is valid and a userinfo
* response was successfully generated in the format of JSON.
*
*
*
* The UserInfo Endpoint of your service is expected to generate a response
* to the client application. The content type of the response must be {@code
* "application/json"}.
*
*
*
* {@link #getResponseContent()} returns a userinfo response in JSON format when
* {@code "action"} is {@code "JSON"}, so a response to the client can be
* built like below.
*
*
*
* HTTP/1.1 200 OK
* Cache-Control: no-store
* Pragma: no-cache
* Content-Type: application/json;charset=UTF-8
*
* (The value returned from {@link #getResponseContent()})
*
*
*
*
* - {@link Action#JWT JWT}
* -
*
* When the value of {@code "action"} is {@code "JWT"}, it means that the
* access token which the client application presented is valid and a
* userinfo response was successfully generated in the format of JWT
* (JSON Web Token)
* (RFC 7519).
*
*
*
* The UserInfo Endpoint of your service is expected to generate a response
* to the client application. The content type of the response must be {@code
* "application/jwt"}.
*
*
*
* {@link #getResponseContent()} returns a userinfo response in JWT format when
* {@code "action"} is {@code "JWT"}, so a response to the client can be
* built like below.
*
*
*
* HTTP/1.1 200 OK
* Cache-Control: no-store
* Pragma: no-cache
* Content-Type: application/jwt
*
* (The value returned from {@link #getResponseContent()})
*
*
*
*
*
*
* Authlete 2.3 and above has the ability to sign the userinfo response using
* HTTP Message Signatures. If this feature is used,
* the resource server implementation should add the headers in this response
* object to the HTTP response message before returning it to the client.
*
*
*
* - {@link #getSignature()} (REQUIRED)
* -
*
* The serialized value for the {@code Signature} header applied to the
* response.
*
*
*
*
* - {@link #getSignatureInput()} (REQUIRED)
* -
*
* The serialized value for the {@code Signature-Input} header applied to the
* response.
*
*
*
*
* - {@link #getContentDigest()} (OPTIONAL)
* -
*
* The serialized value for the {@code Content-Digest} header applied to the
* response. This value is only returned if a {@code message} was passed
* to the request, otherwise it is {@code null}.
*
*
*
*
* @author Takahiko Kawasaki
*/
public class UserInfoIssueResponse extends ApiResponse
{
private static final long serialVersionUID = 2L;
/**
* The next action the service implementation should take.
*/
public enum Action
{
/**
* The request from the service implementation was wrong or
* an error occurred in Authlete. The service implementation
* should return {@code "500 Internal Server Error"} to the
* client application.
*/
INTERNAL_SERVER_ERROR,
/**
* The request does not contain an access token. The service
* implementation should return {@code "400 Bad Request"} to
* the client application.
*/
BAD_REQUEST,
/**
* The access token does not exist or has expired. The service
* implementation should return {@code "401 Unauthorized"} to
* the client application.
*/
UNAUTHORIZED,
/**
* The access token does not cover the required scopes. To be
* concrete, the access token does not include the {@code
* "openid"} scope. The service implementation should return
* {@code "403 Forbidden"} to the client application.
*/
FORBIDDEN,
/**
* The access token was valid and a userinfo response was
* generated successfully in JSON format. The service implementation
* should return {@code "200 OK"} to the client application
* with the content type {@code "application/json;charset=UTF-8"}.
*/
JSON,
/**
* The access token was valid and a userinfo response token was
* generated successfully in JWT format. The service implementation
* should return {@code "200 OK"} to the client application
* with the content type {@code "application/jwt"}.
*/
JWT
}
private static final String SUMMARY_FORMAT = "action=%s, responseContent=%s";
/**
* @since Authlete 1.1
*/
private Action action;
/**
* @since Authlete 1.1
*/
private String responseContent;
/**
* The signature header of the response message.
* @since Authlete 2.3.0
*/
private String signature;
/**
* The signature-input header of the response message
* @since Authlete 2.3.0
*/
private String signatureInput;
/**
* The content-digest header of the response message
* @since Authlete 2.3.0
*/
private String contentDigest;
/**
* Get the next action that the service implementation should take.
*/
public Action getAction()
{
return action;
}
/**
* Set the next action that the service implementation should take.
*/
public UserInfoIssueResponse setAction(Action action)
{
this.action = action;
return this;
}
/**
* Get the response content which can be used as the entity body
* of the response returned to the client application.
*/
public String getResponseContent()
{
return responseContent;
}
/**
* Set the response content which can be used as the entity body
* of the response returned to the client application.
*/
public UserInfoIssueResponse setResponseContent(String content)
{
this.responseContent = content;
return this;
}
/**
* Get the {@code Signature} header value to add to the response message.
*
* @return
* The serialized header value.
*
* @since 3.38
* @since Authlete 2.3
*/
public String getSignature()
{
return signature;
}
/**
* Set the {@code Signature} header value to add to the response message.
*
* @param signature
* The serialized header value.
*
* @return
* {@code this} object.
*
* @since 3.38
* @since Authlete 2.3
*/
public UserInfoIssueResponse setSignature(String signature)
{
this.signature = signature;
return this;
}
/**
* Get the {@code Signature-Input} header value to add to the response message.
*
* @return
* The serialized header value.
*
* @since 3.38
* @since Authlete 2.3
*/
public String getSignatureInput()
{
return signatureInput;
}
/**
* Set the {@code Signature-Input} header value to add to the response message.
*
* @param signatureInput
* The serialized header value.
*
* @return
* {@code this} object.
*
* @since 3.38
* @since Authlete 2.3
*/
public UserInfoIssueResponse setSignatureInput(String signatureInput)
{
this.signatureInput = signatureInput;
return this;
}
/**
* Get the {@code Content-Digest} header value to add to the response message.
*
* @return
* The serialized header value.
*
* @since 3.38
* @since Authlete 2.3
*/
public String getContentDigest()
{
return contentDigest;
}
/**
* Set the {@code Content-Digest} header value to add to the response message.
*
* @param contentDigest
* The serialized header value.
*
* @return
* {@code this} object.
*
* @since 3.38
* @since Authlete 2.3
*/
public UserInfoIssueResponse setContentDigest(String contentDigest)
{
this.contentDigest = contentDigest;
return this;
}
/**
* Get the summary of this instance.
*/
public String summarize()
{
return String.format(SUMMARY_FORMAT, action, responseContent);
}
}