public class TokenRequest extends Object implements Serializable
/auth/token
API.
parameters
(REQUIRED)OAuth 2.0 token request parameters which are the request parameters that the OAuth 2.0 token endpoint of the service implementation received from the client application.
The value of
"parameters"
is the entire entity body (which is formatted inapplication/x-www-form-urlencoded
) of the request from the client application.clientId
(OPTIONAL)The client ID extracted from
Authorization
header of the token request from the client application.If the token endpoint of the service implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client ID in
Authorization
header, the value should be extracted and set to this parameter.clientSecret
(OPTIONAL)The client secret extracted from
Authorization
header of the token request from the client application.If the token endpoint of the service implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client secret in
Authorization
header, the value should be extracted and set to this parameter.clientCertificate
(OPTIONAL)The client certificate from the MTLS of the token request from the client application. See RFC 8705 (OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens) for details.
clientCertificatePath
(OPTIONAL)The certificate path presented by the client during client authentication. The certificates are strings in PEM format.
properties
(OPTIONAL)Extra properties to associate with an access token. Note that
properties
parameter is accepted only when Content-Type of the request is application/json, so don't use application/x-www-form-urlencoded if you want to specifyproperties
.dpop
(OPTIONAL)The value of the
DPoP
HTTP header. See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.htm
(OPTIONAL)The HTTP method of the token request. In normal cases, the value should be
"POST"
. If omitted,"POST"
is used as the default value. See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.htu
(OPTIONAL)The URL of the token endpoint. If omitted, the
tokenEndpoint
property ofService
is used as the default value. See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.jwtAtClaims
(OPTIONAL; Authlete 2.3 onwards)Additional claims in JSON object format that are added to the payload part of the JWT access token. See the description of
getJwtAtClaims()
for details.accessToken
(OPTIONAL)The representation of an access token that may be issued as a result of the Authlete API call. See
getAccessToken()
for details.
An entity body of a token request may contain the client ID
(client_id
) and the client secret (client_secret
)
along with other request parameters as described in
RFC 6749, 2.3.1. Client Password. If the client credentials
are contained in both Authorization
header and the entity
body, they must be identical. Otherwise, Authlete's /auth/token
API generates an error (it's not a service error but
a client error).
Constructor and Description |
---|
TokenRequest() |
Modifier and Type | Method and Description |
---|---|
String |
getAccessToken()
Get the representation of an access token that may be issued as a
result of the Authlete API call.
|
String |
getClientCertificate()
Get the client certificate from the MTLS of the token
request from the client application.
|
String[] |
getClientCertificatePath()
Get the certificate path presented by the client during
client authentication.
|
String |
getClientId()
Get the client ID extracted from
Authorization
header of the token request from the client application. |
String |
getClientSecret()
Get the client secret extracted from
Authorization
header of the token request from the client application. |
String |
getDpop()
Get the
DPoP header presented by the client during the request
to the token endpoint. |
String |
getHtm()
Get the HTTP method of the token request.
|
String |
getHtu()
Get the URL of the token endpoint.
|
String |
getJwtAtClaims()
Get the additional claims in JSON object format that are added to the
payload part of the JWT access token.
|
String |
getParameters()
Get the value of
parameters which are the request
parameters that the OAuth 2.0 token endpoint of the service
implementation received from the client application. |
Property[] |
getProperties()
Get the extra properties to associate with an access token which
may be issued by this request.
|
TokenRequest |
setAccessToken(String accessToken)
Set the representation of an access token that may be issued as a
result of the Authlete API call.
|
TokenRequest |
setClientCertificate(String clientCertificate)
Set the client certificate from the MTLS of the token
request from the client application.
|
TokenRequest |
setClientCertificatePath(String[] clientCertificatePath)
Set the certificate path presented by the client during
client authentication.
|
TokenRequest |
setClientId(String clientId)
Set the client ID extracted from
Authorization
header of the token request from the client application. |
TokenRequest |
setClientSecret(String clientSecret)
Set the client secret extracted from
Authorization
header of the token request from the client application. |
TokenRequest |
setDpop(String dpop)
Set the
DPoP header presented by the client during the request
to the token endpoint. |
TokenRequest |
setHtm(String htm)
Set the HTTP method of the token request.
|
TokenRequest |
setHtu(String htu)
Set the URL of the token endpoint.
|
TokenRequest |
setJwtAtClaims(String claims)
Set the additional claims in JSON object format that are added to the
payload part of the JWT access token.
|
TokenRequest |
setParameters(Map<String,String[]> parameters)
Set the value of
parameters which are the request
parameters that the OAuth 2.0 token endpoint of the service
implementation received from the client application. |
TokenRequest |
setParameters(String parameters)
Set the value of
parameters which are the request
parameters that the OAuth 2.0 token endpoint of the service
implementation received from the client application. |
TokenRequest |
setProperties(Property[] properties)
Set extra properties to associate with an access token which may
be issued by this request.
|
public String getParameters()
parameters
which are the request
parameters that the OAuth 2.0 token endpoint of the service
implementation received from the client application.public TokenRequest setParameters(String parameters)
parameters
which are the request
parameters that the OAuth 2.0 token endpoint of the service
implementation received from the client application.public TokenRequest setParameters(Map<String,String[]> parameters)
parameters
which are the request
parameters that the OAuth 2.0 token endpoint of the service
implementation received from the client application.
This method converts the given map into a string in x-www-form-urlencoded
and passes it to setParameters(String)
method.
parameters
- Request parameters.this
object.public String getClientId()
Authorization
header of the token request from the client application.public TokenRequest setClientId(String clientId)
Authorization
header of the token request from the client application.public String getClientSecret()
Authorization
header of the token request from the client application.public TokenRequest setClientSecret(String clientSecret)
Authorization
header of the token request from the client application.public String getClientCertificate()
public TokenRequest setClientCertificate(String clientCertificate)
public Property[] getProperties()
public TokenRequest setProperties(Property[] properties)
If the value of grant_type
parameter contained in the token
request from the client application is authorization_code
,
properties set by this method will be added as the extra properties
of a newly created access token. The extra properties specified when
the authorization code was issued (using AuthorizationIssueRequest.setProperties(Property[])
) will also be
used, but their values will be overwritten if the extra properties
set by this method have the same keys. In other words, extra
properties contained in this request will be merged into existing
extra properties which are associated with the authorization code.
Otherwise, if the value of grant_type
parameter contained
in the token request from the client application is refresh_token
, properties set by this method will be added to the
existing extra properties of the corresponding access token. Extra
properties having the same keys will be overwritten in the same
manner as the case of grant_type=authorization_code
.
Otherwise, if the value of grant_type
parameter contained
in the token request from the client application is client_credentials
, properties set by this method will be used
simply as extra properties of a newly created access token.
Because Client Credentials flow does not have a preceding authorization
request, merging extra properties will not be performed. This is
different from the cases of grant_type=authorization_code
and grant_type=refresh_token
.
In other cases (grant_type=password
), properties set by
this method will not be used. When you want to associate extra
properties with an access token which is issued using Resource Owner
Password Credentials flow, use TokenIssueRequest.setProperties(Property[])
method instead.
The argument properties
is an array of properties. Each
property must be a pair of a string key and a string value.
That is, each property must be a string array of size 2. The key
must not be null
or an empty string, but the value may be.
Keys of extra properties will be used as labels of top-level
entries in a JSON response containing an access token which is
returned from an authorization server. An example is
example_parameter
, which you can find in 5.1. Successful
Response in RFC 6749. The following code snippet is an example
to set one extra property having example_parameter
as its
key and example_value
as its value.
Property
[] properties = { newProperty
("example_parameter", "example_value") }; request.setProperties
(properties);
Keys listed below should not be used and they would be ignored on the server side even if they were used. It's because they are reserved in RFC 6749 and OpenID Connect Core 1.0.
access_token
token_type
expires_in
refresh_token
scope
error
error_description
error_uri
id_token
Note that there is an upper limit on the total size of extra properties. On the server side, the properties will be (1) converted to a multidimensional string array, (2) converted to JSON, (3) encrypted by AES/CBC/PKCS5Padding, (4) encoded by base64url, and then stored into the database. The length of the resultant string must not exceed 65,535 in bytes. This is the upper limit, but we think it is big enough.
properties
- Extra properties.this
object.public String[] getClientCertificatePath()
public TokenRequest setClientCertificatePath(String[] clientCertificatePath)
clientCertificatePath
- The client certificate path as an array of strings
in PEM format.this
object.public String getDpop()
DPoP
header presented by the client during the request
to the token 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 "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.
DPoP
header string.public TokenRequest setDpop(String dpop)
DPoP
header presented by the client during the request
to the token 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 "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.
dpop
- The DPoP
header string.this
object.public String getHtm()
DPoP
header.
In normal cases, the value is "POST"
. When this parameter
is omitted, "POST"
is used as the default value.
See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.
"POST"
.public TokenRequest setHtm(String htm)
DPoP
header.
In normal cases, the value is "POST"
. When this parameter
is omitted, "POST"
is used as the default value.
See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.
htm
- The HTTP method as a string. For example, "POST"
.this
object.public String getHtu()
DPoP
header.
If this parameter is omitted, the tokenEndpoint
property
of the Service
is used as the default value.
See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.
public TokenRequest setHtu(String htu)
DPoP
header.
If this parameter is omitted, the tokenEndpoint
property
of the Service
is used as the default value.
See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.
htu
- The URL of the token endpoint.this
object.public String getJwtAtClaims()
This request parameter has a meaning only when the format of access
tokens issued by this service is JWT. In other words, it has a meaning
only when the accessTokenSignAlg
property of the Service
holds a non-null value. See the description of the getAccessTokenSignAlg()
method for
details.
Note that this jwtAtClaims
request parameter to the /auth/token
API works only in the client credentials flow (RFC 6749 Section
4.4). For other flows, additional claims need to be passed to
Authlete through other APIs. For example, to embed additional claims
in an access token that is issued by the authorization code flow
(RFC 6749
Section 4.1), the jwtAtClaims
request parameter of the
/auth/authorization/issue
API has to be used.
public TokenRequest setJwtAtClaims(String claims)
This request parameter has a meaning only when the format of access
tokens issued by this service is JWT. In other words, it has a meaning
only when the accessTokenSignAlg
property of the Service
holds a non-null value. See the description of the getAccessTokenSignAlg()
method for
details.
Note that this jwtAtClaims
request parameter to the /auth/token
API works only in the client credentials flow (RFC 6749 Section
4.4). For other flows, additional claims need to be passed to
Authlete through other APIs. For example, to embed additional claims
in an access token that is issued by the authorization code flow
(RFC 6749
Section 4.1), the jwtAtClaims
request parameter of the
/auth/authorization/issue
API has to be used.
claims
- Additional claims that are added to the payload part of the
JWT access token.this
object.public String getAccessToken()
Basically, it is the Authlete server's role to generate an access token.
However, some systems may have inflexible restrictions on the format of
access tokens. Such systems may use this accessToken
request
parameter to specify the representation of an access token by themselves
instead of leaving the access token generation task to the Authlete server.
Usually, the Authlete server (1) generates a random 256-bit value, (2)
base64url-encodes the value into a 43-character string, and (3) uses the
resultant string as the representation of an access token. The Authlete
implementation is written on the assumption that the 256-bit entropy is
big enough. Therefore, make sure that the entropy of the value of the
accessToken
request parameter is big enough, too.
When no access token is generated as a result of the Authlete API call,
this accessToken
request parameter is not used.
public TokenRequest setAccessToken(String accessToken)
Basically, it is the Authlete server's role to generate an access token.
However, some systems may have inflexible restrictions on the format of
access tokens. Such systems may use this accessToken
request
parameter to specify the representation of an access token by themselves
instead of leaving the access token generation task to the Authlete server.
Usually, the Authlete server (1) generates a random 256-bit value, (2)
base64url-encodes the value into a 43-character string, and (3) uses the
resultant string as the representation of an access token. The Authlete
implementation is written on the assumption that the 256-bit entropy is
big enough. Therefore, make sure that the entropy of the value of the
accessToken
request parameter is big enough, too.
When no access token is generated as a result of the Authlete API call,
this accessToken
request parameter is not used.
accessToken
- The representation of an access token that may be issued as a
result of the Authlete API call.this
object.Copyright © 2023. All rights reserved.