com.authlete.jaxrs.spi

Interface AuthorizationDecisionHandlerSpi

All Known Implementing Classes:

AuthorizationDecisionHandlerSpiAdapter

public interface AuthorizationDecisionHandlerSpi

Service Provider Interface to work with AuthorizationDecisionHandler.

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

Author:

Takahiko Kawasaki

Method Summary

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.
Object	getVerifiedClaims(String subject, Object verifiedClaimsRequest) Get the verified claims of the user to be embedded in the ID token.
List<com.authlete.common.assurance.VerifiedClaims>	getVerifiedClaims(String subject, com.authlete.common.assurance.constraint.VerifiedClaimsConstraint constraint) Deprecated.
boolean	isClientAuthorized() Get the decision on the authorization request.

Method Detail

isClientAuthorized

boolean isClientAuthorized()

Get the decision on the authorization request.

Returns:

true if the end-user has decided to grant authorization to the client application. Otherwise, false.

getUserAuthenticatedAt

long getUserAuthenticatedAt()

Get the time when the end-user was authenticated.

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.

Returns:

The time when the end-user authentication occurred. The number of seconds since Unix epoch (1970-01-01). Return 0 if the time is unknown.

getUserSubject

String getUserSubject()

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

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.

Returns:

The subject (= unique identifier) of the end-user. Returning null makes the authorization request fail.

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 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.

Returns:

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

getUserClaim

Object getUserClaim(String claimName,
                    String languageTag)

Get the value of a claim of the user.

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.

If the claim name starts with two colons (::), the claim is a predefined transformed claim. The value of the claim will be computed by Authlete, so the exact value returned by this method is not so important. If this method returns a non-null value, the value of the transformed claim will be computed by Authlete and embedded in the ID token.

Likewise, if the claim name starts with one colon (:), the claim is a transformed claim defined in the "transformed_claims" property in the claims request parameter. If this method returns a non-null value, the value of the transformed claim will be computed by Authlete and embedded in the ID token.

See OpenID Connect Advanced Syntax for Claims (ASC) 1.0 for details about transformed claims.

Parameters:

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.

Returns:

The claim value. null if the claim value of the claim is not available.

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.

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

getVerifiedClaims

@Deprecated
List<com.authlete.common.assurance.VerifiedClaims> getVerifiedClaims(String subject,
                                                                                 com.authlete.common.assurance.constraint.VerifiedClaimsConstraint constraint)

Deprecated.

Get the verified claims of the user to be embedded in the ID token.

NOTE: Since version 2.42, this method is called only when the isOldIdaFormatUsed() method of AuthorizationDecisionHandler.Params returns true. See the description of the method for details.

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.

Parameters:

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.

Returns:

The verified claims. The returned value is embedded in the ID token as the value of the "verified_claims" claim. If this method returns null, the "verified_claims" claim does not appear in the ID token.

Since:

2.25

See Also:

getVerifiedClaims(String, Object)

getVerifiedClaims

Object getVerifiedClaims(String subject,
                         Object verifiedClaimsRequest)

Get the verified claims of the user to be embedded in the ID token.

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": null,
         "time": null,
         "evidence": [
           {
             "type": {
               "value": "document"
             },
             "method": null,
             "document_details": {
               "type": null
             }
           }
         ]
       },
       "claims": {
         "given_name": null,
         "family_name": null,
         "birthdate": null
       }
     }
   }
 }
 

The second argument (verifiedClaimsRequest) of this method represents the value of "verified_claims" in the request. It is a Map instance or a List instance. The latter case happens when the value of "verified_claims" is a JSON array like below.

 {
   "id_token": {
     "verified_claims": [
       {
         "verification": {
           "trust_framework": {
             "value": "gold"
           },
           "evidence": [
             {
               "type": {
                 "value": "document"
               }
             }
           ]
         },
         "claims": {
           "given_name": null,
           "family_name": null
         }
       },
       {
         "verification": {
           "trust_framework": {
             "values": [
               "silver",
               "bronze"
             ]
           },
           "evidence": [
             {
               "type": {
                 "value": "vouch"
               }
             }
           ]
         },
         "claims": {
           "given_name": null,
           "family_name": null
         }
       }
     ]
   }
 }
 

When the given argument is a Map instance, it can be cast by Map<String, Object>. On the other hand, in the case of a List instance, each element in the list can be cast by Map<String, Object>.

This method should return a Map instance or a List instance which represents the value of "verified_claims". The value will be embedded in the ID token as the value of "verified_claims".

For example, to make an ID token include "verified_claims" like below,

 "verified_claims": {
   "verification": {
     "trust_framework": "trust_framework_example"
   },
   "claims": {
     "given_name": "Max",
     "family_name": "Meier"
   }
 }
 

this method should build a Map instance like below and return it.

 Map<String, Object> verification = new HashMap<>();
 verification.put("trust_framework", "trust_framework_example");

 Map<String, Object> claims = new HashMap<>();
 claims.put("given_name", "Max");
 claims.put("family_name", "Meier");

 Map<String, Object> verified_claims = new HashMap<>();
 verified_claims.put("verification", verification);
 verified_claims.put("claims", claims);

 return verified_claims;
 

Parameters:

subject - The subject of the user. The same value returned by getUserSubject().

verifiedClaimsRequest - An object that represents the "verified_claims" in the "id_token" property in the "claims" request parameter. Either a Map instance or a List instance.

Returns:

The verified claims. The returned value is embedded in the ID token as the value of "verified_claims". If this method returns null, "verified_claims" does not appear in the ID token.

Since:

2.42

See Also:

OpenID Connect for Identity Assurance 1.0