public interface AuthorizationDecisionHandlerSpi
AuthorizationDecisionHandler
.
An implementation of this interface must be given to the constructor
of AuthorizationDecisionHandler
class.
Modifier and Type | Method and Description |
---|---|
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 end-user was authenticated.
|
Object |
getUserClaim(String claimName,
String languageTag)
Get the value of a claim of the user.
|
String |
getUserSubject()
Get the subject (= unique identifier) of the end-user.
|
List<com.authlete.common.assurance.VerifiedClaims> |
getVerifiedClaims(String subject,
com.authlete.common.assurance.constraint.VerifiedClaimsConstraint constraint)
Get the verified claims of the user to be embedded in the ID token.
|
boolean |
isClientAuthorized()
Get the decision on the authorization request.
|
boolean isClientAuthorized()
true
if the end-user has decided to grant
authorization to the client application. Otherwise,
false
.long getUserAuthenticatedAt()
For example, if an authorization always requires an end-user to login, the authentication time is always "just now", so the implementation of this method will be like the following.
@Override public long getUserAuthenticatedAt() { return System.currentTimeMillis() / 1000; }
This method is not called when isClientAuthorized()
has returned false
.
String getUserSubject()
In a typical case, the subject is a primary key or another unique ID of the record that represents the end-user in your user database.
This method is not called when isClientAuthorized()
has returned false
.
null
makes the authorization
request fail.String getAcr()
The value returned by this method has an important meaning only
when an authorization requests acr
claim as an essential
claim. Practically speaking, it is unlikely to happen. See "5.5.1.1. Requesting the "acr" Claim" in OpenID
Connect Core 1.0 if you are interested in the details.
If you don't know what ACR is, return null
.
Object getUserClaim(String claimName, String languageTag)
This method may be called multiple times. On the other hand,
this method is not called when isClientAuthorized()
has returned false
or when getUserSubject()
has returned null
.
claimName
- A claim name such as name
and family_name
.
Standard claim names are listed in "5.1. Standard Claims" of OpenID
Connect Core 1.0. Java constant values that represent the
standard claims are listed in StandardClaims
class. The value of claimName
does NOT
contain a language tag.languageTag
- A language tag such as en
and ja
. Implementations
should take this into account whenever possible. See "5.2. Claims Languages and Scripts" in OpenID
Connect Core 1.0 for details.null
if the claim value of the claim
is not available.com.authlete.common.dto.Property[] getProperties()
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 publicProperty
[] getProperties() { return newProperty
[] { newProperty
("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.
null
is returned, any extra property will
not be associated.String[] getScopes()
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.
String getSub()
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.
null
if no such subject exists.List<com.authlete.common.assurance.VerifiedClaims> getVerifiedClaims(String subject, com.authlete.common.assurance.constraint.VerifiedClaimsConstraint constraint)
An authorization request may contain a "claims"
request parameter.
The value of the request parameter is JSON which conforms to the format
defined in 5.5. Requesting Claims using the "claims" Request Parameter of
OpenID
Connect Core 1.0. The JSON may contain an "id_token"
property.
The value of the property is a JSON object which lists claims that the
client application wants to be embedded in the ID token. The following
is an example shown in the section.
{ "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"] } } }
OpenID Connect for Identity Assurance 1.0 has extended this mechanism
to allow client applications to request verified claims. To request
verified claims, a "verified_claims"
property is included in the
"id_token"
property like below.
{ "id_token": { "verified_claims": { "verification": { "trust_framework": { "value": "de_aml" }, "evidence": [ { "type": { "value": "id_document" }, "method": { "value": "pipp" }, "document": { "type": { "values": [ "idcard", "passport" ] } } } ] }, "claims": { "given_name": null, "family_name": { "essential": true }, "birthdate": { "purpose": "To send you best wishes on your birthday" } } } } }
This method should return the requested verified claims.
subject
- The subject of the user. The same value returned by
getUserSubject()
.constraint
- An object that represents the "verified_claims"
in the
"id_token"
property."verified_claims"
claim.
If this method returns null, the "verified_claims"
claim
does not appear in the ID token.Copyright © 2020. All rights reserved.