Package com.authlete.jaxrs.spi

Interface AuthorizationRequestHandlerSpi

All Known Implementing Classes:

AuthorizationRequestHandlerSpiAdapter

public interface AuthorizationRequestHandlerSpi

Service Provider Interface to work with AuthorizationRequestHandler.

An implementation of this interface must be given to the constructor of AuthorizationRequestHandler class.

Author:

Takahiko Kawasaki

Method Summary

Modifier and Type	Method	Description
javax.ws.rs.core.Response	generateAuthorizationPage(com.authlete.common.dto.AuthorizationResponse info)	Generate an authorization page (HTML) to ask an end-user whether to accept or deny an authorization request by a client application.
String	getAcr()	Get the authentication context class reference (ACR) that was satisfied when the current end-user was authenticated.
com.authlete.common.dto.Property[]	getProperties()	Get extra properties to associate with an access token and/or an authorization code.
String[]	getScopes()	Get scopes to associate with an access token and/or an authorization code.
String	getSub()	Get the value of the "sub" claim to be used in the id_token.
long	getUserAuthenticatedAt()	Get the time when the current end-user was authenticated in milliseconds since Unix epoch (1970-01-01).
String	getUserSubject()	Get the subject (= unique identifier) of the current end-user.
boolean	isUserAuthenticated()	Check whether an end-user has already logged in or not.

Method Detail

isUserAuthenticated

boolean isUserAuthenticated()

Check whether an end-user has already logged in or not.

This method is called only when an authorization request comes with prompt=none. Therefore, if you have no mind to support prompt=none, always return false. See 3.1.2.1. Authentication Request in OpenID Connect Core 1.0 for details about prompt=none.

Below is an example implementation using Apache Shiro.

 @Override
 public boolean isUserAuthenticated()
 {
     return SecurityUtils.getSubject().isAuthenticated();
 }

Returns:

true if an end-user has already logged in. Otherwise, false. When false is returned, the client application will receive error=login_required.

getUserAuthenticatedAt

long getUserAuthenticatedAt()

Get the time when the current end-user was authenticated in milliseconds since Unix epoch (1970-01-01).

The value is used to check whether the elapsed time since the last authentication has exceeded the maximum authentication age or not. See max_age in "3.1.2.1. Authentication Request" in OpenID Connect Core 1.0, and default_max_age in "2. Client Metadata" in OpenID Connect Dynamic Client Registration 1.0 for details.

This method is called only when an authorization request comes with prompt=none. Therefore, if you have no mind to support prompt=none, always return 0. See 3.1.2.1. Authentication Request in OpenID Connect Core 1.0 for details about prompt=none.

Below is an example implementation using Apache Shiro.

 @Override
 public long getUserAuthenticatedAt()
 {
     Session session = SecurityUtils.getSubject().getSession(false);

     if (session == null)
     {
         return 0;
     }

     return session.getStartTimestamp().getTime();
 }

Returns:

The time when the end-user was authenticated in seconds since Unix epoch (1970-01-01).

getUserSubject

String getUserSubject()

Get the subject (= unique identifier) of the current end-user. It must consist of only ASCII letters and its length must not exceed 100.

This method is called only when an authorization request comes with prompt=none. Therefore, if you have no mind to support prompt=none, always return null. See 3.1.2.1. Authentication Request in OpenID Connect Core 1.0 for details about prompt=none.

Below is an example implementation using Apache Shiro.

 @Override
 public long getUserAuthenticatedAt()
 {
     return (String)SecurityUtils.getSubject().getPrincipal();
 }

Returns:

The subject (= unique identifier) of the current end-user.

getAcr

String getAcr()

Get the authentication context class reference (ACR) that was satisfied when the current end-user was authenticated.

The value returned by this method has an important meaning only when acr claim is requested as an essential claim. See "5.5.1.1. Requesting the "acr" Claim" in OpenID Connect Core 1.0 if you are interested in the details.

This method is called only when an authorization request comes with prompt=none. Therefore, if you have no mind to support prompt=none, always return null. See 3.1.2.1. Authentication Request in OpenID Connect Core 1.0 for details about prompt=none.

If you don't know what ACR is, return null.

Returns:

The authentication context class reference (ACR) that was satisfied when the current end-user was authenticated.

generateAuthorizationPage

javax.ws.rs.core.Response generateAuthorizationPage(com.authlete.common.dto.AuthorizationResponse info)

Generate an authorization page (HTML) to ask an end-user whether to accept or deny an authorization request by a client application.

Key information that should be displayed in an authorization page is stored in the info object. For example, the name of the client application can be obtained by calling info.getClient().getClientName() method. Likewise, requested scopes can be obtained as an array of Scope objects by calling info.getScopes() method.

In an authorization page, an end-user will finally decide either to grant authorization to the client application or to reject the authorization request. The authorization server should receive the decision and call handle() method.

Parameters:

info - A response from Authlete's /api/auth/authorization API. Key information that should be displayed in an authorization page is stored in the object.

Returns:

A response to show an authorization page.

getProperties

com.authlete.common.dto.Property[] getProperties()

Get extra properties to associate with an access token and/or an authorization code.

This method is expected to return an array of extra properties. The following is an example that returns an array containing one extra property.

 @Override
 public Property[] getProperties()
 {
     return new Property[] {
         new Property("example_parameter", "example_value")
     };
 }

Extra properties returned from this method will appear as top-level entries in a JSON response from an authorization server as shown in 5.1. Successful Response in RFC 6749.

Keys listed below should not be used and they would be ignored on the server side even if they were used. It's because they are reserved in RFC 6749 and OpenID Connect Core 1.0.

• access_token
• token_type
• expires_in
• refresh_token
• scope
• error
• error_description
• error_uri
• id_token

Note that there is an upper limit on the total size of extra properties. On the server side, the properties will be (1) converted to a multidimensional string array, (2) converted to JSON, (3) encrypted by AES/CBC/PKCS5Padding, (4) encoded by base64url, and then stored into the database. The length of the resultant string must not exceed 65,535 in bytes. This is the upper limit, but we think it is big enough.

This method is called only when an authorization request comes with prompt=none. Therefore, if you have no mind to support prompt=none, always return null. See 3.1.2.1. Authentication Request in OpenID Connect Core 1.0 for details about prompt=none.

Returns:

Extra properties. If null is returned, any extra property will not be associated.

Since:

1.3

getScopes

String[] getScopes()

Get scopes to associate with an access token and/or an authorization code.

If null is returned, the scopes specified in the original authorization request from the client application are used. In other cases, including the case of an empty array, the specified scopes will replace the original scopes contained in the original authorization request.

Even scopes that are not included in the original authorization request can be specified. However, as an exception, "openid" scope is ignored on the server side if it is not included in the original request. It is because the existence of "openid" scope considerably changes the validation steps and because adding "openid" triggers generation of an ID token (although the client application has not requested it) and the behavior is a major violation against the specification.

If you add "offline_access" scope although it is not included in the original request, keep in mind that the specification requires explicit consent from the user for the scope (OpenID Connect Core 1.0, 11. Offline Access). When "offline_access" is included in the original request, the current implementation of Authlete's /api/auth/authorization API checks whether the request has come along with prompt request parameter and the value includes "consent". However, note that the implementation of Authlete's /api/auth/authorization/issue API does not perform such checking if "offline_access" scope is added via this scopes parameter.

Returns:

Scopes to associate with an authorization code and/or an access token. If a non-null value is set, the original scopes requested by the client application are replaced.

Since:

1.4

getSub

String getSub()

Get the value of the "sub" claim to be used in the id_token.

If doing a pairwise subject derivation, this method should check the registration of the current Client to see if it has a PAIRWISE subject identifier type. If so, it returns the calculated string of that subject. If not, it returns null and the value of getUserSubject() is used by the API instead.

Returns:

The value of the "sub" claim to be used in the id_token, or null if no such subject exists.

Since:

2.22