com.authlete.common.dto

Class AuthorizationResponse

java.lang.Object

com.authlete.common.dto.ApiResponse

com.authlete.common.dto.AuthorizationResponse

All Implemented Interfaces:

Serializable

public class AuthorizationResponse
extends ApiResponse

Response from Authlete's /auth/authorization API.

Note: In the description below, "authorization server" is always used even where "OpenID provider" should be used.

Authlete's /auth/authorization API returns JSON which can be mapped to this class. The authorization server implementation should retrieve the value of "action" from the response and take the following steps according to the value.

INTERNAL_SERVER_ERROR

When the value of "action" is "INTERNAL_SERVER_ERROR", it means that the request from the authorization server 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 authorization server implementation should generate a response to the client application with the HTTP status of "500 Internal Server Error". Authlete recommends "application/json" as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable.

getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response.

The following illustrates the response which the authorization server implementation should generate and return to the client application.

 HTTP/1.1 500 Internal Server Error
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

BAD_REQUEST

When the value of "action" is "BAD_REQUEST", it means that the request from the client application is invalid.

The HTTP status of the response returned to the client application should be "400 Bad Request" and Authlete recommends "application/json" as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable.

getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response.

The following illustrates the response which the authorization server implementation should generate and return to the client application.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

LOCATION

When the value of "action" is "LOCATION", it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined.

The HTTP status of the response returned to the client application should be "302 Found" and "Location" header must have a redirect URI with the "error" parameter.

getResponseContent() returns the redirect URI which has the "error" parameter, so it can be used as the value of "Location" header.

The following illustrates the response which the authorization server implementation should generate and return to the client application.

 HTTP/1.1 302 Found
 Location: (The value returned from getResponseContent())
 Cache-Control: no-store
 Pragma: no-cache

FORM

When the value of "action" is "FORM", it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined, and that the request contains response_mode=form_post as is defined in "OAuth 2.0 Form Post Response Mode".

The HTTP status of the response returned to the client application should be "200 OK" and the content type should be "text/html;charset=UTF-8".

getResponseContent() returns an HTML which satisfies the requirements of response_mode=form_post, so it can be used as the entity body of the response.

The following illustrates the response which the authorization server implementation should generate and return to the client application.

 HTTP/1.1 200 OK
 Content-Type: text/html;charset=UTF-8
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

NO_INTERACTION

When the value of "action" is "NO_INTERACTION", it means that the request from the client application has no problem and requires the authorization server to process the request without displaying any user interface for authentication and/or consent. This happens when the request contains prompt=none.

The authorization server implementation must follow the following steps.

1. [END-USER AUTHENTICATION] Check whether an end-user has already logged in. If an end-user has logged in, go to the next step ([MAX_AGE]). Otherwise, call Authlete's /auth/authorization/fail API with reason=NOT_LOGGED_IN and use the response from the API to generate a response to the client application.

   
   

2. [MAX_AGE] Get the value of the max age by getMaxAge() method. The value represents the maximum authentication age which has come from "max_age" request parameter or "default_max_age" configuration parameter of the client application. If the value is 0, go to the next step ([SUBJECT]). Otherwise, follow the sub steps described below.

   
   

   1. Get the time at which the end-user was authenticated. Note that this value is not managed by Authlete, meaning that it is expected that the authorization server implementation manages the value. If the authorization server implementation does not manage authentication time of end-users, call Authlete's /auth/authorization/fail API with reason=MAX_AGE_NOT_SUPPORTED and use the response from the API to generate a response to the client application.

      
      

   2. Add the value of the maximum authentication age (which is represented in seconds) to the authentication time.

      
      

   3. Check whether the calculated value is equal to or greater than the current time. If this condition is satisfied, go to the next step ([SUBJECT]). Otherwise, call Authlete's /auth/authorization/fail API with reason=EXCEEDS_MAX_AGE and use the response from the API to generate a response to the client application.

   
   

3. [SUBJECT] Get the value of the requested subject by getSubject() method. The value represents an end-user who the client application expects to grant authorization. If the value is null, go to the next step ([ACRs]). Otherwise, follow the sub steps described below.

   
   

   1. Compare the value of the requested subject to the subject (= unique user ID) of the current end-user.

      
      

   2. If they are equal, go to the next step ([ACRs]).

      
      

   3. If they are not equal, call Authlete's /auth/authorization/fail API with reason=DIFFERENT_SUBJECT and use the response from the API to generate a response to the client application.

   
   

4. [ACRs] Get the value of ACRs (Authentication Context Class References) by getAcrs() method. The value has come from (1) "acr" claim in "claims" request parameter, (2) "acr_values" request parameter, or (3) "default_acr_values" configuration parameter of the client application.

   
   

   It is ensured that all the ACRs returned by getAcrs() method are supported by the authorization server implementation. In other words, it is ensured that all the ACRs are listed in the "acr_values_supported" configuration parameter of the authorization server.

   
   

   If the value of ACRs is null, go to the next step ([SCOPES]). Otherwise, follow the sub steps described below.

   
   

   1. Get the ACR performed for the authentication of the current end-user. Note that this value is managed not by Authlete but by the authorization server implementation. (If the authorization server implementation cannot handle ACRs, it should not have listed ACRs as "acr_values_supported".)

      
      

   2. Compare the ACR value obtained in the above step to each element in the ACR array obtained by getAcrs() method in the listed order. If the ACR value was found in the array, go to the next step ([SCOPES]).

      
      

   3. If the ACR value was not found in the ACR array (= the ACR performed for the authentication of the current end-user did not match any one of the ACRs requested by the client application), check whether one of the requested ACRs must be satisfied or not by calling isAcrEssential() method. If isAcrEssential() returns true, call Authlete's /auth/authorization/fail API with reason=ACR_NOT_SATISFIED and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([SCOPES]).

   
   

5. [SCOPES] Get the scopes by getScopes(). If the array contains a scope which has not been granted to the client application by the end-user in the past, call Authlete's /auth/authorization/fail API with reason=CONSENT_REQUIRED and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]).

   
   

   Note that Authlete provides APIs to manage records of granted scopes (/api/client/granted_scopes/* APIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server (contact sales@authlete.com for details). In other words, the APIs of the shared Authlete server are disabled intentionally (in order to prevent garbage data from being accumulated) and they return 403 Forbidden.

   
   

6. [RESOURCES] Get the requested target resources by getResources(). The array represents the values of the resource request parameters. If you want to reject the request, call Authlete's /auth/authorization/fail API with reason=INVALID_TARGET and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([ISSUE]).

   
   

   See "Resource Indicators for OAuth 2.0" for details. Note that the specification is supported since Authlete 2.2. If the Authlete server you are using is older than 2.2, getResources() always returns null.

   
   

7. [ISSUE] If all the above steps succeeded, the last step is to issue an authorization code, an ID token and/or an access token. (There is a special case. When response_type=none, nothing is issued.) The last step can be performed by calling Authlete's /auth/authorization/issue API. The API requires the following parameters, which are represented as properties of AuthorizationIssueRequest class. Prepare these parameters and call the /auth/authorization/issue API.

   
   

   • [ticket] (required) This parameter represents a ticket which is exchanged with tokens at the /auth/authorization/issue endpoint. Use the value returned by getTicket() as it is.

     
     

   • [subject] (required) This parameter represents the unique identifier of the current end-user. It is often called "user ID" and it may or may not be visible to the user. In any case, it is a number or a string assigned to an end-user by your service. Authlete does not care about the format of the value of subject, but it must consist of only ASCII letters and its length must be equal to or less than 100.

     
     

     When getSubject() method returns a non-null value, the value of subject parameter is necessarily identical to the value returned from the method.

     
     

     The value of this parameter will be embedded in an ID token as the value of "sub" claim. When the value of "subject_type" configuration parameter of the client is PAIRWISE, the value of "sub" claim is different from the value specified here. Note that the behavior for PAIRWISE is not supported by Authlete 2.1 and older versions. See 8. Subject Identifier Types of OpenID Connect Core 1.0 for details about subject types.

     
     

     You can use the sub request parameter to adjust the value of the sub claim in an ID token. See the description of the sub request parameter for details.

     
     

   • [authTime] (optional) This parameter represents the time when the end-user authentication occurred. Its value is the number of seconds from 1970-01-01. The value of this parameter will be embedded in an ID token as the value of "auth_time" claim.

     
     

   • [acr] (optional) This parameter represents the ACR (Authentication Context Class Reference) which the authentication of the end-user satisfies. When getAcrs() method returns a non-empty array and isAcrEssential() method returns true, the value of this parameter must be one of the array elements. Otherwise, even null is allowed. The value of this parameter will be embedded in an ID token as the value of "acr" claim.

     
     

   • [claims] (optional) This parameter represents claims of the end-user. "Claims" here are pieces of information about the end-user such as "name", "email" and "birthdate". The authorization server implementation is required to gather claims of the end-user, format the claim values into a JSON and set the JSON string as the value of this parameter.

     
     

     The claims which the authorization server implementation is required to gather can be obtained by getClaims() method.

     
     

     For example, if getClaims() method returns an array which contains "name", "email" and "birthdate", the value of this parameter should look like the following.

      {
        "name": "John Smith",
        "email": "john@example.com",
        "birthdate": "1974-05-06"
      }

     getClaimsLocales() lists the end-user's preferred languages and scripts for claim values, ordered by preference. When getClaimsLocales() returns a non-empty array, its elements should be taken into account when the authorization server implementation gathers claim values. Especially, note the excerpt below from 5.2. Claims Languages and Scripts of OpenID Connect Core 1.0.

     "When the OP determines, either through the claims_locales parameter, or by other means, that the End-User and Client are requesting Claims in only one set of languages and scripts, it is RECOMMENDED that OPs return Claims without language tags when they employ this language and script. It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims using language tags."

     If getClaims() method returns null or an empty array, the value of this parameter should be null.

     
     

     See 5.1. Standard Claims of OpenID Connect Core 1.0 for claim names and their value formats. Note (1) that the authorization server implementation may support its special claims (5.1.2. Additional Claims) and (2) that claim names may be followed by a language tag (5.2. Claims Languages and Scripts). Read the specification of OpenID Connect Core 1.0 for details.

     
     

     The claim values in this parameter will be embedded in an ID token.

     
     

     getIdTokenClaims() is available since version 2.25. The method returns the value of the "id_token" property in the "claims" request parameter or in the "claims" property in a request object. The value returned from the method should be considered when you prepare claim values. See the description of the method for details. Note that, however, old Authlete servers don't support this response parameter.

     
     

   • [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 to Authlete's /auth/authorization/issue is application/json, so don't use application/x-www-form-urlencoded if you want to use this request parameter. See Extra Properties for details.

     
     

   • [scopes] (optional) Scopes to associate with an access token and/or an authorization code. If this parameter 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 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 Authlete 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 in an ID token which may be issued. 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.

   
   

   /auth/authorization/issue API returns a response in JSON format which can be mapped to AuthorizationIssueResponse. Use the response from the API to generate a response to the client application. See the description of AuthorizationIssueResponse for details.

INTERACTION

When the value of "action" is "INTERACTION", it means that the request from the client application has no problem and requires the authorization server to process the request with user interaction by an HTML form.

The purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to a client application. The items described below are some points which the authorization server implementation should take into account when it builds the UI.

1. [DISPLAY MODE] AuthorizationResponse contains "display" parameter. The value can be obtained by getDisplay() method and is one of PAGE (default), POPUP, TOUCH and WAP. The meanings of the values are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0. Basically, the authorization server implementation should display the UI which is suitable for the display mode, but it is okay for the authorization server implementation to "attempt to detect the capabilities of the User Agent and present an appropriate display."

   
   

   It is ensured that the value returned by getDisplay() is one of the supported display values which are specified by "display_values_supported" configuration parameter of the service.

   
   

2. [UI LOCALE] AuthorizationResponse contains "ui_locales" parameter. The value can be obtained by getUiLocales() and it is an array of language tag values (such as "fr-CA" and "en") ordered by preference. The authorization server implementation should display the UI in one of the language listed in the "ui_locales" parameter when possible.

   
   

   It is ensured that language tags returned by getUiLocales() are contained in the list of supported UI locales which are specified by "ui_locales_supported" configuration parameter of the service.

   
   

3. [CLIENT INFORMATION] The authorization server implementation should show the end-user information about the client application. The information can be obtained by getClient() method.

   
   

4. [SCOPES] A client application requires authorization for specific permissions. In OAuth 2.0 specification, "scope" is a technical term which represents a permission. getScopes() method returns scopes requested by the client application. The authorization server implementation should show the end-user the scopes.

   
   

   The authorization server implementation may choose not to show scopes to which the end-user has given consent in the past. To put it the other way around, the authorization server implementation may show only the scopes to which the end-user has not given consent yet. However, if the value returned from getPrompts() contains CONSENT, the authorization server implementation has to obtain explicit consent from the end-user even if the end-user has given consent to all the requested scopes in the past.

   
   

   Note that Authlete provides APIs to manage records of granted scopes (/api/client/granted_scopes/* APIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server (contact sales@authlete.com for details). In other words, the APIs of the shared Authlete server are disabled intentionally (in order to prevent garbage data from being accumulated) and they return 403 Forbidden.

   
   

   It is ensured that scopes returned by getScopes() are contained in the list of supported scopes which are specified by "scopes_supported" configuration parameter of the service.

   
   

5. [AUTHORIZATION DETAILS] The authorization server implementation should show the end-user "authorization details" if the request includes it. getAuthorizationDetails() returns the content of the authorization_details request parameter.

   
   

   See "OAuth 2.0 Rich Authorization Requests" for details. Note that the specification is supported since Authlete 2.2. If the Authlete server you are using is older than 2.2, getAuthorizationDetails() always returns null.

   
   

6. [PURPOSE] The authorization server implementation must show the value of the purpose request parameter if it supports OpenID Connect for Identity Assurance 1.0. See 8. Transaction-specific Purpose in the specification for details.

   
   

   getPurpose() returns the value of the purpose request parameter. However, if the Authlete server you are using does not support OpenID Connect for Identity Assurance 1.0 (in other words, if the Authlete server is older than 2.2), getPurpose() always returns null.

   
   

7. [END-USER AUTHENTICATION] Necessarily, the end-user must be authenticated (= must login your service) before granting authorization to the client application. Simply put, a login form is expected to be displayed for end-user authentication. The authorization server implementation must follow the steps described below to comply with OpenID Connect. (Or just always show a login form if it's too much of a bother to follow the steps below.)

   
   

   1. Get the value of getPrompts(). It corresponds to the value of the prompt request parameter. Details of the request parameter are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0.

      
      

   2. If the value returned from getPrompts() contains SELECT_ACCOUNT, display a form to urge the end-user to select one of his/her accounts for login. If getSubject() returns a non-null value, it is the end-user ID that the client application expects, so the value should be used to determine the value of the login ID. Note that a subject and a login ID are not necessarily equal. If getSubject() returns null, the value returned by getLoginHint() should be referred to as a hint to determine the value of the login ID. getLoginHint() method simply returns the value of the login_hint request parameter.

      
      

   3. If the value returned from getPrompts() contains LOGIN, display a form to urge the end-user to login even if the end-user has already logged in. If getSubject() returns a non-null value, it is the end-user ID that the client application expects, so the value should be used to determine the value of the login ID. Note that a subject and a login ID are not necessarily equal. If getSubject() returns null, the value returned by getLoginHint() should be referred to as a hint to determine the value of the login ID. getLoginHint() method simply returns the value of the login_hint request parameter.

      
      

   4. If the value returned from getPrompts() does not contain LOGIN, the authorization server implementation does not have to authenticate the end-user if all the conditions described below are satisfied. If any one of the conditions is not satisfied, show a login form to authenticate the end-user.

      
      

      • An end-user has already logged in your service.

        
        

      • The login ID of the current end-user matches the value returned by getSubject(). This check is required only when getSubject() returns a non-null value.

        
        

      • The max age, which is the number of seconds obtained by getMaxAge() method, has not passed since the current end-user logged in your service. This check is required only when getMaxAge() returns a non-zero value.

        
        

        If the authorization server implementation does not manage authentication time of end-users (= if the authorization server implementation cannot know when end-users logged in) and if getMaxAge() returns a non-zero value, a login form should be displayed.

        
        

      • The ACR (Authentication Context Class Reference) of the authentication performed for the current end-user satisfies one of the ACRs listed by getAcrs(). This check is required only when getAcrs() returns a non-empty array.

   
   

   In every case, the end-user authentication must satisfy one of the ACRs listed by getAcrs() when getAcrs() returns a non-empty array and isAcrEssential() returns true.

   
   

8. [GRANT/DENY BUTTONS] The end-user is supposed to choose either (1) to grant authorization to the client application or (2) to deny the authorization request. The UI must have UI components to accept the decision by the user. Usually, a button to grant authorization and a button to deny the request are provided.

   
   

When the subject returned by getSubject() method is not null, the end-user authentication must be performed for the subject, meaning that the authorization server implementation should repeatedly show a login form until the subject is successfully authenticated.

The end-user will choose either (1) to grant authorization to the client application or (2) to deny the authorization request. When the end-user chose to deny the authorization request, call Authlete's /auth/authorization/fail API with reason=DENIED and use the response from the API to generate a response to the client application.

When the end-user chose to grant authorization to the client application, the authorization server implementation has to issue an authorization code, an ID token, and/or an access token to the client application. (There is a special case. When response_type=none, nothing is issued.) Issuing the tokens can be performed by calling Authlete's /auth/authorization/issue API. Read [ISSUE] written above in the description for the case of action=NO_INTERACTION.

Author:

Takahiko Kawasaki

See Also:

RFC 6749, OAuth 2.0, OpenID Connect Core 1.0, OpenID Connect Dynamic Client Registration 1.0, OpenID Connect Discovery 1.0, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AuthorizationResponse.Action The next action that the service implementation should take.

Constructor Summary

Constructors

Constructor and Description
AuthorizationResponse()

Method Summary

Modifier and Type	Method and Description
String[]	getAcrs() Get the list of ACRs (Authentication Context Class References) requested by the client application.
AuthorizationResponse.Action	getAction() Get the next action that the service implementation should take.
AuthzDetails	getAuthorizationDetails() Get the authorization details.
String[]	getClaims() Get the list of claims that the client application requests to be embedded in the ID token.
String[]	getClaimsLocales() Get the list of preferred languages and scripts for claim values contained in the ID token.
Client	getClient() Get the information about the client application which has made the authorization request.
Display	getDisplay() Get the display mode which the client application requests by "display" request parameter.
String	getIdTokenClaims() Get the value of the "id_token" property in the "claims" request parameter or in the "claims" property in a request object.
String	getLoginHint() Get the value of login hint, which is specified by the client application using "login_hint" request parameter.
Prompt	getLowestPrompt() Deprecated.
int	getMaxAge() Get the maximum authentication age which is the allowable elapsed time in seconds since the last time the end-user was actively authenticated by the service implementation.
Prompt[]	getPrompts() Get the list of prompts contained in the authorization request (= the value of prompt request parameter).
String	getPurpose() Get the value of the purpose request parameter.
String	getRequestObjectPayload() Get the payload part of the request object.
URI[]	getResources() Get the resources specified by the resource request parameters or by the resource property in the request object.
String	getResponseContent() Get the response content which can be used to generate a response to the client application.
Scope[]	getScopes() Get the scopes which the client application requests by "scope" request parameter.
Service	getService() Get the information about the service.
String	getSubject() Get the subject (= end-user's unique ID) that the client application requests.
String	getTicket() Get the ticket which has been issued to the service implementation from Authlete's /auth/authorization API.
String[]	getUiLocales() Get the list of preferred languages and scripts for the user interface.
String	getUserInfoClaims() Get the value of the "userinfo" property in the "claims" request parameter or in the "claims" property in a request object.
boolean	isAcrEssential() Get the flag which indicates whether the end-user authentication must satisfy one of the requested ACRs.
boolean	isClientIdAliasUsed() Get the flag which indicates whether the value of the client_id request parameter included in the authorization request is the client ID alias or the original numeric client ID.
void	setAcrEssential(boolean essential) Set the flag which indicates whether the end-user authentication must satisfy one of the requested ACRs.
void	setAcrs(String[] acrs) Set the list of ACRs (Authentication Context Class References) requested by the client application.
void	setAction(AuthorizationResponse.Action action) Set the next action that the service implementation should take.
void	setAuthorizationDetails(AuthzDetails details) Set the authorization details.
void	setClaims(String[] claims) Set the list of claims that the client application requests to be embedded in the ID token.
void	setClaimsLocales(String[] claimsLocales) Set the list of preferred languages and scripts for claim values contained in the ID token.
void	setClient(Client client) Set the information about the client application which has made the authorization request.
void	setClientIdAliasUsed(boolean used) Set the flag which indicates whether the value of the client_id request parameter included in the authorization request is the client ID alias or the original numeric client ID.
void	setDisplay(Display display) Set the display mode which the client application requires by "display" request parameter.
void	setIdTokenClaims(String idTokenClaims) Set the value of the "id_token" property in the "claims" request parameter or in the "claims" property in a request object.
void	setLoginHint(String loginHint) Set the value of login hint, which is specified by the client application using "login_hint" request parameter.
void	setLowestPrompt(Prompt prompt) Set the prompt that the UI displayed to the end-user must satisfy at least.
void	setMaxAge(int maxAge) Set the maximum authentication age.
void	setPrompts(Prompt[] prompts) Set the list of prompts contained in the authorization request (= the value of prompt request parameter).
void	setPurpose(String purpose) Set the value of the purpose request parameter.
void	setRequestObjectPayload(String payload) Set the payload part of the request object.
void	setResources(URI[] resources) Set the resources specified by the resource request parameters or by the resource property in the request object.
void	setResponseContent(String content) Set the response content which can be used to generate a response to the client application.
void	setScopes(Scope[] scopes) Set the scopes which the client application requests or the default scopes when the authorization request does not contain "scope" request parameter.
void	setService(Service service) Set the information about the service.
void	setSubject(String subject) Set the subject (= end-user's login ID) that the client application requests.
void	setTicket(String ticket) Set the ticket for the service implementation to call /auth/authorization/issue API and /auth/authorization/fail API.
void	setUiLocales(String[] uiLocales) Set the list of preferred languages and scripts for the user interface.
void	setUserInfoClaims(String userInfoClaims) Set the value of the "userinfo" property in the "claims" request parameter or in the "claims" property in a request object.
String	summarize() Get the summary of this instance.

Methods inherited from class com.authlete.common.dto.ApiResponse

getResultCode, getResultMessage, setResultCode, setResultMessage

Methods inherited from class java.lang.Object

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

Constructor Detail

AuthorizationResponse

public AuthorizationResponse()

Method Detail

getAction

public AuthorizationResponse.Action getAction()

Get the next action that the service implementation should take.

setAction

public void setAction(AuthorizationResponse.Action action)

Set the next action that the service implementation should take.

getService

public Service getService()

Get the information about the service.

Returns:

Information about the service.

Since:

1.23

setService

public void setService(Service service)

Set the information about the service.

Parameters:

service - Information about the service.

Since:

1.23

getClient

public Client getClient()

Get the information about the client application which has made the authorization request.

See Also:

OpenID Connect Dynamic Client Registration 1.0

setClient

public void setClient(Client client)

Set the information about the client application which has made the authorization request.

getDisplay

public Display getDisplay()

Get the display mode which the client application requests by "display" request parameter. When the authorization request does not contain "display" request parameter, this method returns Display.PAGE as the default value.

See Also:

OpenID Connect Core 1.0, 3.1.2.1. Authentication Request

setDisplay

public void setDisplay(Display display)

Set the display mode which the client application requires by "display" request parameter.

getMaxAge

public int getMaxAge()

Get the maximum authentication age which is the allowable elapsed time in seconds since the last time the end-user was actively authenticated by the service implementation. The value comes from "max_age" request parameter or "default_max_age" configuration parameter of the client application. 0 may be returned which means that the max age constraint does not have to be imposed.

See Also:

OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata

setMaxAge

public void setMaxAge(int maxAge)

Set the maximum authentication age.

getScopes

public Scope[] getScopes()

Get the scopes which the client application requests by "scope" request parameter. When the authorization request does not contain "scope" request parameter, this method returns a list of scopes which are marked as default by the service implementation. null may be returned if the authorization request does not contain valid scopes and none of registered scopes is marked as default.

You may want to enable end-users to select/deselect scopes in the authorization page. In other words, you may want to use a different set of scopes than the set specified by the original authorization request. You can replace scopes when you call Authlete's /auth/authorization/issue API. See the description of AuthorizationIssueRequest.setScopes(String[]) for details.

See Also:

OAuth 2.0, 3.3. Access Token Scope

setScopes

public void setScopes(Scope[] scopes)

Set the scopes which the client application requests or the default scopes when the authorization request does not contain "scope" request parameter.

You may want to enable end-users to select/deselect scopes in the authorization page. In other words, you may want to use a different set of scopes than the set specified by the original authorization request. You can replace scopes when you call Authlete's /auth/authorization/issue API. See the description of AuthorizationIssueRequest.setScopes(String[]) for details.

getUiLocales

public String[] getUiLocales()

Get the list of preferred languages and scripts for the user interface. The value comes from "ui_locales" request parameter.

See Also:

OpenID Connect Core 1.0, 3.1.2.1. Authentication Request

setUiLocales

public void setUiLocales(String[] uiLocales)

Set the list of preferred languages and scripts for the user interface.

getClaimsLocales

public String[] getClaimsLocales()

Get the list of preferred languages and scripts for claim values contained in the ID token. The value comes from "claims_locales" request parameter.

See Also:

OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts

setClaimsLocales

public void setClaimsLocales(String[] claimsLocales)

Set the list of preferred languages and scripts for claim values contained in the ID token.

getClaims

public String[] getClaims()

Get the list of claims that the client application requests to be embedded in the ID token. The value comes from "scope" and "claims" request parameters of the original authorization request.

See Also:

OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values, OpenID Connect Core 1.0, 5.5. Requesting Claims using the "claims" Request Parameter

setClaims

public void setClaims(String[] claims)

Set the list of claims that the client application requests to be embedded in the ID token.

isAcrEssential

public boolean isAcrEssential()

Get the flag which indicates whether the end-user authentication must satisfy one of the requested ACRs.

This method returns true only when the authorization request from the client contains "claim" request parameter and it contains an entry for "acr" claim with "essential":true.

See Also:

OpenID Connect Core 1.0, 5.5.1. Individual Claims Requests

setAcrEssential

public void setAcrEssential(boolean essential)

Set the flag which indicates whether the end-user authentication must satisfy one of the requested ACRs.

isClientIdAliasUsed

public boolean isClientIdAliasUsed()

Get the flag which indicates whether the value of the client_id request parameter included in the authorization request is the client ID alias or the original numeric client ID.

Since:

2.3

setClientIdAliasUsed

public void setClientIdAliasUsed(boolean used)

Set the flag which indicates whether the value of the client_id request parameter included in the authorization request is the client ID alias or the original numeric client ID.

Since:

2.3

getAcrs

public String[] getAcrs()

Get the list of ACRs (Authentication Context Class References) requested by the client application. The value come from (1) "acr" claim in "claims" request parameter, (2) "acr_values" request parameter, or (3) "default_acr_values" configuration parameter of the client application.

See Also:

OpenID Connect Core 1.0, 5.5. Requesting Claims using the "claims" Request Parameter, OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata

setAcrs

public void setAcrs(String[] acrs)

Set the list of ACRs (Authentication Context Class References) requested by the client application.

getSubject

public String getSubject()

Get the subject (= end-user's unique ID) that the client application requests. The value comes from "sub" claim in "claims" request parameter. This method may return null (probably in most cases).

See Also:

OpenID Connect Core 1.0, 5.5. Requesting Claims using the "claims" Request Parameter

setSubject

public void setSubject(String subject)

Set the subject (= end-user's login ID) that the client application requests.

getLoginHint

public String getLoginHint()

Get the value of login hint, which is specified by the client application using "login_hint" request parameter.

See Also:

OpenID Connect Core 1.0, 3.1.2.1. Authentication Request

setLoginHint

public void setLoginHint(String loginHint)

Set the value of login hint, which is specified by the client application using "login_hint" request parameter.

getLowestPrompt

@Deprecated
public Prompt getLowestPrompt()

Deprecated.

Get the prompt that the UI displayed to the end-user must satisfy at least. The value comes from "prompt" request parameter. When the authorization request does not contain "prompt" parameter, this method returns CONSENT as the default value.

This method is deprecated. Use getPrompts() instead.

See Also:

OpenID Connect Core 1.0, 3.1.2.1. Authentication Request

setLowestPrompt

public void setLowestPrompt(Prompt prompt)

Set the prompt that the UI displayed to the end-user must satisfy at least.

getPrompts

public Prompt[] getPrompts()

Get the list of prompts contained in the authorization request (= the value of prompt request parameter).

Returns:

The list of prompts contained in the authorization request.

Since:

1.34

See Also:

OpenID Connect Core 1.0, 3.1.2.1. Authentication Request

setPrompts

public void setPrompts(Prompt[] prompts)

Set the list of prompts contained in the authorization request (= the value of prompt request parameter).

Parameters:

prompts - The list of prompts contained in the authorization request.

Since:

1.34

getRequestObjectPayload

public String getRequestObjectPayload()

Get the payload part of the request object.

This method returns null if the authorization request does not include a request object.

Returns:

The payload part of the request object in JSON format.

Since:

2.22

setRequestObjectPayload

public void setRequestObjectPayload(String payload)

Set the payload part of the request object.

Parameters:

payload - The payload part of the request object in JSON format.

Since:

2.22

getIdTokenClaims

public String getIdTokenClaims()

Get the value of the "id_token" property in the "claims" request parameter or in the "claims" property in a request object.

A client application may request certain claims be embedded in an ID token or in a response from the UserInfo endpoint. There are several ways. Including the claims request parameter and including the claims property in a request object are such examples. In both the cases, the value of the claims parameter/property is JSON. Its format is described in 5.5. Requesting Claims using the "claims" Request Parameter of OpenID Connect Core 1.0.

The following is an excerpt from the specification. You can find "userinfo" and "id_token" are top-level properties.

 {
  "userinfo":
   {
    "given_name": {"essential": true},
    "nickname": null,
    "email": {"essential": true},
    "email_verified": {"essential": true},
    "picture": null,
    "http://example.info/claims/groups": null
  },
 "id_token":
  {
   "auth_time": {"essential": true},
   "acr": {"values": ["urn:mace:incommon:iap:silver"] }
  }
 }
 

This method (getIdTokenClaims()) returns the value of the "id_token" property in JSON format. For example, if the JSON above is included in an authorization request, this method returns JSON equivalent to the following.

  {
   "auth_time": {"essential": true},
   "acr": {"values": ["urn:mace:incommon:iap:silver"] }
  }
 

Note that if a request object is given and it contains the claims property and if the claims request parameter is also given, this method returns the value in the former.

Returns:

The value of the "id_token" property in the "claims" in JSON format.

Since:

2.25

setIdTokenClaims

public void setIdTokenClaims(String idTokenClaims)

Set the value of the "id_token" property in the "claims" request parameter or in the "claims" property in a request object.

Parameters:

idTokenClaims - The value of the "id_token" property in the "claims" in JSON format.

Since:

2.25

getUserInfoClaims

public String getUserInfoClaims()

Get the value of the "userinfo" property in the "claims" request parameter or in the "claims" property in a request object.

A client application may request certain claims be embedded in an ID token or in a response from the UserInfo endpoint. There are several ways. Including the claims request parameter and including the claims property in a request object are such examples. In both the cases, the value of the claims parameter/property is JSON. Its format is described in 5.5. Requesting Claims using the "claims" Request Parameter of OpenID Connect Core 1.0.

The following is an excerpt from the specification. You can find "userinfo" and "id_token" are top-level properties.

 {
  "userinfo":
   {
    "given_name": {"essential": true},
    "nickname": null,
    "email": {"essential": true},
    "email_verified": {"essential": true},
    "picture": null,
    "http://example.info/claims/groups": null
  },
 "id_token":
  {
   "auth_time": {"essential": true},
   "acr": {"values": ["urn:mace:incommon:iap:silver"] }
  }
 }
 

This method (getUserInfoClaims()) returns the value of the "userinfo" property in JSON format. For example, if the JSON above is included in an authorization request, this method returns JSON equivalent to the following.

   {
    "given_name": {"essential": true},
    "nickname": null,
    "email": {"essential": true},
    "email_verified": {"essential": true},
    "picture": null,
    "http://example.info/claims/groups": null
  }
 

Note that if a request object is given and it contains the claims property and if the claims request parameter is also given, this method returns the value in the former.

Returns:

The value of the "userinfo" property in the "claims" in JSON format.

Since:

2.25

setUserInfoClaims

public void setUserInfoClaims(String userInfoClaims)

Set the value of the "userinfo" property in the "claims" request parameter or in the "claims" property in a request object.

Parameters:

userInfoClaims - The value of the "userinfo" property in the "claims" in JSON format.

Since:

2.25

getResources

public URI[] getResources()

Get the resources specified by the resource request parameters or by the resource property in the request object. If both are given, the values in the request object take precedence. See "Resource Indicators for OAuth 2.0" for details.

Returns:

Target resources.

Since:

2.62

setResources

public void setResources(URI[] resources)

Set the resources specified by the resource request parameters or by the resource property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details.

Parameters:

resources - Target resources.

Since:

2.62

getAuthorizationDetails

public AuthzDetails getAuthorizationDetails()

Get the authorization details. This represents the value of the "authorization_details" request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".

Returns:

Authorization details.

Since:

2.56

setAuthorizationDetails

public void setAuthorizationDetails(AuthzDetails details)

Set the authorization details. This represents the value of the "authorization_details" request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".

Parameters:

details - Authorization details.

Since:

2.56

getPurpose

public String getPurpose()

Get the value of the purpose request parameter.

The purpose request parameter is defined in 8. Transaction-specific Purpose of OpenID Connect for Identity Assurance 1.0 as follows:

purpose OPTIONAL. String describing the purpose for obtaining certain user data from the OP. The purpose MUST NOT be shorter than 3 characters and MUST NOT be longer than 300 characters. If these rules are violated, the authentication request MUST fail and the OP returns an error invalid_request to the RP.

NOTE: This method works only when Authlete server you are using supports OpenID Connect for Identity Assurance 1.0.

Returns:

The value of the purpose request parameter.

Since:

2.63

See Also:

OpenID Connect for Identity Assurance 1.0, 8. Transaction-specific Purpose

setPurpose

public void setPurpose(String purpose)

Set the value of the purpose request parameter.

The purpose request parameter is defined in 8. Transaction-specific Purpose of OpenID Connect for Identity Assurance 1.0 as follows:

purpose OPTIONAL. String describing the purpose for obtaining certain user data from the OP. The purpose MUST NOT be shorter than 3 characters and MUST NOT be longer than 300 characters. If these rules are violated, the authentication request MUST fail and the OP returns an error invalid_request to the RP.

Parameters:

purpose - The value of the purpose request parameter.

Since:

2.63

See Also:

OpenID Connect for Identity Assurance 1.0, 8. Transaction-specific Purpose

getResponseContent

public String getResponseContent()

Get the response content which can be used to generate a response to the client application. The format of the value varies depending on the value of "action".

setResponseContent

public void setResponseContent(String content)

Set the response content which can be used to generate a response to the client application.

getTicket

public String getTicket()

Get the ticket which has been issued to the service implementation from Authlete's /auth/authorization API. This ticket is needed for /auth/authorization/issue API and /auth/authorization/fail API.

setTicket

public void setTicket(String ticket)

Set the ticket for the service implementation to call /auth/authorization/issue API and /auth/authorization/fail API.

summarize

public String summarize()

Get the summary of this instance.