GAIN PoC Interim Report (Spring 2023)

11 min readMay 2, 2023

Disclaimer

This is a copy (with some editorial adjustments) of the interim report about GAIN PoC I submitted to the GAIN PoC Community Group on March 26, 2023. Please note that while the report was well received by the group, it is not an officially endorsed document.

Preface

GAIN (Global Assured Identity Network) is a project to build a high-trust digital identity network over the Internet. The white paper of the project “GAIN DIGITAL TRUST” was co-authored by over 150 professionals in related fields and published on September 13, 2021. The white paper is freely downloadable from the GAIN website.

To research the technical feasibility of GAIN, volunteers formed GAIN PoC Community Group. This document is an interim report on the findings obtained through a year of activities by the community group.

Current Architecture of Ecosystems

The open banking movement started in the United Kingdom has spread to countries around the world. Australian Consumer Data Right (CDR) and Brazilian Open Finance are examples of the movement.

Each country has built its own ecosystem where multiple services and multiple applications connect with each other. Technically, the services and applications have implemented “authorization servers” and “relying parties” respectively whose technical details are defined in RFC 6749 The OAuth 2.0 Authorization Framework and other related standards.

In a typical implementation, a relying party belongs to one authorization server at a time. An authorization server and a relying party that do not have such a relationship cannot communicate with each other. Therefore, if an application wants to communicate with multiple services, the application has to establish a relationship with each service’s authorization server one by one.

To establish the relationship, an application registers itself to each authorization server by using the mechanism called “dynamic client registration”. The mechanism is defined in OpenID Connect Dynamic Client Registration 1.0 and RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol.

An authorization server that supports dynamic client registration provides the dynamic client registration endpoint. The endpoint accepts a dynamic client registration request which contains a set of client metadata. Upon a successful registration, the endpoint returns JSON that contains actually-registered client metadata and a newly-issued client identifier. The application must remember the client identifier for later use.

To prevent unauthorized parties from registering clients, real-world deployments employ some countermeasures. An example is to require that a dynamic client registration request contain a “software statement” which has been issued by a trusted authority. In UK-style ecosystems, a central “directory” serves the role.

The diagram below (excerpted from “Implementer’s note about Open Banking Brasil”) illustrates the flow of issuance and verification of a software statement in Brazilian Open Banking. By verifying the presented software statement, the authorization server can be sure that the dynamic client registration request has come from a legitimate party.

Design Considerations

Decentralized Trust

One of the goals GAIN wants to achieve is to connect existing and future ecosystems with each other to build a cross-border network where applications can communicate with services in different ecosystems.

A straightforward architecture for the goal might be to build a single central directory that governs all applications and all services in the world. However, it is unrealistic because each ecosystem has its own regulatory requirements to meet local needs. Impact on ecosystems, even if any, must be as minimal as possible.

Trust between applications and services in different ecosystems should be able to be established without needing a single central authority.

Globally-Unique Client Identifiers

Client identifiers issued through the dynamic client registration are unique only in the authorization server that has issued them. Even within a single ecosystem, client identifiers issued by different authorization servers may conflict.

Therefore, applications in existing ecosystems have to manage carefully which client identifier has been issued by which authorization server. An application has to switch a client identifier that represents the application itself according to which service it wants to communicate with. This is a burden on the application side.

It is desirable that an application can use a single client identifier regardless of whatever service to communicate with.

KYC

For a high-trust digital identity, it should be ensured that user claims (such as family name and date of birth) have been obtained through KYC processes.

Adopted Standards

With the design considerations above, the community group decided to adopt the following specifications for the PoC.

OpenID Connect Federation 1.0

OpenID Connect Federation 1.0 (OIDC Federation) has the following characteristics that are appealing to the PoC.

First, the specification defines a mechanism where an identity provider (authorization server) and a relying party that have no direct relationship trust each other based on “trust chains” and the identity provider accepts OAuth/OIDC requests from the relying party without needing prior registration of the relying party.

Trust of the trust chains is assured by “trust anchors” and “intermediate authorities” that are independent of identity providers and relying parties. Trust chains of OIDC Federation are similar to certificate chains of Public Key Infrastructure. Trust anchors and intermediate authorities are conceptually equivalent to root certificate authority (Root CA) and intermediate certificate authority (Intermediate CA).

Second, an application can consistently use the same client identifier in every communication with different services. The client identifier is a globally-unique URL. The URL is determined not by an identity provider but by an entity that manages the relying party. OIDC Federation client identifiers have something in common with “Decentralized Identifiers” in that identifiers are determined by entities being identified.

OpenID Connect for Identity Assurance 1.0

Common social media out there may hold user claims (e.g. family name and date of birth), but the values of the claims are often just self-asserted ones. Therefore, they cannot be used in legal contexts. For example, a self-asserted date of birth cannot be used for the purpose of age verification to buy liquor, which is one of the use cases written in the GAIN white paper.

OpenID Connect for Identity Assurance 1.0 (OIDC4IDA) defines a mechanism to transmit user claims (e.g. family name and date of birth) that have been verified by official evidence such as passport and driver’s license. Identity providers that support OIDC4IDA can embed verified user claims in ID Tokens and responses from the userinfo endpoint.

Technically, information related to verified user claims is all put under “verified_claims”. Therefore, a relying party that receives an ID Token or a userinfo response can distinguish verified user claims from other normal (often just self-asserted) user claims.

The figure below excerpted from the web page of the eKYC-IDA Working Group illustrates how the content of verified_claims is structured.

Authorization Flow

The following diagram summarizes the authorization flow used in the PoC.

Technical points to note are as follows.

The authorization flow starts from a PAR request. The client identifier contained in the request is a globally-unique URL.
The PAR request contains a claims request parameter. The value of the parameter contains "id_token":{"verified_claims":...} to request the authorization server to embed verified user claims in the ID Token which will be issued from the token endpoint.
The payload of the ID Token issued from the token endpoint contains verified_claims.

Authorization Flow Example

This section describes an example of authorization flow to show actual requests and responses.

Variables

Common variables used in the examples are defined as follows.

ISSUER = https://fapidev-as.authlete.net/
PAR_ENDPOINT = https://fapidev-as.authlete.net/api/par
TOKEN_ENDPOINT = https://fapidev-as.authlete.net/api/token
CLIENT_ID = https://relying-party.authlete.net/5899463614448063
REDIRECT_URI = https://fapidev-api.authlete.net/api/mock/redirection/11794872185
AUTH_PRI = credentials/authlete/auth.pri.jwk
MTLS_PRI = credentials/authlete/mtls.pri.pem
MTLS_CER = credentials/authlete/mtls.cer.pem

An important point in the PoC is that the client identifier (the value of CLIENT_ID) is a globally-unique URL. Actual files pointed to by the relative paths in the above list (i.e. the values of AUTH_PRI, MTLS_PRI and MTLS_CER) are in the GAIN PoC Git repository.

PAR Request

Prepare a client assertion for the private_key_jwt client authentication (RFC 7523). The generate-client-assertion.rb script in the command line below is in the GAIN PoC Git repository.

ASSERTION=`bin/generate-client-assertion.rb --aud=$ISSUER --key=$AUTH_PRI --sub=$CLIENT_ID`

Send a PAR request to the PAR endpoint. Newlines in the command line below are for display purposes only. An actual request should not contain newlines.

curl $PAR_ENDPOINT
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  -d client_assertion=$ASSERTION
  -d client_id=$CLIENT_ID
  -d response_type=code
  -d scope=openid
  -d redirect_uri=$REDIRECT_URI
  --data-urlencode claims='{
    "id_token":{
      "verified_claims":{
        "verification":{
          "trust_framework":null
        },
        "claims":{
          "given_name":null,
          "family_name":null,
          "birthdate":null,
          ":age_18_or_over":null,
          "::age_100_or_over":null
        }
      }
    },
    "transformed_claims":{
      "age_18_or_over":{
        "claim":"birthdate",
        "fn":[ "years_ago", ["gte",18] ]
      }
    }
  }'

The PAR endpoint returns a response like below.

{
  "expires_in": 90,
  "request_uri":
    "urn:ietf:params:oauth:request_uri:20auKsHjnMxQg1L23jvvbCDvwlH6MAQk5cTQDO0gPaE"
}

The value of the request_uri parameter in the PAR response is used in the following authorization request.

Authorization Request

Send an authorization request to the authorization endpoint via a web browser.

https://fapidev-www.authlete.net/api/authorization?client_id=${CLIENT_ID}&request_uri=${REQUEST_URI}

The authorization endpoint returns an authorization page. Input inga and inga as login ID and password (the login credentials are just for demo), and then press the “Authorize” button. If the login form needs to be displayed again, append &prompt=login at the end of the authorization request.

Token Request

Send a token request to the token endpoint. Newlines in the command line below are for display purposes only. An actual request should not contain newlines. Note that in the example the client certificate is included in the request by using the--key option and the --cert option for certificate binding (RFC 8705).

curl
  --key $MTLS_PRI
  --cert $MTLS_CER
  $TOKEN_ENDPOINT
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  -d client_assertion=$ASSERTION
  -d grant_type=authorization_code
  -d code=$AUTHORIZATION_CODE
  -d redirect_uri=$REDIRECT_URI

The token endpoint returns a response like below. New lines and white spaces in the values of access_token and id_token are for display purposes only. Actual values do not contain them.

{
  "access_token":
    "eyJhbGciOiJQUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6ImF1dGhsZXRlLWZhcGlkZXYtYXBpLTI
     wMTgwNTI0In0.eyJzdWIiOiIxMDA0IiwiZ3JhbnRfdHlwZSI6ImF1dGhvcml6YXRpb25fY29kZSIsIn
     Njb3BlIjoib3BlbmlkIiwiYXV0aF90aW1lIjoxNjcwNjA3MTM1LCJpc3MiOiJodHRwczovL2ZhcGlkZ
     XYtYXMuYXV0aGxldGUubmV0LyIsImNuZiI6eyJ4NXQjUzI1NiI6ImhaT05oU01pbE12SkFDLXN5RFlY
     Uk9hOVlIYk8yUXR5bWxSME1LT09HLVUifSwiZXhwIjoxNjcwNjA5NTEyLCJpYXQiOjE2NzA2MDg2MTI
     sImNsaWVudF9pZCI6Imh0dHBzOi8vcmVseWluZy1wYXJ0eS5hdXRobGV0ZS5uZXQvNTg5OTQ2MzYxND
     Q0ODA2MyIsImp0aSI6IlNsM0VEUGpyTXllQkFyaU9NWlFmSjRBSXVkaldNd0lubVR5ck5wajRhN3cif
     Q.UQu-kO8yo--3dxiiaO2eEnBwNeBxL5LFepzxQWJp8G6k1L0NeVzgF1jMrWfKUSQishnKSSbnQ6ymD
     jQJ3E7MfJj4vdS8IdMf7wcCsMFTR0UXCpueKgOdXZmWAjU1IWM9rn5rz0jtlw-wNujLlT5sGearta3y
     8yyvQPgCe7exjdLstwF7Mo6XzXFx28FiZgrLiEouOYOP26QvRcptGeX6kQxiAIeWAxB4YFxlrZgJgmf
     uuL-mdx4uKp1jkxl0GQ5QZh7MUIvgAlm3od3CMPVDAeSdHQsnIoQPibTbzd069gMqqR9esV-j-x6_OX
     Lv8e1hmlAJ-DjW9vj07BjrQUGvFg",
  "refresh_token":"b172VT2h31P77-0HIiZ_2Nz6844qpZGozyqDFLigpV0",
  "scope":"openid",
  "id_token":
    "eyJraWQiOiJhdXRobGV0ZS1mYXBpZGV2LWFwaS0yMDE4MDUyNCIsImFsZyI6IlJTMjU2In0.eyJpc3M
     iOiJodHRwczovL2ZhcGlkZXYtYXMuYXV0aGxldGUubmV0LyIsInN1YiI6IjEwMDQiLCJhdWQiOlsiaH
     R0cHM6Ly9yZWx5aW5nLXBhcnR5LmF1dGhsZXRlLm5ldC81ODk5NDYzNjE0NDQ4MDYzIl0sImV4cCI6M
     TY3MDYwODkxMiwiaWF0IjoxNjcwNjA4NjEyLCJhdXRoX3RpbWUiOjE2NzA2MDcxMzUsInZlcmlmaWVk
     X2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoibmlzdF84MDBfNjNBIn0
     sImNsYWltcyI6eyJnaXZlbl9uYW1lIjoiSW5nYSIsImZhbWlseV9uYW1lIjoiU2lsdmVyc3RvbmUiLC
     JiaXJ0aGRhdGUiOiIxOTkxLTExLTA2IiwiOjphZ2VfMTAwX29yX292ZXIiOmZhbHNlLCI6YWdlXzE4X
     29yX292ZXIiOnRydWV9fX0.PSf0WD8j92e080Jue2LmDeHV7_027OAw9hbnmnJyd26YiA7DCOTiLhlz
     mKgN_7CPOySkU5I-AWaPeDblVLSrpO1CQpp_GyYHETffC-ew2fIFls59xTUgC81_dBs011VDA95nZc9
     E3VjrRVcnBrmMWNNaw2plfb6ooXDLj2tTpIoYl_CMbp4eI_1rCo0G0yyZXd3Vw6bTWYKdG33-nnJ7AL
     O6KtnkcKuIVthFDBFkhA320ujUzopHn7-ksN1onQwQa9bxyFW7XPHp5C24TNsIkBP-an0emPJ0JsSYr
     YBZFtrxjbuUxZz16SpmTEj3bPZepsSGdfCZCLdbAP_QB4cAwQ",
  "token_type":"Bearer",
  "expires_in":900
}

The payload of the ID Token in the example contains information equivalent to the following JSON. Points to note are that verified_claims is embedded (OIDC4IDA) and that the globally-unique URL is listed in the aud claim (OIDC Federation).

{
  "iss": "https://fapidev-as.authlete.net/",
  "sub": "1004",
  "aud": [
    "https://relying-party.authlete.net/5899463614448063"
  ],
  "exp": 1670608912,
  "iat": 1670608612,
  "auth_time": 1670607135,
  "verified_claims": {
    "verification": {
      "trust_framework": "nist_800_63A"
    },
    "claims": {
      "given_name": "Inga",
      "family_name": "Silverstone",
      "birthdate": "1991-11-06",
      "::age_100_or_over": false,
      ":age_18_or_over": true
    }
  }
}

Trust Chain Resolution

When a client identifier in an authorization request is unknown but it is an HTTP-accessible URL, an authorization server that supports the OIDC Federation specification tries to construct a trust chain from the URL and determine whether the client identifier is acceptable or not. If the client identifier is acceptable, the authorization server registers the relying party automatically and continues to handle the authorization request. This process is called “automatic client registration”, which is different from “dynamic client registration” defined in OpenID Connect Dynamic Client Registration 1.0 and RFC 7591.

The procedure of automatic client registration is divided into the following steps.

Resolve trust chains of the relying party and select one from among them.
Apply the metadata policy of the selected trust chain if available.
Authenticate the authorization request.
Validate the client metadata.
Register the relying party with the client metadata.

The first step is called “trust chain resolution”. It is the core of the decentralized trust.

Trust Chain Resolution Example

The diagram below (excerpted from “OpenID Connect Federation 1.0” on Authlete website) depicts the flow of trust chain resolution.

This section does not explain details of the specification but just shows actual messages exchanged between entities for trust chain resolution using https://relying-party.authlete.net/5899463614448063 as an example.

Relying Party’s Entity Configuration

The first step is to fetch the “entity configuration” of the relying party. The entity configuration is downloadable from the URL that is constructed by concatenating the client identifier and the fixed string "/.well-known/openid-federation".

curl https://relying-party.authlete.net/5899463614448063/.well-known/openid-federation

An entity configuration is a kind of JWT. The following is an example response from the URL.

eyJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoib3FfRzRWSS1XTnowdUtRUWVxNGhOdHNTMFpOck5JakpZeHZVU3N6ckZPcyJ9.eyJpc3MiOiJodHRwczovL3JlbHlpbmctcGFydHkuYXV0aGxldGUubmV0LzU4OTk0NjM2MTQ0NDgwNjMiLCJzdWIiOiJodHRwczovL3JlbHlpbmctcGFydHkuYXV0aGxldGUubmV0LzU4OTk0NjM2MTQ0NDgwNjMiLCJpYXQiOjE2Nzk3NTA0MjAsImV4cCI6MTY3OTc1NDAyMCwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsIm4iOiJnay0zaG5jTHBnTVo3cDU2WkxLNTBLZHZzQXViVjkydnlYTnpBemZvZzV6UTREbUF5eV9xZ3VnN2g3VDBqOHhmZnkyU051UW1UOUdCNFUtZzJVYzVmdk9ydHJYdlBJSDhYVDhTeHJ5bTZXSmFVaHlnNjE1M0ZzTlpLMzdrTDZMM1JTaVl0WFA0N093TmNsX0xGaFVKbjdHN0FhR2p5VUIyMnVZWmdTZTE2RWhBejdrazJ1NHdmeFVhM0VxdjBIbjdtb1hDWUZaZUNxNHhaWDI2dWF0d1QzaTc1bWs2RFNKRVBKQ3hSWHRMU1FpRzFKajg5VVVicEZrRkRSQWd0WXh2MUowTldyNnlBRFdUMDRJNEgyTUswR1JLZEtFYkU4dG91bFYwdnJ4dE5ZemlGOGpBdllsMVMyQmpBaGFZbDh1YkFBV1V2MDBBa0dDZlY0VWZKWmtTQ1EiLCJraWQiOiJvcV9HNFZJLVdOejB1S1FRZXE0aE50c1MwWk5yTklqSll4dlVTc3pyRk9zIn1dfSwiYXV0aG9yaXR5X2hpbnRzIjpbImh0dHBzOi8vdHJ1c3QtYW5jaG9yLmF1dGhsZXRlLm5ldC8iXSwibWV0YWRhdGEiOnsib3BlbmlkX3JlbHlpbmdfcGFydHkiOnsiY2xpZW50X2lkIjoiaHR0cHM6Ly9yZWx5aW5nLXBhcnR5LmF1dGhsZXRlLm5ldC81ODk5NDYzNjE0NDQ4MDYzIiwicmVkaXJlY3RfdXJpcyI6WyJodHRwczovL2ZhcGlkZXYtYXBpLmF1dGhsZXRlLm5ldC9hcGkvbW9jay9yZWRpcmVjdGlvbi8xMTc5NDg3MjE4NSIsImh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC95ZXMvb2lkY2NiIl0sInJlc3BvbnNlX3R5cGVzIjpbImNvZGUiLCJpZF90b2tlbiJdLCJncmFudF90eXBlcyI6WyJhdXRob3JpemF0aW9uX2NvZGUiLCJyZWZyZXNoX3Rva2VuIl0sImNsaWVudF9uYW1lIjoiR0FJTiBQb0MgQ2xpZW50IiwibG9nb191cmkiOiJodHRwczovL3d3dy5hdXRobGV0ZS5jb20vaW1nL2xvZ28vYXV0aGxldGUtbG9nby1pbWFnZS1ibHVlLXdpdGgtd2hpdGUtYmctMjU2LnBuZyIsImp3a3MiOnsia2V5cyI6W3sia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsImtpZCI6ImdhaW5wb2MiLCJ4NWMiOlsiTUlJQmp6Q0NBVFdnQXdJQkFnSVVTWEtHWlNSQzdLVkNEYUNmbkpLd0JUQ2ZzUkV3Q2dZSUtvWkl6ajBFQXdJd0hURWJNQmtHQTFVRUF3d1NZMnhwWlc1MExtVjRZVzF3YkdVdVkyOXRNQjRYRFRJeU1EVXdOREl6TVRjME5Gb1hEVEkxTURFeU9ESXpNVGMwTkZvd0hURWJNQmtHQTFVRUF3d1NZMnhwWlc1MExtVjRZVzF3YkdVdVkyOXRNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVBUDZQZ0ZsOU5uUVNhWUNOOG1TZ09aRWxsZWFwMHFPZythMzlIck11RU5UeGQ2NmRuS3pwY1lGV09LMGNxM1BGMEVsTGhTMzNwbmFya2RDd2Z5TnB4Nk5UTUZFd0hRWURWUjBPQkJZRUZBWlF1MmgyMVZwMC83MkxMRitNaXpqWXBsQjhNQjhHQTFVZEl3UVlNQmFBRkFaUXUyaDIxVnAwLzcyTExGK01pempZcGxCOE1BOEdBMVVkRXdFQi93UUZNQU1CQWY4d0NnWUlLb1pJemowRUF3SURTQUF3UlFJZ0JINldBeE5nSWZrOFg0WVVKRnJRR0tYZ2gwREh2QWhMVUs5THFBSjZBWFlDSVFDZmxFSU1BbmNVUGcxR29meGsxZ1RVZ3NMdUk5UUR2L1Y1WG1kS0lPbTd3UT09Il0sIngiOiJBUDZQZ0ZsOU5uUVNhWUNOOG1TZ09aRWxsZWFwMHFPZy1hMzlIck11RU5RIiwieSI6IjhYZXVuWnlzNlhHQlZqaXRIS3R6eGRCSlM0VXQ5NloycTVIUXNIOGphY2MifSx7Imt0eSI6IlJTQSIsImUiOiJBUUFCIiwia2lkIjoidmNJT2FVMFk4TjhXZDdIbjVuSzlxWEZ3WHhJbTVJMTB6NXlXUFdYMFk4MCIsImFsZyI6IlJTMjU2IiwibiI6InQzcDIzdzcwOFZ6OWtTQ1k4UG5CcUNndTl5Zi00TVNEOTRDN3JheU5uSElUSlhwNV9tVS1DdkdVekdEVFNUNUxnQWRXbG9zZEJQa0lhbHdYM1BmWFhYZllVT2dVZmk2LWlCVDhjLUNtNF9GLU9rYldlSmJpOU45S1NtSjRoVURNQzBoc2M1bVg4TkJiNWNueno5NnRFTjNtVENVY1gyY0VxVV82NmZxQy1kZkRtT2NObDJQeE82dVdBenpaVk9ibmxFZjlnbkg2cVlOVFpZcS0yXzZxT0JkTEkyNDNGTnhxUFZ6aFYtRldMRkMycUhlVVlOcGNuOWJLUjZnb1lCcFNJdnA1VnEwX0JaZEd3TTVudkhVaVFvYVdwUDlacUJ2SUF6VWpCVjlOMW9yZXZ4enVsdl9sdjB3aElnYllXXzlNX3Q5SVI0ekdtb0NNcmhVaUxBUmsyUSJ9XX0sInN1YmplY3RfdHlwZSI6InB1YmxpYyIsImlkX3Rva2VuX3NpZ25lZF9yZXNwb25zZV9hbGciOiJSUzI1NiIsInRva2VuX2VuZHBvaW50X2F1dGhfbWV0aG9kIjoicHJpdmF0ZV9rZXlfand0IiwidG9rZW5fZW5kcG9pbnRfYXV0aF9zaWduaW5nX2FsZyI6IlJTMjU2IiwidGxzX2NsaWVudF9jZXJ0aWZpY2F0ZV9ib3VuZF9hY2Nlc3NfdG9rZW5zIjp0cnVlLCJjbGllbnRfcmVnaXN0cmF0aW9uX3R5cGVzIjpbImF1dG9tYXRpYyIsImV4cGxpY2l0Il19fX0.bTpkHrvRqscNmlqJXnxQk_YLjde6H7VFEKBfGoBOI0vWCYk4gLbImbrJS4-z_aWl8xqb9srFjs2Mzlq8t-8RNJdSxJhrI_ha9SUkZITxIGyR1lkTp4wGwfeZsQIt4mocEKv_iIV64Km9KLl7ELaXj1ipegFuFu5BBgvEYHCmSuMcjvPLIYI4bK224xbVreGIyyhu3dPyzBfLcUQ767RiaViQrnTzfZIAOmbT_a8j_yy1rSnqeM7O-33VNayT8c7H-2LjZntDMVSqgaVZox0PsqNaLyQX-ii6UPeje5ESvTkO54-_0ZVwx01b5cfAXfpUdSfNBGCYNoiDbFfaEUz5vg

In the payload of the entity configuration, the following claim is contained.

"authority_hints": [
  "https://trust-anchor.authlete.net/"
]

The authority_hints claim is a list of direct superior authorities (trust anchors and/or intermediate authorities) that may issue an “entity statement” for the relying party. In this example, the authority_hints claim contains one element.

Although the name of the element implies that it is a trust anchor, it is unknown whether it is a trust anchor or an intermediate authority at this timing. In either case, it is a direct superior authority of the relying party.

Superior Authority’s Entity Configuration

To request the superior authority to issue an entity statement for the relying party, it is necessary to know the URL of the Web API that can issue the entity statement. The Web API is called “fetch endpoint”.

Because the URL of the fetch endpoint is written in the entity configuration of the superior authority, the entity configuration needs to be downloaded.

curl https://trust-anchor.authlete.net/.well-known/openid-federation

The following is an example response of the superior authority’s entity configuration.

eyJhbGciOiJSUzI1NiIsImtpZCI6Ik45WWhJRjNtQTRRV3phM0ZYOEN6cmdod3VfdEhmaG03N3Y1MFdkREg2YTQiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2Nzk3NTUyMzcsImlhdCI6MTY3OTc1MTYzNywiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuYXV0aGxldGUubmV0LyIsInN1YiI6Imh0dHBzOi8vdHJ1c3QtYW5jaG9yLmF1dGhsZXRlLm5ldC8iLCJqd2tzIjp7ImtleXMiOlt7Imt0eSI6IlJTQSIsIm4iOiJtZ0Zmd09mcmN4eGU5OWlsTUdiVzFtdWlzczF1ZWdjSjNGaks0ajdfUHhxbF91YmE1cWdkUXBwSDNUT0dqMXYtME1hQXZMUFpFaXlIT0VEUzRtN2ptR0Nac1k0OXU0REFrbUd3VFZIQXh4ZHg0NlZBd0d2WVJDdUl3emEtMXBZOHVNVXJSbHlBblY0R0pkSF9EWDdBX3hsWG9aMk9XT1gwMW93N3dLeEFYRHc2SFlpMy1iYldJOExPTWhmYXNJc2ttMWJDSVVjMXdXaEM5N1RMN0VheFZvQ0paaDM0bXdIRFhCVTNlNnRvUXJYVnZzM2ZaQWh4MllJSzhxUEVVQmtxZmxIVGJfY1ltSkNHeW5TSTZLSTZ5WkhJOUdfa1dwZUpTRkt3eExZWlNOVlVuajl0ZGpyVW9PRVU1MXFlTUZybVotVm9tVTFaaEFaU09TdF9icGx2bHciLCJlIjoiQVFBQiIsImtpZCI6Ik45WWhJRjNtQTRRV3phM0ZYOEN6cmdod3VfdEhmaG03N3Y1MFdkREg2YTQifV19LCJtZXRhZGF0YSI6eyJmZWRlcmF0aW9uX2VudGl0eSI6eyJmZWRlcmF0aW9uX2xpc3RfZW5kcG9pbnQiOiJodHRwczovL3RydXN0LWFuY2hvci5hdXRobGV0ZS5uZXQvbGlzdC8iLCJmZWRlcmF0aW9uX2ZldGNoX2VuZHBvaW50IjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuYXV0aGxldGUubmV0L2ZldGNoLyJ9fX0.JHEESDp5xpkFAhPsORpMeJXILAT-y8iZhbYUWqnwSiL5H2ewxJx368e457ODB_Ep8OHghMNpCtEpzZy82ePGElcDGvFPLB6lCpR_Vu5AlA18eFSo-m8B15CComwpSDBM2n0objVgyufsMedq1e7hRbQXtgwBOtKR3WDXjD-RQxUVWJ_eMGgL1zhj09jmbCuPY0xxkoi-hwMmsPYi-kA-fRLIKksHyiprQkRE_gaDQMgSRjdJFdpwGU4bHs0fwGX_9U7xNtdEbx0YYdsPfRxC_cKNTnZ378jNAQ9Dn6McHkIGgV3o-8VdNaSh9_5mAoINYls7Ze4nDoNDwPxNZyRW3Q

In the payload of the entity configuration, the following claim is contained.

"metadata": {
  "federation_entity": {
    "federation_list_endpoint": "https://trust-anchor.authlete.net/list/",
    "federation_fetch_endpoint": "https://trust-anchor.authlete.net/fetch/"
  }
}

The value of the federation_fetch_endpoint property is the URL of the fetch endpoint.

Entity Statement for Relying Party Issued By Superior Authority

The fetch endpoint issues an entity statement for an entity specified by the sub request parameter if the endpoint recognizes the specified entity.

curl https://trust-anchor.authlete.net/fetch/?sub=https://relying-party.authlete.net/5899463614448063

The following is an example response from the fetch endpoint.

eyJhbGciOiJSUzI1NiIsImtpZCI6Ik45WWhJRjNtQTRRV3phM0ZYOEN6cmdod3VfdEhmaG03N3Y1MFdkREg2YTQiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2Nzk5MjU0NDEsImlhdCI6MTY3OTc1MjY0MSwiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuYXV0aGxldGUubmV0LyIsInN1YiI6Imh0dHBzOi8vcmVseWluZy1wYXJ0eS5hdXRobGV0ZS5uZXQvNTg5OTQ2MzYxNDQ0ODA2MyIsImp3a3MiOnsia2V5cyI6W3siZSI6IkFRQUIiLCJuIjoiZ2stM2huY0xwZ01aN3A1NlpMSzUwS2R2c0F1YlY5MnZ5WE56QXpmb2c1elE0RG1BeXlfcWd1ZzdoN1Qwajh4ZmZ5MlNOdVFtVDlHQjRVLWcyVWM1ZnZPcnRyWHZQSUg4WFQ4U3hyeW02V0phVWh5ZzYxNTNGc05aSzM3a0w2TDNSU2lZdFhQNDdPd05jbF9MRmhVSm43RzdBYUdqeVVCMjJ1WVpnU2UxNkVoQXo3a2sydTR3ZnhVYTNFcXYwSG43bW9YQ1lGWmVDcTR4WlgyNnVhdHdUM2k3NW1rNkRTSkVQSkN4Ulh0TFNRaUcxSmo4OVVVYnBGa0ZEUkFndFl4djFKME5XcjZ5QURXVDA0STRIMk1LMEdSS2RLRWJFOHRvdWxWMHZyeHROWXppRjhqQXZZbDFTMkJqQWhhWWw4dWJBQVdVdjAwQWtHQ2ZWNFVmSlprU0NRIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJvcV9HNFZJLVdOejB1S1FRZXE0aE50c1MwWk5yTklqSll4dlVTc3pyRk9zIiwia3R5IjoiUlNBIn1dfSwibWV0YWRhdGFfcG9saWN5Ijp7Im9wZW5pZF9yZWx5aW5nX3BhcnR5Ijp7fX0sInRydXN0X21hcmtzIjpbeyJpZCI6Imh0dHBzOi8vcmVseWluZy1wYXJ0eS5hdXRobGV0ZS5uZXQvNTg5OTQ2MzYxNDQ0ODA2MyIsInRydXN0X21hcmsiOiJleUpoYkdjaU9pSlNVekkxTmlJc0ltdHBaQ0k2SWs0NVdXaEpSak50UVRSUlYzcGhNMFpZT0VONmNtZG9kM1ZmZEVobWFHMDNOM1kxTUZka1JFZzJZVFFpTENKMGVYQWlPaUowY25WemRDMXRZWEpySzJwM2RDSjkuZXlKemRXSWlPaUpvZEhSd2N6b3ZMM0psYkhscGJtY3RjR0Z5ZEhrdVlYVjBhR3hsZEdVdWJtVjBMelU0T1RrME5qTTJNVFEwTkRnd05qTWlMQ0pwYzNNaU9pSm9kSFJ3Y3pvdkwzUnlkWE4wTFdGdVkyaHZjaTVoZFhSb2JHVjBaUzV1WlhRdklpd2lhV0YwSWpveE5qYzVOelV5TmpReGZRLlJmNHV0Y24wa3dfTWVSXzdrU1lETFZyeEpqUWJ5TnZZQ2FVbmpkVWZmU2xoT2xxX0dCdTU3bE9uSGNJLWNEdzB1TFdqZVNPLUptdmxRY2t2am94YW1HclVRaFlKUjBLdFRBNjFVS1lhVTJjLTNrRDNkTV85SElIdmg5UjQ5cVpjTVlGbXFrMGt2UmVSNERITXRzd3d5WGRGbUxhOG93dk9PTzZvVnZXcmQxTm11QTZfUU4tNWFxVUpFUk9KNFUxbTMzbnRUaEpXSWdGS0NBRTBPVkZCaUlKN2F1bFdFSWo2YUNJVDF6eHI0RUpibUJqc2FUNlpRMnM3U1FncEZDbU0tei1nVUtOV1JsN0NHWDVWc1JrNVR5aVNlNDhpRE9HdzlwOUVia195eVgxWU9vNE9TMEhBeUlsTkd3cDNlUEh1SmhKQUFmUVNxMUt2aG1EN0N2U3R1dyJ9XX0.PMuzOEOhe0R2GEZr7dmZCFHbzd3CFz-iJQoXGXOEPXkPCTN38GUAr90k98phyM9FQDlj9XvUWDcIQTgpr83xU6lwXx2Pqf1VbKabdwsBH5ES0n0LSDTboG6gNU-t2xOiaznMEorhM8JyG7SX4PWSRzrDr6FHqJVQShzCJY5D_3CDF0YYtJf4gR0g9tgpZu6MnWZh1rargS_Q2qg1X2IgBixBloNVnpqpIF3FGQjmGqzOeepG0EseZBj-gMUTCpccgf5_5nmY3zhUdetEniQo-gHOezSnnWH3BLWzO3cfHKkm589A5lE10qiq9db-p386e0-RRzF_M3CoQJE4uoJwAw

Trust Chain Verification

Because the entity configuration of the superior authority (https://trust-anchor.authlete.net/) does not contain the authority_hints claim, the superior authority is a trust anchor. Therefore, the process of trust chain resolution terminates there.

As a result, the trust chain that consists of only two JWTs has been constructed. The first JWT is the entity configuration of the relying party and the last one is the entity statement issued from the fetch endpoint of the trust anchor.

If the authorization server knows the trust anchor as a trusted one and signatures of all the JWTs that have appeared in the process of trust chain resolution are verified, the trust chain is regarded as valid.

Note that public keys for signature verification are included in entity statements issued by direct superior authorities. The relationship is complex as the diagram below illustrates.