com.authlete.common.dto.UserInfoRequest Maven / Gradle / Ivy
/*
* Copyright (C) 2015-2024 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;
import java.io.Serializable;
import java.net.URI;
/**
* Request to Authlete's {@code /auth/userinfo} API.
*
*
*
* token (REQUIRED)-
*
* An access token to get user information.
*
*
*
* clientCertificate (OPTIONAL)-
*
* The client certificate from the MTLS of the userinfo request from
* the client application.
* See RFC 8705
* (OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access
* Tokens) for details.
*
*
*
* dpop (OPTIONAL)-
*
* The value of the {@code DPoP} HTTP header.
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
*
* htm (OPTIONAL)-
*
* The HTTP method of the userinfo request. In normal cases, the value should
* be either {@code "GET"} or {@code "POST"}.
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
*
* htu (OPTIONAL)-
*
* The URL of the userinfo endpoint, without query or fragment components.
* If omitted, the {@code userInfoEndpoint}
* property of {@link Service} is used as the default value.
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
*
* targetUri (OPTIONAL; Authlete 2.3 onwards)-
*
* The full URL of the userinfo request, including the query part, if any.
*
*
*
* headers (OPTIONAL; Authlete 2.3 onwards)-
*
* The HTTP headers included in the userinfo request. They are used to compute
* component values, which will be part of the signature base for HTTP message
* signatures.
*
*
*
* requestBodyContained (OPTIONAL; Authlete 2.3 onwards)-
*
* The flag indicating whether the userinfo request contains a request body.
*
*
*
* dpopNonceRequired (OPTIONAL; Authlete 3.0 onwards)-
*
* The flag indicating whether to require the DPoP proof JWT to include
* the {@code nonce} claim. Even if the service's {@code dpopNonceRequired}
* property is false, calling the {@code /auth/userinfo} API with this
* {@code dpopNonceRequired} parameter true will force the Authlete API to
* check whether the DPoP proof JWT includes the expected nonce value.
*
*
*
*
*
*
* @author Takahiko Kawasaki
*/
public class UserInfoRequest implements Serializable
{
private static final long serialVersionUID = 5L;
/**
* The access token.
*/
private String token;
/**
* The client certificate used in the TLS connection established
* between the client application and the userinfo endpoint.
*
* @since 2.37
*/
private String clientCertificate;
/**
* The {@code DPoP} header.
*
* @since 2.70
*/
private String dpop;
/**
* The HTTP method of the userinfo request.
*
* @since 2.70
*/
private String htm;
/**
* The URL of the userinfo endpoint,
* without query or fragment components.
*
* @since 2.70
*/
private String htu;
/**
* The full URL of the userinfo endpoint.
*
*
* This parameter has been deprecated and replaced with the
* {@code targetUri} parameter.
*
*
* @since 3.38
* @since Authlete 2.3
* @deprecated
*/
@Deprecated
private String uri;
/**
* The full URI of the userinfo request, including the query part, if any.
*
* @since 4.12
* @since Authlete 2.3.26
*/
private URI targetUri;
/**
* The HTTP headers included in the userinfo request. They are used to
* compute component values, which will be part of the signature base
* for HTTP message signatures.
*
* @since 3.38
* @since Authlete 2.3
*/
private Pair[] headers;
/**
* The HTTP message body of the request, if present.
*
*
* This parameter has been deprecated. In exchange, the
* {@code requestBodyContained} parameter has been introduced.
*
*
* @since 3.38
* @since Authlete 2.3
* @deprecated
*/
@Deprecated
private String message;
/**
* The flag indicating whether the userinfo request contains a request body.
*
* @since 4.12
* @since Authlete 2.3.26
*/
private boolean requestBodyContained;
/**
* Whether to check if the DPoP proof JWT includes the expected nonce value.
*
* @since 3.82
* @since Authlete 3.0
*/
private boolean dpopNonceRequired;
/**
* Get the access token which has come along with the userinfo
* request from the client application.
*/
public String getToken()
{
return token;
}
/**
* Set the access token which has been issued by Authlete.
* The access token is the one that has come along with the
* userinfo request from the client application.
*/
public UserInfoRequest setToken(String token)
{
this.token = token;
return this;
}
/**
* Get the client certificate used in the TLS connection established
* between the client application and the userinfo endpoint.
*
* @return
* The client certificate in PEM format.
*/
public String getClientCertificate()
{
return clientCertificate;
}
/**
* Set the client certificate used in the TLS connection established
* between the client application and the userinfo endpoint.
*
*
* The value of this request parameter is referred to when the access
* token given to the userinfo endpoint was bound to a client certificate
* when it was issued. See RFC 8705 OAuth 2.0
* Mutual-TLS Client Authentication and Certificate-Bound Access Tokens
* for details about the specification of certificate-bound access tokens.
*
*
* @param certificate
* The client certificate in PEM format.
*
* @return
* {@code this} object.
*
* @since 2.37
*/
public UserInfoRequest setClientCertificate(String certificate)
{
this.clientCertificate = certificate;
return this;
}
/**
* Get the {@code DPoP} header presented by the client during the request
* to the userinfo endpoint. The header contains a signed JWT which
* includes the public key that is paired with the private key used to
* sign the JWT.
*
*
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
* @return
* The {@code DPoP} header string.
*
* @since 2.70
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*/
public String getDpop()
{
return dpop;
}
/**
* Set the {@code DPoP} header presented by the client during the request
* to the userinfo endpoint. The header contains a signed JWT which
* includes the public key that is paired with the private key used to
* sign the JWT.
*
*
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
* @param dpop
* The {@code DPoP} header string.
*
* @return
* {@code this} object.
*
* @since 2.70
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*/
public UserInfoRequest setDpop(String dpop)
{
this.dpop = dpop;
return this;
}
/**
* Get the HTTP method of the userinfo request. This field is used to
* validate the {@code DPoP} header.
*
*
* In normal cases, the value is either {@code "GET"} or {@code "POST"}.
*
*
*
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
*
* NOTE: This parameter was added for DPoP, but now it is also used as the
* value of the {@code @method} derived component of HTTP message signatures
* (RFC
* 9421 HTTP Message Signatures, Section 2.2.1. Method).
*
*
* @return
* The HTTP method as a string. For example, {@code "GET"}.
*
* @since 2.70
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*
* @see RFC 9421 HTTP Message Signatures, Section 2.2.1. Method
*/
public String getHtm()
{
return htm;
}
/**
* Set the HTTP method of the userinfo request. This field is used to
* validate the {@code DPoP} header.
*
*
* In normal cases, the value is either {@code "GET"} or {@code "POST"}.
*
*
*
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
*
* NOTE: This parameter was added for DPoP, but now it is also used as the
* value of the {@code @method} derived component of HTTP message signatures
* (RFC
* 9421 HTTP Message Signatures, Section 2.2.1. Method).
*
*
* @param htm
* The HTTP method as a string. For example, {@code "GET"}.
*
* @return
* {@code this} object.
*
* @since 2.70
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*
* @see RFC 9421 HTTP Message Signatures, Section 2.2.1. Method
*/
public UserInfoRequest setHtm(String htm)
{
this.htm = htm;
return this;
}
/**
* Get the URL of the userinfo endpoint. This field is used to validate
* the {@code DPoP} header.
*
*
* If this parameter is omitted, the {@code userInfoEndpoint} property
* of the {@link Service} is used as the default value.
*
*
*
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
* @return
* The URL of the userinfo endpoint.
*
* @since 2.70
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*/
public String getHtu()
{
return htu;
}
/**
* Set the URL of the userinfo endpoint. This field is used to validate
* the {@code DPoP} header.
*
*
* If this parameter is omitted, the {@code userInfoEndpoint} property
* of the {@link Service} is used as the default value.
*
*
*
* See RFC 9449 OAuth
* 2.0 Demonstrating Proof of Possession (DPoP) for details.
*
*
* @param htu
* The URL of the userinfo endpoint.
*
* @return
* {@code this} object.
*
* @since 2.70
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*/
public UserInfoRequest setHtu(String htu)
{
this.htu = htu;
return this;
}
/**
* Get the URL of the userinfo endpoint. This field is used to validate
* the HTTP Message Signature.
*
*
* If this parameter is omitted, the {@code userInfoEndpoint} property
* of the {@link Service} is used as the default value.
*
*
*
* NOTE: This parameter has been deprecated and replaced with the
* {@code targetUri} parameter.
*
*
* @return
* The URL of the userinfo endpoint.
*
* @since 3.38
* @since Authlete 2.3
* @deprecated
*/
@Deprecated
public String getUri()
{
return uri;
}
/**
* Set the URL of the userinfo endpoint. This field is used to validate
* the HTTP Message Signature.
*
*
* If this parameter is omitted, the {@code userInfoEndpoint} property
* of the {@link Service} is used as the default value.
*
*
*
* NOTE: This parameter has been deprecated and replaced with the
* {@code targetUri} parameter.
*
*
* @param uri
* The URL of the userinfo endpoint.
*
* @return
* {@code this} object.
*
* @since 3.38
* @since Authlete 2.3
* @deprecated
*/
@Deprecated
public UserInfoRequest setUri(String uri)
{
this.uri = uri;
return this;
}
/**
* Get the target URI of the userinfo request, including the query part,
* if any.
*
*
* This parameter is used as the value of the {@code @target-uri} derived
* component for HTTP message signatures (RFC 9421
* HTTP Message Signatures, Section 2.2.2. Target URI). Additionally,
* other derived components such as {@code @authority}, {@code @scheme},
* {@code @path}, {@code @query} and {@code @query-param} are computed
* from this parameter.
*
*
*
* When this parameter is omitted, the value of the {@code htu} parameter
* is used. The {@code htu} parameter represents the URL of the userinfo
* endpoint, which usually serves as the target URI of the userinfo request.
* The only exception is when the access token is specified as a query
* parameter, as defined in RFC 6750
* Section 2.3. However, RFC 6750 states that this method "SHOULD
* NOT be used" unless other methods are not viable.
*
*
*
* If neither this {@code targetUri} parameter nor the {@code htu}
* parameter is specified, the {@code userInfoEndpoint} property of the
* {@link Service} is used as a fallback.
*
*
* @return
* The target URI of the userinfo request.
*
* @since 4.12
* @since Authlete 2.3.26
*
* @see RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI
*/
public URI getTargetUri()
{
return targetUri;
}
/**
* Set the target URI of the userinfo request, including the query part,
* if any.
*
*
* This parameter is used as the value of the {@code @target-uri} derived
* component for HTTP message signatures (RFC 9421
* HTTP Message Signatures, Section 2.2.2. Target URI). Additionally,
* other derived components such as {@code @authority}, {@code @scheme},
* {@code @path}, {@code @query} and {@code @query-param} are computed
* from this parameter.
*
*
*
* When this parameter is omitted, the value of the {@code htu} parameter
* is used. The {@code htu} parameter represents the URL of the userinfo
* endpoint, which usually serves as the target URI of the userinfo request.
* The only exception is when the access token is specified as a query
* parameter, as defined in RFC 6750
* Section 2.3. However, RFC 6750 states that this method "SHOULD
* NOT be used" unless other methods are not viable.
*
*
*
* If neither this {@code targetUri} parameter nor the {@code htu}
* parameter is specified, the {@code userInfoEndpoint} property of the
* {@link Service} is used as a fallback.
*
*
* @param targetUri
* The target URI of the userinfo request.
*
* @return
* {@code this} object.
*
* @since 4.12
* @since Authlete 2.3.26
*
* @see RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI
*/
public UserInfoRequest setTargetUri(URI targetUri)
{
this.targetUri = targetUri;
return this;
}
/**
* Get the HTTP headers included in the userinfo request. They are used
* to compute component values, which will be part of the signature base
* for HTTP message signatures.
*
* @return
* The HTTP headers.
*
* @since 3.38
* @since Authlete 2.3
*/
public Pair[] getHeaders()
{
return headers;
}
/**
* Set the HTTP headers included in the userinfo request. They are used
* to compute component values, which will be part of the signature base
* for HTTP message signatures.
*
* @param headers
* The HTTP headers.
*
* @return
* {@code this} object.
*
* @since 3.38
* @since Authlete 2.3
*/
public UserInfoRequest setHeaders(Pair[] headers)
{
this.headers = headers;
return this;
}
/**
* Get the HTTP message body, if present. If provided, this will be used to calculate
* the expected value of the {@code Content-Digest} in the headers of the request
* covered by the HTTP Message Signature.
*
*
* NOTE: This parameter has been deprecated. In exchange, the
* {@code requestBodyContained} parameter has been introduced.
*
*
* @return
* The HTTP message body.
*
* @since 3.38
* @since Authlete 2.3
* @deprecated
*/
@Deprecated
public String getMessage()
{
return message;
}
/**
* Set the HTTP message body, if present. If provided, this will be used to calculate
* the expected value of the {@code Content-Digest} in the headers of the request
* covered by the HTTP Message Signature.
*
*
* NOTE: This parameter has been deprecated. In exchange, the
* {@code requestBodyContained} parameter has been introduced.
*
*
* @param message
* The HTTP message body.
*
* @return
* {@code this} object.
*
* @since 3.38
* @since Authlete 2.3
* @deprecated
*/
@Deprecated
public UserInfoRequest setMessage(String message)
{
this.message = message;
return this;
}
/**
* Get the flag indicating whether the userinfo request contains a request
* body.
*
*
* When the userinfo request must comply with the HTTP message signing
* requirements defined in the FAPI 2.0 Message Signing specification, the
* {@code "content-digest"} component identifier must be included in the
* signature base of the HTTP message signature (see RFC 9421 HTTP Message
* Signatures) if the userinfo request contains a request body.
*
*
*
* When this {@code requestBodyContained} parameter is true, Authlete
* checks whether {@code "content-digest"} is included in the signature
* base, if the FAPI profile applies to the userinfo request.
*
*
*
* NOTE: The FAPI 2.0 Message Signing specification is not applied to
* the userinfo endpoint until its necessity is agreed upon by the
* industry (cf. FAPI Issue 723).
*
*
* @return
* {@code true} if the userinfo request contains a request body.
*
* @since 4.12
* @since Authlete 2.3.26
*/
public boolean isRequestBodyContained()
{
return requestBodyContained;
}
/**
* Set the flag indicating whether the userinfo request contains a request
* body.
*
*
* When the userinfo request must comply with the HTTP message signing
* requirements defined in the FAPI 2.0 Message Signing specification, the
* {@code "content-digest"} component identifier must be included in the
* signature base of the HTTP message signature (see RFC 9421 HTTP Message
* Signatures) if the userinfo request contains a request body.
*
*
*
* When this {@code requestBodyContained} parameter is true, Authlete
* checks whether {@code "content-digest"} is included in the signature
* base, if the FAPI profile applies to the userinfo request.
*
*
*
* NOTE: The FAPI 2.0 Message Signing specification is not applied to
* the userinfo endpoint until its necessity is agreed upon by the
* industry (cf. FAPI Issue 723).
*
*
* @param contained
* {@code true} to indicate that the userinfo request contains
* a request body.
*
* @return
* {@code this} object.
*
* @since 4.12
* @since Authlete 2.3.26
*/
public UserInfoRequest setRequestBodyContained(boolean contained)
{
this.requestBodyContained = contained;
return this;
}
/**
* Get the flag indicating whether to check if the DPoP proof JWT includes
* the expected {@code nonce} value.
*
*
* If this request parameter is {@code true} or if the service's
* {@code dpopNonceRequired} property ({@link Service#isDpopNonceRequired()})
* is {@code true}, the {@code /auth/userinfo} API checks if the DPoP proof
* JWT includes the expected {@code nonce} value. In this case, the response
* from the {@code /auth/userinfo} API will include the {@code dpopNonce}
* response parameter, which should be used as the value of the
* {@code DPoP-Nonce} HTTP header.
*
*
* @return
* {@code true} if the {@code /auth/userinfo} API checks whether the
* DPoP proof JWT includes the expected {@code nonce} value, even
* if the service's {@code dpopNonceRequired} property is false.
*
* @since 3.82
* @since Authlete 3.0
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*/
public boolean isDpopNonceRequired()
{
return dpopNonceRequired;
}
/**
* Set the flag indicating whether to check if the DPoP proof JWT includes
* the expected {@code nonce} value.
*
*
* If this request parameter is {@code true} or if the service's
* {@code dpopNonceRequired} property ({@link Service#isDpopNonceRequired()})
* is {@code true}, the {@code /auth/userinfo} API checks if the DPoP proof
* JWT includes the expected {@code nonce} value. In this case, the response
* from the {@code /auth/userinfo} API will include the {@code dpopNonce}
* response parameter, which should be used as the value of the
* {@code DPoP-Nonce} HTTP header.
*
*
* @param required
* {@code true} to have the {@code /auth/userinfo} API check whether
* the DPoP proof JWT includes the expected {@code nonce} value,
* even if the service's {@code dpopNonceRequired} property is false.
*
* @return
* {@code this} object.
*
* @since 3.82
* @since Authlete 3.0
*
* @see RFC 9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)
*/
public UserInfoRequest setDpopNonceRequired(boolean required)
{
this.dpopNonceRequired = required;
return this;
}
}