public class AuthorizationResponse extends ApiResponse
/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.
[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 withreason=
NOT_LOGGED_IN
and use the response from the API to generate a response to the client application.
[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.
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 withreason=
MAX_AGE_NOT_SUPPORTED
and use the response from the API to generate a response to the client application.
Add the value of the maximum authentication age (which is represented in seconds) to the authentication time.
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 withreason=
EXCEEDS_MAX_AGE
and use the response from the API to generate a response to the client application.
[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 isnull
, go to the next step ([ACRs]). Otherwise, follow the sub steps described below.
Compare the value of the requested subject to the subject (= unique user ID) of the current end-user.
If they are equal, go to the next step ([ACRs]).
If they are not equal, call Authlete's
/auth/authorization/fail
API withreason=
DIFFERENT_SUBJECT
and use the response from the API to generate a response to the client application.
[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.
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"
.)
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]).
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. IfisAcrEssential()
returnstrue
, call Authlete's/auth/authorization/fail
API withreason=
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]).
[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 withreason=
CONSENT_REQUIRED
and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([DYNAMIC SCOPES]).
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 return403 Forbidden
.
[DYNAMIC SCOPES] Get the dynamic scopes by
getDynamicScopes()
. 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 withreason=
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 dynamic scopes are not remembered as granted scopes.
See the description of the
DynamicScope
class for details about dynamic scopes.
[RESOURCES] Get the requested target resources by
getResources()
. The array represents the values of theresource
request parameters. If you want to reject the request, call Authlete's/auth/authorization/fail
API withreason=
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.
[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 ofAuthorizationIssueRequest
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 bygetTicket()
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 ofsubject
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 isPAIRWISE
, the value of"sub"
claim is different from the value specified here. Note that the behavior forPAIRWISE
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 thesub
claim in an ID token. See the description of thesub
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 andisAcrEssential()
method returnstrue
, the value of this parameter must be one of the array elements. Otherwise, evennull
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. WhengetClaimsLocales()
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 returnsnull
or an empty array, the value of this parameter should benull
.
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
isapplication/json
, so don't useapplication/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 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 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 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.
/auth/authorization/issue
API returns a response in JSON format which can be mapped toAuthorizationIssueResponse
. Use the response from the API to generate a response to the client application. See the description ofAuthorizationIssueResponse
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.
[DISPLAY MODE]
AuthorizationResponse
contains"display"
parameter. The value can be obtained bygetDisplay()
method and is one ofPAGE
(default),POPUP
,TOUCH
andWAP
. 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.
[UI LOCALE]
AuthorizationResponse
contains"ui_locales"
parameter. The value can be obtained bygetUiLocales()
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.
[CLIENT INFORMATION] The authorization server implementation should show the end-user information about the client application. The information can be obtained by
getClient()
method.
[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()
containsCONSENT
, 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 return403 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.
[DYNAMIC SCOPES] The authorization request may include dynamic scopes. The list of recognized dynamic scopes are accessible by
getDynamicScopes()
method. See the description of theDynamicScope
class for details about dynamic scopes.
[AUTHORIZATION DETAILS] The authorization server implementation should show the end-user "authorization details" if the request includes it.
getAuthorizationDetails()
returns the content of theauthorization_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.
[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 thepurpose
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.
[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.)
Get the value of
getPrompts()
. It corresponds to the value of theprompt
request parameter. Details of the request parameter are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0.
If the value returned from
getPrompts()
containsSELECT_ACCOUNT
, display a form to urge the end-user to select one of his/her accounts for login. IfgetSubject()
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. IfgetSubject()
returns null, the value returned bygetLoginHint()
should be referred to as a hint to determine the value of the login ID.getLoginHint()
method simply returns the value of thelogin_hint
request parameter.
If the value returned from
getPrompts()
containsLOGIN
, display a form to urge the end-user to login even if the end-user has already logged in. IfgetSubject()
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. IfgetSubject()
returns null, the value returned bygetLoginHint()
should be referred to as a hint to determine the value of the login ID.getLoginHint()
method simply returns the value of thelogin_hint
request parameter.
If the value returned from
getPrompts()
does not containLOGIN
, 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 whengetSubject()
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 whengetMaxAge()
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 whengetAcrs()
returns a non-empty array.
In every case, the end-user authentication must satisfy one of the ACRs listed by
getAcrs()
whengetAcrs()
returns a non-empty array andisAcrEssential()
returnstrue
.
[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
.
Authlete 2.3 and newer versions support Grant Management for
OAuth 2.0. An authorization request may contain a grant_id
request parameter which is defined in the specification. If the value of
the request parameter is valid, getGrantSubject()
will return the
subject of the user who has given the grant to the client application.
Authorization server implementations may use the value returned from
getGrantSubject()
in order to determine the user to authenticate.
Authlete 2.3 and newer version support "Transformed Claims". An
authorization request may request "transformed claims". A transformed
claim uses an existing claim as input. For example, an authorization server
may predefine a transformed claim named 18_or_over
which uses the
birthdate
claim as input. If a client application requests the
18_or_over
transformed claim, the authorization server needs to
prepare the value of the birthdate
claim and passes it to Authlete's
/api/auth/authorization/issue
API so that Authlete can compute the
value of the 18_or_over
transformed claim. See the descriptions
of getRequestedClaimsForTx()
and getRequestedVerifiedClaimsForTx()
for details.
Modifier and Type | Class and Description |
---|---|
static class |
AuthorizationResponse.Action
The next action that the service implementation should take.
|
Constructor and Description |
---|
AuthorizationResponse() |
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. |
DynamicScope[] |
getDynamicScopes()
Get the dynamic scopes which the client application requested
by the
scope request parameter. |
GMAction |
getGmAction()
Get the value of the
grant_management_action request parameter. |
Grant |
getGrant()
Get the content of the grant which is identified by the
grant_id
request parameter. |
String |
getGrantId()
Get the value of the
grant_id request parameter. |
String |
getGrantSubject()
Get the subject of the user who has given the grant which is identified
by the
grant_id 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[] |
getRequestedClaimsForTx()
Get names of claims that are requested indirectly by "transformed
claims".
|
StringArray[] |
getRequestedVerifiedClaimsForTx()
Get names of verified claims that are requested indirectly by
"transformed claims".
|
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 |
getTransformedClaims()
Get the value of the
"transformed_claims" property in the
"claims" request parameter or in the "claims" property
in a request object. |
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 |
isClientEntityIdUsed()
Get the flag which indicates whether the value of the
client_id
request parameter included in the authorization request is the entity
ID of the client. |
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. |
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 |
setClientEntityIdUsed(boolean used)
Set the flag which indicates whether the value of the
client_id
request parameter included in the authorization request is the entity
ID of the client. |
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. |
void |
setDisplay(Display display)
Set the display mode which the client application requires
by
"display" request parameter. |
void |
setDynamicScopes(DynamicScope[] dynamicScopes)
Set the dynamic scopes which the client application requested
by the
scope request parameter. |
void |
setGmAction(GMAction action)
Set the value of the
grant_management_action request parameter. |
void |
setGrant(Grant grant)
Set the content of the grant which is identified by the
grant_id
request parameter. |
void |
setGrantId(String grantId)
Set the value of the
grant_id request parameter. |
void |
setGrantSubject(String subject)
Set the subject of the user who has given the grant which is identified
by the
grant_id 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 |
setRequestedClaimsForTx(String[] claims)
Set names of claims that are requested indirectly by "transformed
claims".
|
void |
setRequestedVerifiedClaimsForTx(StringArray[] claimsArray)
Set names of verified claims that are requested indirectly by
"transformed claims".
|
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 |
setTransformedClaims(String transformedClaims)
Set the value of the
"transformed_claims" property in the
"claims" request parameter or in the "claims" property
in a request object. |
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.
|
getResultCode, getResultMessage, setResultCode, setResultMessage
public AuthorizationResponse.Action getAction()
public void setAction(AuthorizationResponse.Action action)
public Service getService()
public void setService(Service service)
service
- Information about the service.public Client getClient()
public void setClient(Client client)
public Display getDisplay()
"display"
request parameter. When the authorization
request does not contain "display"
request parameter,
this method returns Display.PAGE
as the default value.public void setDisplay(Display display)
"display"
request parameter.public int getMaxAge()
"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.public void setMaxAge(int maxAge)
public Scope[] getScopes()
"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.
public void setScopes(Scope[] scopes)
"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.
public DynamicScope[] getDynamicScopes()
scope
request parameter. See the description of
DynamicScope
for details.DynamicScope
public void setDynamicScopes(DynamicScope[] dynamicScopes)
scope
request parameter. See the description of
DynamicScope
for details.dynamicScopes
- The list of dynamic scopes.DynamicScope
public String[] getUiLocales()
"ui_locales"
request
parameter.public void setUiLocales(String[] uiLocales)
public String[] getClaimsLocales()
"claims_locales"
request parameter.public void setClaimsLocales(String[] claimsLocales)
public String[] getClaims()
"scope"
and "claims"
request parameters of
the original authorization request.public void setClaims(String[] claims)
public boolean isAcrEssential()
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
.
public void setAcrEssential(boolean essential)
public boolean isClientIdAliasUsed()
client_id
request parameter included in the authorization request is the client
ID alias.public void setClientIdAliasUsed(boolean used)
client_id
request parameter included in the authorization request is the client
ID alias.public boolean isClientEntityIdUsed()
client_id
request parameter included in the authorization request is the entity
ID of the client.
"Entity ID" is a technical term defined in OpenID Connect Federation 1.0.
When this flag is true
, client.
getEntityId()
returns the entity ID of the client.
true
if the value of the client_id
request
parameter is the entity ID of the client.public void setClientEntityIdUsed(boolean used)
client_id
request parameter included in the authorization request is the entity
ID of the client.
"Entity ID" is a technical term defined in OpenID Connect Federation 1.0.
When this flag is true
, client.
getEntityId()
returns the entity ID of the client.
used
- true
to indicate that the value of the client_id
request parameter is the entity ID of the client.public String[] getAcrs()
"acr"
claim in "claims"
request parameter, (2)
"acr_values"
request parameter, or (3) "default_acr_values"
configuration parameter of the client
application.public void setAcrs(String[] acrs)
public String getSubject()
"sub"
claim in "claims"
request parameter. This method
may return null
(probably in most cases).public void setSubject(String subject)
public String getLoginHint()
"login_hint"
request parameter.public void setLoginHint(String loginHint)
"login_hint"
request parameter.@Deprecated public Prompt getLowestPrompt()
"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.
public void setLowestPrompt(Prompt prompt)
public Prompt[] getPrompts()
prompt
request parameter).public void setPrompts(Prompt[] prompts)
prompt
request parameter).prompts
- The list of prompts contained in the authorization request.public String getRequestObjectPayload()
This method returns null
if the authorization request does not
include a request object.
public void setRequestObjectPayload(String payload)
payload
- The payload part of the request object in JSON format.public String getIdTokenClaims()
"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.
"id_token"
property in the
"claims"
in JSON format.public void setIdTokenClaims(String idTokenClaims)
"id_token"
property in the "claims"
request parameter or in the "claims"
property in a request object.idTokenClaims
- The value of the "id_token"
property in the
"claims"
in JSON format.public String getUserInfoClaims()
"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.
"userinfo"
property in the
"claims"
in JSON format.public void setUserInfoClaims(String userInfoClaims)
"userinfo"
property in the "claims"
request parameter or in the "claims"
property in a request object.userInfoClaims
- The value of the "userinfo"
property in the
"claims"
in JSON format.public String getTransformedClaims()
"transformed_claims"
property in the
"claims"
request parameter or in the "claims"
property
in a request object."transformed_claims"
property in the
"claims"
in JSON format.public void setTransformedClaims(String transformedClaims)
"transformed_claims"
property in the
"claims"
request parameter or in the "claims"
property
in a request object.transformedClaims
- The value of the "transformed_claims"
property in the
"claims"
in JSON format.public URI[] getResources()
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.public void setResources(URI[] resources)
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.resources
- Target resources.public AuthzDetails getAuthorizationDetails()
"authorization_details"
request parameter which is defined in
"OAuth 2.0 Rich Authorization Requests".public void setAuthorizationDetails(AuthzDetails details)
"authorization_details"
request parameter which is defined in
"OAuth 2.0 Rich Authorization Requests".details
- Authorization details.public String getPurpose()
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 errorinvalid_request
to the RP.
NOTE: This method works only when Authlete server you are using supports OpenID Connect for Identity Assurance 1.0.
purpose
request parameter.public void setPurpose(String purpose)
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 errorinvalid_request
to the RP.
purpose
- The value of the purpose
request parameter.public GMAction getGmAction()
grant_management_action
request parameter.
The grant_management_action
request parameter is defined in
Grant
Management for OAuth 2.0, which is supported by Authlete 2.3 and
newer versions.
null
or one of
CREATE
, REPLACE
and MERGE
.public void setGmAction(GMAction action)
grant_management_action
request parameter.
The grant_management_action
request parameter is defined in
Grant
Management for OAuth 2.0, which is supported by Authlete 2.3 and
newer versions.
action
- A grant management action. null
or one of
CREATE
, REPLACE
and MERGE
.public String getGrantId()
grant_id
request parameter.
The grant_id
request parameter is defined in
Grant
Management for OAuth 2.0, which is supported by Authlete 2.3 and
newer versions.
public void setGrantId(String grantId)
grant_id
request parameter.
The grant_id
request parameter is defined in
Grant
Management for OAuth 2.0, which is supported by Authlete 2.3 and
newer versions.
grantId
- A grant ID.public String getGrantSubject()
grant_id
request parameter.
Authlete 2.3 and newer versions support Grant Management
for OAuth 2.0. An authorization request may contain a grant_id
request parameter which is defined in the specification. If the value of
the request parameter is valid, getGrantSubject()
will return
the subject of the user who has given the grant to the client application.
Authorization server implementations may use the value returned from
getGrantSubject()
in order to determine the user to authenticate.
The user your system will authenticate during the authorization process
(or has already authenticated) may be different from the user of the
grant. The first implementer's draft of "Grant Management for OAuth 2.0"
does not mention anything about the case, so the behavior in the case is
left to implementations. Authlete will not perform the grant management
action when the subject
passed to Authlete does not match the
user of the grant.
public void setGrantSubject(String subject)
grant_id
request parameter.
Authlete 2.3 and newer versions support Grant Management
for OAuth 2.0. An authorization request may contain a grant_id
request parameter which is defined in the specification. If the value of
the request parameter is valid, getGrantSubject()
will return
the subject of the user who has given the grant to the client application.
Authorization server implementations may use the value returned from
getGrantSubject()
in order to determine the user to authenticate.
The user your system will authenticate during the authorization process
(or has already authenticated) may be different from the user of the
grant. The first implementer's draft of "Grant Management for OAuth 2.0"
does not mention anything about the case, so the behavior in the case is
left to implementations. Authlete will not perform the grant management
action when the subject
passed to Authlete does not match the
user of the grant.
subject
- The subject of the user who has given the grant.public Grant getGrant()
grant_id
request parameter.
The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. Be careful when your system displays the content of the grant.
public void setGrant(Grant grant)
grant_id
request parameter.
The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. Be careful when your system displays the content of the grant.
grant
- The content of the grant.public String[] getRequestedClaimsForTx()
A client application can request "transformed claims" by adding
names of transformed claims in the claims
request parameter.
The following is an example of the claims
request parameter
that requests a predefined transformed claim named 18_or_over
and a transformed claim named nationality_usa
to be embedded
in an ID Token.
{ "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "id_token": { "::18_or_over": null, ":nationality_usa": null } }
The example above assumes that a transformed claim named 18_or_over
is predefined by the authorization server like below.
{ "18_or_over": { "claim": "birthdate", "fn": [ "years_ago", [ "gte", 18 ] ] } }
In the example, the nationalities
claim is requested indirectly
by the nationality_usa
transformed claim. Likewise, the
birthdate
claim is requested indirectly by the 18_or_over
transformed claim.
When the claims
request parameter of an authorization request is
like the example above, this requestedClaimsForTx
property will
hold the following value.
[ "birthdate", "nationalities" ]
It is expected that the authorization server implementation prepares values
of the listed claims and passes them as the value of the claimsForTx
request parameter when it calls the /api/auth/authorization/issue
API (cf. AuthorizationIssueRequest.setClaimsForTx(String)
). The
following is an example of the value of the claimsForTx
request
parameter.
{ "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] }
This requestedClaimsForTx
property is available from Authlete 2.3
onwards.
public void setRequestedClaimsForTx(String[] claims)
See the description of getRequestedClaimsForTx()
for details.
claims
- Names of claims that are requested indirectly by
"transformed claims"getRequestedClaimsForTx()
public StringArray[] getRequestedVerifiedClaimsForTx()
A client application can request "transformed claims" by adding
names of transformed claims in the claims
request parameter.
The following is an example of the claims
request parameter
that requests a predefined transformed claim named 18_or_over
and a transformed claim named nationality_usa
to be embedded
in an ID Token.
{ "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "id_token": { "verified_claims": { "verification": { "trust_framework": null }, "claims": { "::18_or_over": null, ":nationality_usa": null } } } }
The example above assumes that a transformed claim named 18_or_over
is predefined by the authorization server like below.
{ "18_or_over": { "claim": "birthdate", "fn": [ "years_ago", [ "gte", 18 ] ] } }
In the example, the nationalities
claim is requested indirectly
by the nationality_usa
transformed claim. Likewise, the
birthdate
claim is requested indirectly by the 18_or_over
transformed claim.
When the claims
request parameter of an authorization request is
like the example above, this requestedVerifiedClaimsForTx
property
will hold the following value.
[ { "array": [ "birthdate", "nationalities" ] } ]
It is expected that the authorization server implementation prepares
values of the listed verified claims and passes them as the value of
the verifiedClaimsForTx
request parameter when it calls the
/api/auth/authorization/issue
API (cf.
AuthorizationIssueRequest.setVerifiedClaimsForTx(String[])
).
The following is an example of the value of the
verifiedClaimsForTx
request parameter.
[ "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" ]
The reason that this requestedVerifiedClaimsForTx
property and
the verifiedClaimsForTx
request parameter are arrays is that
the "verified_claims"
property in the claims
request
parameter 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 } } ] } }
The order of elements in requestedVerifiedClaimsForTx
matches
the order of elements in the "verified_claims"
array.
This requestedVerifiedClaimsForTx
property is available from
Authlete 2.3 onwards.
public void setRequestedVerifiedClaimsForTx(StringArray[] claimsArray)
See the description of getRequestedVerifiedClaimsForTx()
for
details.
This requestedVerifiedClaimsForTx
property is available from
Authlete 2.3 onwards.
claimsArray
- Names of verified claims that are requested indirectly by
"transformed claims"getRequestedVerifiedClaimsForTx()
public String getResponseContent()
"action"
.public void setResponseContent(String content)
public String getTicket()
/auth/authorization
API. This ticket is
needed for /auth/authorization/issue
API and
/auth/authorization/fail
API.public void setTicket(String ticket)
/auth/authorization/issue
API and
/auth/authorization/fail
API.public String summarize()
Copyright © 2023. All rights reserved.