Table of Contents
This is the first generally available version of Authlete 2.2. It includes the following new or enhanced features.
Authlete 2.2 supports the final version of the “Financial-grade API (FAPI)” which was approved in January, 2021.
The final version has some differences over the Implementer’s Draft 2 (October, 2018). The following revised provisions may affect to existing FAPI-enabled systems. Please note that configuration and source codes of software you are using may need updating accordingly.
nbfclaim, and their duration (diff between
nbf) must be no longer than 60 minutes.
“nbf Claim” is a new configuration item in Authlete 2.2 for smooth migration from the final version to the Implementer’s Draft 2 without breaking live systems. You can choose “Optional” to make the
nbf claim treated as optional even when an authorization request is regarded as a FAPI-Part2 request. That is, the authorization server does not perform validation on lifetime of the request object.
Note that setting “Optional” makes the authorization server violate the specification partly. This setting is intended to support existing FAPI-compliant client applications during migration, so it is recommended that you revert the setting back to “Required” after confirming that all client application implementations are enabled to embed an
nbf claim in request objects.
This configuration item corresponds to
Service.nbfOptional in the authlete-java-common library;
false mean “Optional” and “Required”, respectively.
Authlete 2.2 supports “JWT Secured Authorization Request (JAR).”
JAR is a successor of “Request Object” which is defined in OpenID Connect Core 1.0. It introduces some breaking changes as listed below. Please update configuration and source codes of software you are using as necessary.
response_typeparameter outside the request object is no longer mandatory.
scopeparameter outside the request object is no longer mandatory even when the
scopeclaim in the request object contains
See the following blog post for technical details of JAR and Authlete’s JAR support.
“Request Object Processing” is a new configuration item in Authlete 2.2 for smooth migration without breaking live systems.
You can choose “Backward compatible” to have Authlete process request objects in accordance with the rules of OpenID Connect Core 1.0. This configuration item corresponds to
Service.traditionalRequestObjectProcessingApplied in the authlete-java-common library;
false mean “Backward compatible” and “JAR compatible”, respectively.
Once confirming that all client application implementations get ready for JAR, it is recommended to revert the configuration back to “JAR compatible.”
When “Request Object Processing” is set to “JAR compatible” and “Request Object” is set to “Required”, the
require_signed_request_object metadata in the discovery document of the authorization server is
true. See the JAR specification for details about the metadata.
request_uri in an authorization request is one that has been issued from the “Pushed Authorization Request Endpoint” (which is defined in “OAuth 2.0 Pushed Authorization Requests”), the request object is processed with the JAR rules regardless of the setting of “Request Object Processing.”
Authlete 2.2 supports “OAuth 2.0 Pushed Authorization Requests (PAR).”
PAR is a mechanism that allows a client to register an authorization request into an authorization server before making an authorization request to an authorization endpoint.
See the following blog post for the overview of PAR.
“PAR Use” is a new configuration item in both Service and Client settings.
If “Mandatory” is set in Service configuration, the authorization server accepts authorization request data only via the PAR method. As a result, the authorization server will reject any authorization request without a request URI issued from the PAR endpoint.
If “Mandatory” is set in Client configuration, all authorization requests from the client must use the PAR method.
“PAR Use” in Service and Client correspond to the server metadata
require_pushed_authorization_requests and the client metadata
Authlete 2.2 supports “OAuth 2.0 Rich Authorization Requests (RAR).”
RAR is a mechanism that allows a client to include detailed information to an authorization request. The specification introduces a new parameter
authorization_details whose value is an array of JSON objects representing the detailed information. The
authorization_details parameter can be used where the
scope parameter can be used, for example, in authorization requests and token responses. In addition, Authlete supports the parameter at the backchannel authentication endpoint (CIBA) and the device authorization endpoint (RFC 8628) as well.
Before RAR is defined, details of an authorization request are represented in many ways. For example, some deployments have used a structured format to values of the
scope request parameter. The RAR specification standardizes how details of an authorization request is represented in a flexible manner.
“Supported Authorization Data Types” is a new Service configuration item to list supported values of the
type field of each element in
authorization_details. It corresponds to the server metadata
“Authorization Data Types” is a new Client configuration item to list value of the
type field of each element in
authorization_details that the client may use. It corresponds to the client metadata
Authlete 2.2 supports “OAuth 2.0 Demonstration of Proof-of-Posession at the Application Layer (DPoP).”
DPoP is a new “Proof-of-Possession” mechanism for access tokens, and can be used as an alternative when it is difficult to use “certificate binding” (RFC 8705).
See the following blog post for technical details of DPoP and Authlete’s DPoP support.
Authlete 2.2 supports the second Implementer’s Draft of “OpenID Connect for Identity Assurance 1.0 (IDA),” which was released on May 19, 2020.
IDA has been being developed for distribution of KYC results in a verifiable manner. See the following blog post for technical details of IDA and Authlete’s IDA support.
Authlete 2.2 supports “Resource Indicators for OAuth 2.0.”
“Resource Indicators for OAuth 2.0” is a mechanism that allows a client to specify audiences of access tokens. The specification adds a new request parameter
resource to authorization requests and token requests. In addition, Authlete’s implementation supports the request parameter at the backchannel authentication endpoint (CIBA) and the device authorization endpoint (RFC 8628) as well.
resources are set to the value of the
aud claim in an introspection response. Also, when the format of access token is JWT, they are set to the value of the
aud claim in the JWT. Note that the format of access tokens generated by Authlete becomes JWT by setting “Access Token Signature Algorithm”.
It is up to resource server implementations how to utilize the audience information of access tokens.
Authlete 2.2 supports “OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response.”
“OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response” defines a new authorization response parameter,
iss, as a countermeasure for a certain type of mix-up attackes.
The specification requires that the
iss response parameter always be included in authorization responses unless JARM (JWT Secured Authorization Response Mode) is used. A client application can ensure that the mix-up attack has not been made, by confirming that the value of the
iss parameter in the authorization response matches the identifier of the authorization server.
Note that if a client application communicates with just one authorization server, the client application does not have to worry about the mix-up attack and does not have to verify the
iss response parameter. See the specification for details.
“iss Response Parameter” is a new configuration item in Authlete 2.2. When “Suppressed” is selected, the authorization server does not include the
iss response parameter. This is for experiment purposes only - developers may be able to test the mix-up attack by suppressing the
iss response parameter.
When “Included” is selected, the
authorization_response_iss_parameter_supported metadata in the discovery document of the authorization server is
true. See the specification for details about the metadata.
This configuration item corresponds to
Service.issSuppressed in the authlete-java-common library;
false mean “Suppressed” and “Included”, respectively.
NOTE: Do not set “Suppressed” in production environment unless there are special reasons for it.
The following are other new configuration items added since the previous release. The list includes features that have been backported to previous versions.
When a request has no
scope parameter (or none of the given scopes is valid) and the service’s pre-defined default scope set is empty, the authorization server regards that the request requests no scope. When “Required” is set, such requests are rejected.
If “Restrictive” is selected, claims specified by shortcut scopes (e.g.
profile) are included in an ID token only when no access token is issued (only when
id_token). On the other hand, if “Nonrestrictive” is selected, the claims are always included in an ID token regardless of whether an access token is issued or not.
If “Mandatory” is selected, all authorization requests are required to utilize a request object.
If “Enabled” is selected, the remaining duration of the used refresh token is taken over to the newly issued one. The value of this configuration item does not have any effect when “Refresh Token Continuous Use” is “Enabled”.
This request parameter has been added to APIs that may issue an ID token. Arbitrary claims can be embedded into an ID token by using the request parameter.
This request parameter has been added to the
/api/auth/introspection/standard API. If
withHiddenProperties=true is given, properties whose
true also are included in introspection responses.
Maximum length of
subject request parameter has been updated from 100 to 255.