com.authlete.jaxrs.spi

Interface UserInfoRequestHandlerSpi

All Known Implementing Classes:

UserInfoRequestHandlerSpiAdapter

public interface UserInfoRequestHandlerSpi

Service Provider Interface to work with UserInfoRequestHandler.

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

Since:

1.2

Author:

Takahiko Kawasaki

Method Summary

Modifier and Type	Method and Description
Object	getUserClaim(String claimName, String languageTag) Get the value of a claim of the user.
Object	getVerifiedClaims(String subject, Object verifiedClaimsRequest) Get the verified claims of the user to be embedded in the userinfo response.
List<com.authlete.common.assurance.VerifiedClaims>	getVerifiedClaims(String subject, com.authlete.common.assurance.constraint.VerifiedClaimsConstraint constraint) Deprecated.
void	prepareUserClaims(String subject, String[] claimNames) Prepare claim values of the user who is identified by the subject (= unique identifier).

Method Detail

prepareUserClaims

void prepareUserClaims(String subject,
                       String[] claimNames)

Prepare claim values of the user who is identified by the subject (= unique identifier).

This method is called before calls of getUserClaim(String, String) method.

Parameters:

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

claimNames - Names of the requested claims. Each claim name may contain a language tag. See "5.2. Claims Languages and Scripts" in OpenID Connect Core 1.0 for details.

getUserClaim

Object getUserClaim(String claimName,
                    String languageTag)

Get the value of a claim of the user.

This method may be called multiple times.

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.

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

NOTE: Since version 2.42, this method is called only when the isOldIdaFormatUsed() method of UserInfoRequestHandler.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 a "userinfo" property. The value of the property is a JSON object which lists claims that the client application wants to be embedded in the userinfo response. 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 "userinfo" property like below.

 {
   "userinfo": {
     "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.

constraint - An object that represents the "verified_claims" in the "userinfo" property.

Returns:

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

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

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 "userinfo" property. The value of the property is a JSON object which lists claims that the client application wants to be embedded in the userinfo response. 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 "userinfo" property like below.

 {
   "userinfo": {
     "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.

 {
   "userinfo": {
     "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 userinfo response as the value of "verified_claims".

For example, to make a userinfo response 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.

verifiedClaimsRequest - An object that represents the "verified_claims" in the "userinfo" 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 userinfo response as the value of "verified_claims". If this method returns null, "verified_claims" does not appear in the userinfo response.

Since:

2.42

See Also:

OpenID Connect for Identity Assurance 1.0