com.authlete.common.ida

Class DatasetExtractor

java.lang.Object

com.authlete.common.ida.DatasetExtractor

public class DatasetExtractor
extends Object

A utility to extract a dataset that meets conditions specified by a verified_claims request. The specification of the request is defined in OpenID Connect for Identity Assurance 1.0.

The extract() method of this class builds a new dataset that satisfies conditions of a verified_claims request from the given original dataset. What the method does is not just to return the entire dataset when it meets conditions of a verified_claims request. Instead, the method extracts only necessary parts from the original dataset and omits unnecessary parts in order to conform to the filtering rules and the data minimization policy that are written in the specification.

For example, when the original dataset holds the following:

 {
   "verification": {
     "trust_framework": "uk_tfida",
     "evidence": [
       {
         "type": "electronic_record",
         "check_details": [
           {
             "check_method": "kbv",
             "organization": "TheCreditBureau",
             "txn": "kbv1-hf934hn09234ng03jj3"
           }
         ],
         "time": "2021-04-09T14:12Z",
         "record": {
           "type": "mortgage_account",
           "source": {
             "name": "TheCreditBureau"
           }
         }
       },
       {
         "type": "electronic_record",
         "check_details": [
           {
             "check_method": "kbv",
             "organization": "OpenBankingTPP",
             "txn": "kbv2-nm0f23u9459fj38u5j6"
           }
         ],
         "time": "2021-04-09T14:12Z",
         "record": {
           "type": "bank_account",
           "source": {
             "name": "TheBank"
           }
         }
       }
     ]
   },
   "claims": {
     "given_name": "Sarah",
     "family_name": "Meredyth",
     "birthdate": "1976-03-11",
     "place_of_birth": {
       "country": "UK"
     },
     "address": {
       "locality": "Edinburgh",
       "postal_code": "EH1 9GP",
       "country": "UK",
       "street_address": "122 Burns Crescent"
     }
   }
 }
 

and the following verified_claims request is made:

 {
   "verification": {
     "trust_framework": null,
     "evidence": [
       {
         "type": {
           "value": "electronic_record"
         },
         "check_details": [
           {
             "check_method": null,
             "organization": {
               "value": "OpenBankingTPP"
             },
             "txn": null
           }
         ]
       }
     ]
   },
   "claims": {
     "given_name": null,
     "family_name": {
       "value": "Unknown"
     },
     "address": {
       "locality": null
     }
   }
 }
 

the extract() method generates a new dataset as shown below:

 {
   "verification": {
     "trust_framework": "uk_tfida",
     "evidence": [
       {
         "type": "electronic_record",
         "check_details": [
           {
             "check_method": "kbv",
             "organization": "OpenBankingTPP",
             "txn": "kbv2-nm0f23u9459fj38u5j6"
           }
         ]
       }
     ]
   },
   "claims": {
     "given_name": "Sarah",
     "address": {
       "locality": "Edinburgh"
     }
   }
 }
 

Below are points to note:

1. The original dataset contains two elements in the "evidence" array, but the generated dataset contains only one element. It is because the constraint, check_details/*/organization == "OpenBankingTPP", filtered out the unmatched element.
2. The generated dataset does not contain the "family_name" claim. It is because the value of the "family_name" claim in the original dataset is not "Unknown". When the "value", "values" and "max_age" constraints are not satisfied under "verification", the entire "verified_claims" is omitted. On the other hand, under "claims", unmatched claims are just omitted without affecting the entire "verified_claims".
3. Many properties are omitted from the generated dataset for the data minimization policy. For example, "address" contains only "locality". Other properties such as "postal_code", "country" and "street_address" are omitted.

The extract() method returns a new dataset or null silently. No exception is raised in any case. If you want to view the internal process of the method, set a logger by the setLogger() method. The logging levels of warn, debug and trace are used according to the following criteria.

warn

The warn level is used when the structure of the request seems invalid (specification violation) or when the structure of the original dataset seems inappropriate.

debug

The debug level is used when the property being checked causes failure of matching.

trace

The trace level is used when it is determined how to process a property regardless of whether the property is adopted or omitted.

Since:

3.17

See Also:

OpenID Connect for Identity Assurance 1.0

Constructor Summary

Constructors

Constructor and Description
DatasetExtractor() The default constructor.
DatasetExtractor(OffsetDateTime currentTime) Constructor with time which is used for the "max_age" constraint.

Method Summary

Modifier and Type	Method and Description
Map<String,Object>	extract(Map<String,Object> request, List<Map<String,Object>> originalDatasets) Repeat to call the extract(Map, Map) method for each element in originalDatasets until the method succeeds in generating a dataset that meets conditions of the request.
Map<String,Object>	extract(Map<String,Object> request, Map<String,Object> original) Extract a dataset that meets conditions of the request from the original dataset.
boolean	isTransformedClaimAware() Get the flag which indicates whether transformed claims are recognized.
DatasetExtractor	setLogger(org.slf4j.Logger logger) Set a logger that processes logs emitted by this instance.
DatasetExtractor	setTransformedClaimAware(boolean aware) Set the flag which indicates whether transformed claims are recognized.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DatasetExtractor

public DatasetExtractor()

The default constructor.

This is an alias of DatasetExtractor((OffsetDateTime)null).

DatasetExtractor

public DatasetExtractor(OffsetDateTime currentTime)

Constructor with time which is used for the "max_age" constraint.

The "max_age" constraint here is not the one defined in OpenID Connect Core 1.0 but the one defined in OpenID Connect for Identity Assurance 1.0.

Parameters:

currentTime - Time which is used for the "max_age" constraint. If null is given, OffsetDateTime.now(UTC) is used.

Method Detail

isTransformedClaimAware

public boolean isTransformedClaimAware()

Get the flag which indicates whether transformed claims are recognized. The initial value when an instance of this class is created is true.

When transformed claims are recognized, they are not omitted from the dataset generated by the extract() method. Note that, however, the extract() method does not compute values of transformed claims. The computation is performed by Authlete when you pass the generated dataset to Authlete's /api/auth/authorization/issue API or /api/auth/userinfo/issue API.

Returns:

true if transformed claims are recognized.

See Also:

OpenID Connect Advanced Syntax for Claims (ASC) 1.0

setTransformedClaimAware

public DatasetExtractor setTransformedClaimAware(boolean aware)

Set the flag which indicates whether transformed claims are recognized.

See the description of isTransformedClaimAware() for details.

Parameters:

aware - true to be aware of transformed claims.

Returns:

this object.

setLogger

public DatasetExtractor setLogger(org.slf4j.Logger logger)

Set a logger that processes logs emitted by this instance.

Parameters:

logger - A logger that processes logs emitted by this instance.

Returns:

this object.

See Also:

Simple Logging Facade for Java (SLF4J)

extract

public Map<String,Object> extract(Map<String,Object> request,
                                  List<Map<String,Object>> originalDatasets)

Repeat to call the extract(Map, Map) method for each element in originalDatasets until the method succeeds in generating a dataset that meets conditions of the request.

Parameters:

request - A Map instance that represents the content of a "verified_claims" request.

originalDatasets - A list of original datasets.

Returns:

A new dataset built from one of the given original datasets. If none of the original datasets satisfy the conditions of the "verified_claims" request, null is returned.

extract

public Map<String,Object> extract(Map<String,Object> request,
                                  Map<String,Object> original)

Extract a dataset that meets conditions of the request from the original dataset.

Parameters:

request - A Map instance that represents the content of a "verified_claims" request.

original - The original dataset from which this method builds a new dataset that satisfies conditions of the "verified_claims" request.

Returns:

A new dataset built from the original dataset. If the original dataset cannot satisfy conditions of the "verified_claims" request, null is returned.