public class AuthorizationIssueRequest extends Object implements Serializable
/auth/authorization/issue
API.
ticket
(REQUIRED)The ticket issued by Authlete's
/auth/authorization
API to the service implementation. It is the value of"ticket"
contained in the response from Authlete's/auth/authorization
API (AuthorizationResponse
).subject
(CONDITIONALLY REQUIRED)The subject (= a user account managed by the service) who has granted authorization to the client application. This parameter is required unless the authorization request has come with
response_type=none
(which means the client application did not request any token to be returned). See "4. None Response Type" in OAuth 2.0 Multiple Response Type Encoding Practices for details aboutresponse_type=none
.authTime
(OPTIONAL)The time when the authentication of the end-user occurred.
acr
(OPTIONAL)The Authentication Context Class Reference performed for the end-user authentication.
claims
(OPTIONAL)The claims of the end-user (= pieces of information about the end-user) in JSON format. See OpenID Connect Core 1.0, 5.1. Standard Claims for details about the format.
idtHeaderParams
(OPTIONAL)JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request.
properties
(OPTIONAL)Extra properties to associate with an access token and/or an authorization code that may be issued by this request. 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
parameter.scopes
(OPTIONAL)Scopes to associate with an access token and/or an authorization code. If this field is
null
, the scopes specified in the original authorization request from the client application are used. In other cases, including the case of an empty array, the specified scopes will replace the original scopes contained in the original authorization request.Even scopes that are not included in the original authorization request can be specified. However, as an exception,
"openid"
scope is ignored on the server side if it is not included in the original request. It is because the existence of"openid"
scope considerably changes the validation steps and because adding"openid"
triggers generation of an ID token (although the client application has not requested it) and the behavior is a major violation against the specification.If you add
"offline_access"
scope although it is not included in the original request, keep in mind that the specification requires explicit consent from the user for the scope (OpenID Connect Core 1.0, 11. Offline Access). When"offline_access"
is included in the original request, the current implementation of Authlete's/auth/authorization
API checks whether the request has come along withprompt
request parameter and the value includes"consent"
. However, note that the implementation of Authlete's/auth/authorization/issue
API does not perform such checking if"offline_access"
scope is added via thisscopes
parameter.sub
(OPTIONAL)The value of the
sub
claim. If the value of this request parameter is not empty, it is used as the value of thesub
claim. Otherwise, the value of thesubject
request parameter is used as the value of thesub
claim. The main purpose of this parameter is to hide the actual value of the subject from client applications.Note that even if this
sub
parameter is not empty, the value of thesubject
request parameter is used as the value of the subject which is associated with the access token.authorizationDetails
(OPTIONAL)The value of the
authorization_details
to associate with the token. If this value isnull
, the authorization details on the original request are used. If this value is set, its contents completely override the authorization details set in the original request.consentedClaims
(OPTIONAL; Authlete 2.3 onwards)Claims that the user has consented for the client application to know. If this value is
null
or empty, Authlete computes the value from the consented scopes (e.g.profile
) and the claims included in the JSON of theclaims
request parameter. See the description ofsetConsentedClaims(String[])
for details.claimsForTx
(OPTIONAL; Authlete 2.3 onwards)Claim data that are referenced when Authlete computes values of transformed claims. See the description of
setClaimsForTx(String)
for details.verifiedClaimsForTx
(OPTIONAL; Authlete 2.3 onwards)Verified claim data that are referenced when Authlete computes values of transformed claims. See the description of
setVerifiedClaimsForTx(String[])
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; Authlete 2.2.27 onwards)The representation of an access token that may be issued as a result of the Authlete API call. See
getAccessToken()
for details.
AuthorizationResponse
,
OpenID Connect Core 1.0, 5.1. Standard Claims,
Serialized FormConstructor and Description |
---|
AuthorizationIssueRequest() |
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 |
getAcr()
Get the value of
"acr" which is the authentication
context class reference value which the end-user authentication
satisfied. |
AuthzDetails |
getAuthorizationDetails()
Get the authorization details.
|
long |
getAuthTime()
Get the value of
"authTime" which is the time
when the authentication of the end-user occurred. |
String |
getClaims()
Get the value of
"claims" which is the claims of the subject
in JSON format. |
String |
getClaimsForTx()
Get values of claims requested indirectly by "transformed claims".
|
String[] |
getConsentedClaims()
Get the claims that the user has consented for the client application
to know.
|
String |
getIdtHeaderParams()
Get JSON that represents additional JWS header parameters for ID tokens
that may be issued based on the authorization request.
|
String |
getJwtAtClaims()
Get the additional claims in JSON object format that are added to the
payload part of the JWT access token.
|
Property[] |
getProperties()
Get the extra properties to associate with an access token and/or
an authorization code which will be issued by this request.
|
String[] |
getScopes()
Get scopes to associate with an authorization code and/or an access token.
|
String |
getSub()
Get the value of the
sub claim that should be used in
the ID token which is to be issued. |
String |
getSubject()
Get the value of
"subject" which is the subject
(= a user account managed by the service) who has granted
authorization to the client application. |
String |
getTicket()
Get the value of
"ticket" which is the ticket
issued by Authlete's /auth/authorization API
to the service implementation. |
String[] |
getVerifiedClaimsForTx()
Get values of verified claims requested indirectly by
"transformed claims".
|
AuthorizationIssueRequest |
setAccessToken(String accessToken)
Set the representation of an access token that may be issued as a
result of the Authlete API call.
|
AuthorizationIssueRequest |
setAcr(String acr)
Set the value of
"acr" which is the authentication
context class reference value which the end-user authentication
satisfied. |
AuthorizationIssueRequest |
setAuthorizationDetails(AuthzDetails authorizationDetails)
Set the authorization details.
|
AuthorizationIssueRequest |
setAuthTime(long authTime)
Set the value of
"authTime" which is the time
when the authentication of the end-user occurred. |
AuthorizationIssueRequest |
setClaims(Map<String,Object> claims)
Set the value of
"claims" which is the claims of the subject. |
AuthorizationIssueRequest |
setClaims(String claims)
Set the value of
"claims" which is the claims of the subject
in JSON format. |
AuthorizationIssueRequest |
setClaimsForTx(Map<String,Object> claims)
Set the value of
"claimsForTx" which is the claims of the
subject. |
AuthorizationIssueRequest |
setClaimsForTx(String claims)
Set values of claims requested indirectly by "transformed claims".
|
AuthorizationIssueRequest |
setConsentedClaims(String[] claims)
Set the claims that the user has consented for the client application
to know.
|
AuthorizationIssueRequest |
setIdtHeaderParams(String params)
Set JSON that represents additional JWS header parameters for ID tokens
that may be issued based on the authorization request.
|
AuthorizationIssueRequest |
setJwtAtClaims(String claims)
Set the additional claims in JSON object format that are added to the
payload part of the JWT access token.
|
AuthorizationIssueRequest |
setProperties(Property[] properties)
Set extra properties to associate with an access token and/or
an authorization code which will be issued by this request.
|
AuthorizationIssueRequest |
setScopes(String[] scopes)
Set scopes to associate with an authorization code and/or an access token.
|
AuthorizationIssueRequest |
setSub(String sub)
Set the value of the
sub claim that should be used in
the ID token which is to be issued. |
AuthorizationIssueRequest |
setSubject(String subject)
Set the value of
"subject" which is the subject
(= a user account managed by the service) who has granted
authorization to the client application. |
AuthorizationIssueRequest |
setTicket(String ticket)
Set the value of
"ticket" which is the ticket
issued by Authlete's /auth/authorization API
to the service implementation. |
AuthorizationIssueRequest |
setVerifiedClaimsForTx(List<Map<String,Object>> list)
Set the value of
"verifiedClaimsForTx" which is the verified
claims of the subject. |
AuthorizationIssueRequest |
setVerifiedClaimsForTx(String[] claims)
Set values of verified claims requested indirectly by
"transformed claims".
|
public String getTicket()
"ticket"
which is the ticket
issued by Authlete's /auth/authorization
API
to the service implementation.public AuthorizationIssueRequest setTicket(String ticket)
"ticket"
which is the ticket
issued by Authlete's /auth/authorization
API
to the service implementation.ticket
- The ticket.this
object.public String getSubject()
"subject"
which is the subject
(= a user account managed by the service) who has granted
authorization to the client application.
This subject
property is used as the value of the
subject associated with the access token (if one is issued)
and as the value of the sub
claim in the ID token
(if one is issued).
Note that, if getSub()
returns a non-empty value,
it is used as the value of the sub
claim in the ID
token. However, even in such a case, the value of the
subject associated with the access token is still the value
of this subject
property.
getSub()
public AuthorizationIssueRequest setSubject(String subject)
"subject"
which is the subject
(= a user account managed by the service) who has granted
authorization to the client application.
This subject
property is used as the value of the
subject associated with the access token (if one is issued)
and as the value of the sub
claim in the ID token
(if one is issued).
Note that, if a non-empty value is set by setSub(String)
method, the value is used as the value of the sub
claim
in the ID token. However, even in such a case, the value of the
subject associated with the access token is still the value set
by this method.
subject
- The subject.this
object.setSub(String)
public String getSub()
sub
claim that should be used in
the ID token which is to be issued. If this method returns
null
or its value is empty, the value of the subject
is used. The main purpose of this sub
property
is to hide the actual value of the subject from client applications.
Note that the value of the subject
request parameter is
used as the value of the subject associated with the access token
regardless of whether this sub
property is a non-empty
value or not.
sub
claim.getSubject()
public AuthorizationIssueRequest setSub(String sub)
sub
claim that should be used in
the ID token which is to be issued. If null
(the default
value) or an empty string is given, the value of the subject
is used. The main purpose of this sub
property
is to hide the actual value of the subject from client applications.
Note that the value of the subject
request parameter is
used as the value of the subject associated with the access token
regardless of whether this sub
property is a non-empty
value or not.
sub
- The value of the sub
claim.this
object.setSubject(String)
public long getAuthTime()
"authTime"
which is the time
when the authentication of the end-user occurred.public AuthorizationIssueRequest setAuthTime(long authTime)
"authTime"
which is the time
when the authentication of the end-user occurred.authTime
- The time when the end-user authentication occurred.
It is the number of seconds since 1970-01-01.this
object.public String getAcr()
"acr"
which is the authentication
context class reference value which the end-user authentication
satisfied.public AuthorizationIssueRequest setAcr(String acr)
"acr"
which is the authentication
context class reference value which the end-user authentication
satisfied.acr
- The authentication context class reference.this
object.public String getClaims()
"claims"
which is the claims of the subject
in JSON format.setClaims(String)
for details about the format.setClaims(String)
public AuthorizationIssueRequest setClaims(String claims)
"claims"
which is the claims of the subject
in JSON format.
The service implementation is required to retrieve claims of the subject (= information about the end-user) from its database and format them in JSON format.
For example, if "given_name"
claim, "family_name"
claim and "email"
claim are requested, the service implementation
should generate a JSON object like the following:
{ "given_name": "Takahiko", "family_name": "Kawasaki", "email": "takahiko.kawasaki@example.com" }
and set its String representation by this method.
See OpenID Connect Core 1.0, 5.1. Standard Claims for further details about the format.
claims
- The claims of the subject in JSON format.this
object.public AuthorizationIssueRequest setClaims(Map<String,Object> claims)
"claims"
which is the claims of the subject.
The argument is converted into a JSON string and passed to setClaims(String)
method.claims
- The claims of the subject. Keys are claim names.this
object.public Property[] getProperties()
public AuthorizationIssueRequest setProperties(Property[] properties)
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[] getScopes()
null
is returned from this method, replacement
is not performed.public AuthorizationIssueRequest setScopes(String[] scopes)
null
(the default value) is set, the scopes specified in the
original authorization request from the client application are used. In
other cases, including the case of an empty array, the scopes given to
this method will replace the original scopes contained in the original
request.
Even scopes that are not included in the original authorization request
can be specified. However, as an exception, "openid"
scope
is ignored on the server side if it is not included in the original
request (to be exact, if "openid"
was not included in the
parameters
request parameter of /api/auth/authorization API call).
It is because the existence of "openid"
scope considerably
changes the validation steps and because adding "openid"
triggers generation of an ID token (although the client application has
not requested it) and the behavior is a major violation against the
specification.
If you add "offline_access"
scope although it is not
included in the original request, keep in mind that the specification
requires explicit consent from the user for the scope (OpenID Connect Core 1.0, 11. Offline Access). When
"offline_access"
is included in the original request, the
current implementation of Authlete's /api/auth/authorization API checks
whether the request has come along with prompt
request
parameter and the value includes "consent"
. However, note
that the implementation of Authlete's /api/auth/authorization/issue API
does not perform such checking if "offline_access"
scope
is added via this scopes
parameter.
Value | Effect |
---|---|
null |
The scopes contained in the original authorization request are used. |
An empty array | No scopes are associated with an authorization code and/or an access token. The scopes contained in the original authorization request are not used. |
A non-empty array of scope names | Scopes listed in the array are associated with an authorization code and/or an access token. |
scopes
- Scopes to associate with an authorization code and/or an access
token. If a non-null value is set, the original scopes requested
by the client application are replaced.this
object.public String getIdtHeaderParams()
public AuthorizationIssueRequest setIdtHeaderParams(String params)
params
- JSON that represents additional JWS header parameters for ID tokens.this
object.public AuthzDetails getAuthorizationDetails()
"authorization_details"
request parameter which is defined in
"OAuth 2.0 Rich Authorization Requests". If this parameter is
set, it overrides the parameter in the original request.public AuthorizationIssueRequest setAuthorizationDetails(AuthzDetails authorizationDetails)
"authorization_details"
request parameter which is defined in
"OAuth 2.0 Rich Authorization Requests". If this parameter is
set, it overrides the parameter in the original request.authorizationDetails
- Authorization details.this
object.public String[] getConsentedClaims()
See the description of setConsentedClaims(String[])
for
details.
public AuthorizationIssueRequest setConsentedClaims(String[] claims)
If the claims
request parameter holds JSON, Authlete extracts
claims from the JSON and embeds them in an ID token (cf. setClaims(String)
). However, the claims are not necessarily identical
to the set of claims that the user has actually consented for the client
application to know.
For example, if the user has allowed the profile
scope to be
tied to an access token being issued, it technically means that the
user has consented for the client application to know the following
claims based on the mapping defined in OpenID Connect Core 1.0 Section 5.4. Requesting Claims using Scope Values: name
,
family_name
, given_name
, middle_name
,
nickname
, preferred_username
, profile
,
picture
, website
, gender
, birthdate
,
zoneinfo
, locale
and updated_at
. However,
JSON of the claims
request parameter does not necessarily
include all the claims. It may be simply because the authorization
server does not support other claims or because the authorization
server intends to return requested claims from the UserInfo Endpoint instead of embedding them in an ID token, or
for some other reasons. Therefore, Authlete does not assume that the
claims in the JSON of the claims
request parameter represent
the complete set of consented claims.
This consentedClaims
request parameter (supported from Authlete
2.3) can be used to convey the exact set of consented claims to Authlete.
Authlete saves the information into its database and makes them
referrable in responses from the /api/auth/introspection
API
and the /api/auth/userinfo
API.
In addition, the information conveyed via this consentedClaims
request parameter is used to compute the exact value of the claims
parameter in responses from the Grant Management Endpoint, which
is defined in Grant Management for OAuth 2.0.
profile
) and the claims in the JSON of the claims
request parameter although Authlete knows the possibility that the
computed set may be different from the actual set of consented claims.
Especially, the computed set may not include claims that the
authorization server returns from the UserInfo Endpoint. Therefore,
if you want to control the exact set of consented claims, utilize this
request parameter.
claims
- Consented claims.this
object.public String getClaimsForTx()
See the description of setClaimsForTx(String)
for details.
setClaimsForTx(String)
public AuthorizationIssueRequest setClaimsForTx(String claims)
A client application may request "transformed claims". Each of
transformed claims uses an existing claim as input. As a result, to
compute the value of a transformed claim, the value of the referenced
existing claim is needed. This claimsForTx
request parameter
has to be used to provide values of existing claims for computation of
transformed claims.
A response from the /api/auth/authorization
API may include the
requestedClaimsForTx
response parameter which is a list of
claims that are referenced indirectly by transformed claims (cf. AuthorizationResponse.getRequestedClaimsForTx()
). The authorization
server implementation should prepare values of the claims listed in
requestedClaimsForTx
and pass them as the value of this claimsForTx
request parameter.
The following is an example of the value of this request parameter.
{ "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] }
This request parameter (claimsForTx
) is recognized by Authlete
2.3 onwards.
claims
- Values of claims requested indirectly by "transformed claims".
The format is JSON.this
object.AuthorizationResponse.getRequestedClaimsForTx()
public AuthorizationIssueRequest setClaimsForTx(Map<String,Object> claims)
"claimsForTx"
which is the claims of the
subject. The argument is converted into a JSON string and passed
to setClaimsForTx(String)
method.claims
- The claims of the subject. Keys are claim names.this
object.public String[] getVerifiedClaimsForTx()
See the description of setVerifiedClaimsForTx(String[])
for details.
setVerifiedClaimsForTx(String[])
public AuthorizationIssueRequest setVerifiedClaimsForTx(String[] claims)
A client application may request "transformed claims". Each of
transformed claims uses an existing claim as input. As a result, to
compute the value of a transformed claim, the value of the referenced
existing claim is needed. This verifiedClaimsForTx
request
parameter has to be used to provide values of existing claims for
computation of transformed claims.
A response from the /api/auth/authorization
API may include the
requestedVerifiedClaimsForTx
response parameter which is a list
of verified claims that are referenced indirectly by transformed claims
(cf. AuthorizationResponse.getRequestedVerifiedClaimsForTx()
).
The authorization server implementation should prepare values of the
verified claims listed in requestedVerifiedClaimsForTx
and pass
them as the value of this verifiedClaimsForTx
request parameter.
The following is an example of the value of this request parameter.
[ "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" ]
The reason that this verifiedClaimsForTx
property is an array
is that the "verified_claims"
property in the claims
request parameter of an authorization request can be an array like below.
{ "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "id_token": { "verified_claims": [ { "verification": { "trust_framework": { "value": "gold" } }, "claims": { "::18_or_above": null } }, { "verification": { "trust_framework": { "value": "silver" } }, "claims": { ":nationality_usa": null } } ] } }
For the example above, the value of this verifiedClaimsForTx
property should be an array of size 2 and look like below. The first
element is JSON including claims which have been verified under the
trust framework "gold", and the second element is JSON including
claims which have been verified under the trust framework "silver".
[ "{\"birthdate\":\"1970-01-23\"}", "{\"nationalities\":[\"DEU\",\"USA\"]}" ]
This request parameter (verifiedClaimsForTx
) is recognized by
Authlete 2.3 onwards.
claims
- Values of verified claims requested indirectly by
"transformed claims". The format of elements in the
array is JSON.this
object.AuthorizationResponse.getRequestedVerifiedClaimsForTx()
public AuthorizationIssueRequest setVerifiedClaimsForTx(List<Map<String,Object>> list)
"verifiedClaimsForTx"
which is the verified
claims of the subject. Each element in the given list is converted to
a JSON string and a newly created string array containing the converted
elements is passed to setVerifiedClaimsForTx(String[])
.list
- List of clusters of verified claims.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.
public AuthorizationIssueRequest 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.
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.
Note that the Authlete API generates an access token only when the
response_type
request parameter of the authorization request
contains token
. In other cases, the Authlete API generates no
access token.
public AuthorizationIssueRequest 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.
Note that the Authlete API generates an access token only when the
response_type
request parameter of the authorization request
contains token
. In other cases, the Authlete API generates no
access token.
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.