com.authlete.common.dto

Class AuthorizationIssueRequest

java.lang.Object

com.authlete.common.dto.AuthorizationIssueRequest

All Implemented Interfaces:

Serializable

public class AuthorizationIssueRequest
extends Object
implements Serializable

Request to Authlete's /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 about response_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.

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 specify properties 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 with prompt 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 this scopes 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 the sub claim. Otherwise, the value of the subject request parameter is used as the value of the sub 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 the subject request parameter is used as the value of the subject which is associated with the access token.

Author:

Takahiko Kawasaki

See Also:

AuthorizationResponse, OpenID Connect Core 1.0, 5.1. Standard Claims, Serialized Form

Constructor Summary

Constructors

Constructor and Description
AuthorizationIssueRequest()

Method Summary

Modifier and Type	Method and Description
String	getAcr() Get the value of "acr" which is the authentication context class reference value which the end-user authentication satisfied.
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.
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.
AuthorizationIssueRequest	setAcr(String acr) Set the value of "acr" which is the authentication context class reference value which the end-user authentication satisfied.
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	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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AuthorizationIssueRequest

public AuthorizationIssueRequest()

Method Detail

getTicket

public String getTicket()

Get the value of "ticket" which is the ticket issued by Authlete's /auth/authorization API to the service implementation.

Returns:

The ticket.

setTicket

public AuthorizationIssueRequest setTicket(String ticket)

Set the value of "ticket" which is the ticket issued by Authlete's /auth/authorization API to the service implementation.

Parameters:

ticket - The ticket.

Returns:

this object.

getSubject

public 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.

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.

Returns:

The subject.

See Also:

getSub()

setSubject

public 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.

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.

Parameters:

subject - The subject.

Returns:

this object.

Since:

setSub(String)

getSub

public String getSub()

Get the value of the 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.

Returns:

The value of the sub claim.

Since:

1.35

See Also:

getSubject()

setSub

public AuthorizationIssueRequest setSub(String sub)

Set the value of the 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.

Parameters:

sub - The value of the sub claim.

Returns:

this object.

Since:

1.35

See Also:

setSubject(String)

getAuthTime

public long getAuthTime()

Get the value of "authTime" which is the time when the authentication of the end-user occurred.

Returns:

The time when the end-user authentication occurred. It is the number of seconds since 1970-01-01.

setAuthTime

public AuthorizationIssueRequest setAuthTime(long authTime)

Set the value of "authTime" which is the time when the authentication of the end-user occurred.

Parameters:

authTime - The time when the end-user authentication occurred. It is the number of seconds since 1970-01-01.

Returns:

this object.

getAcr

public String getAcr()

Get the value of "acr" which is the authentication context class reference value which the end-user authentication satisfied.

Returns:

The authentication context class reference.

setAcr

public AuthorizationIssueRequest setAcr(String acr)

Set the value of "acr" which is the authentication context class reference value which the end-user authentication satisfied.

Parameters:

acr - The authentication context class reference.

Returns:

this object.

getClaims

public String getClaims()

Get the value of "claims" which is the claims of the subject in JSON format.

Returns:

The claims of the subject in JSON format. See the description of setClaims(String) for details about the format.

See Also:

setClaims(String)

setClaims

public AuthorizationIssueRequest setClaims(String claims)

Set the value of "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.

Parameters:

claims - The claims of the subject in JSON format.

Returns:

this object.

See Also:

OpenID Connect Core 1.0, 5.1. Standard Claims

setClaims

public AuthorizationIssueRequest setClaims(Map<String,Object> claims)

Set the value of "claims" which is the claims of the subject. The argument is converted into a JSON string and passed to setClaims(String) method.

Parameters:

claims - The claims of the subject. Keys are claim names.

Returns:

this object.

Since:

1.24

getProperties

public Property[] getProperties()

Get the extra properties to associate with an access token and/or an authorization code which will be issued by this request.

Returns:

Extra properties.

Since:

1.30

setProperties

public 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.

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 = { new Property("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.

Parameters:

properties - Extra properties.

Returns:

this object.

Since:

1.30

getScopes

public String[] getScopes()

Get scopes to associate with an authorization code and/or an access token. If this method returns a non-null value, the set of scopes will be used instead of the scopes specified in the original authorization request.

Returns:

Scopes to replace the scopes specified in the original authorization request. When null is returned from this method, replacement is not performed.

Since:

1.34

setScopes

public AuthorizationIssueRequest setScopes(String[] scopes)

Set scopes to associate with an authorization code and/or an access token. If 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.

Parameters:

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.

Returns:

this object.

Since:

1.34