[Openid-specs-ab] Issue #1382: Proposal of an improved Federation API (openid/connect)

[peppelinux]

New issue 1382: Proposal of an improved Federation API
https://bitbucket.org/openid/connect/issues/1382/proposal-of-an-improved-federation-api

Giuseppe De Marco:

Instead of a single **federation\_api** endpoint I would much rather 4 specialized fed api endpoints, named according to their specific operations. I wonder what might be a good semantics to name these endpoints, their purposes and their peculiar characteristics. On the track proposed by Roland I share a proposal below:  
  
- **federation\_statement** \(FETCH\), performs the current federation\_api fetch function, it’s required only for intermediaries and trust anchors and its result can be cached or served as a static content. My proposal would like to get even more than a single statement at this endpoint, with an appropriate pagination. Exactly as it is in SAML2 with MDQ, if the subject is specified the endpoint would return the single statement otherwise a list of paginated statements. Here a proposal of a FETCH response:

#### request for a single member/subject

```
GET /federation_statement_fetch?sub=https%3A%2F%2Fspid.example.it HTTP/1.1
Host: openid.sunet.se
```

#### response

```
200 OK
Last-Modified: Mon, 17 Dec 2018 11:15:56 GMT
Content-Type: oidc-federation-statement-fetch+jwt

{
 "alg": "RS256",
 "kid": "WU52Y3MxX0VTYWs0b1pwbXAxcVkzd1Y5YnY3OWJHeUZXczgtRl9Lc3VDTQ",
 "typ": "oidc-federation-statement-fetch+jwt"
}
.
{
  "iss": "https://openid.sunet.se",
  "iat": 1620050972,
  "exp": 1620072515,
  "statements": [
    {
      "iss": "https://openid.sunet.se",
      "sub": "https://spid.example.it",
      "iat": 1516239022,
      "exp": 1516298022,
      "metadata": {
        "openid_relying_party": {
          "application_type": "web",
          "redirect_uris": [
            "https://spid.example.it/rp/callback"
          ],
          "organization_name": "example",
          "logo_uri": "https://www.example.it/images/32x32.png",
          "grant_types": [
            "authorization_code"
          ],
          "signed_jwks_uri": "https://spid.example.it/rp/jwks.json"
        }
      },
      "jwks": {
        "keys": [
          {
            "alg": "RS256",
            "e": "AQAB",
            "key_ops": [
              "verify"
            ],
            "kid": "key1",
            "kty": "RSA",
            "n": "pnXBOusEANuug6ewezb9J_...",
            "use": "sig"
          }
        ]
      },
      "authority_hints": [
        "https://spid.registry.agid.it"
      ]
    }
  ],
  "page": 1,
  "total_pages": 1,
  "total_entries": 1,
  "next_page_path": "",
  "prev_page_path": ""
}
```

#### request for the entire subjects

```
GET /federation_statement_fetch HTTP/1.1
Host: openid.sunet.se
```

... as seen in the previous example, the pagination would do the job. The entity statements will be many inside the “statements” list.

* **federation\_list**, performs the current federation\_api listing with several changes compared to the current implementation, it would return a JWT object with the “entities“ claim valued as follows. Only the **iat** claim for each entity is REQUIRED, other claims may be supported as optionals. Each page must have not more than 100 entries, this allows us to serve these page as static contents \(with a smart httpd rewrite rule\). The claim “**iat**”, in root of the JWT, determine if the resultset have been updated.  
  The entities resultset must have a descendant ordering with higher iat on top, so as to explain which entities have been added or updated lately.

#### FeDERATION LIST RESPONSE

```
{
 "alg": "RS256",
 "kid": "WU52Y3MxX0VTYWs0b1pwbXAxcVkzd1Y5YnY3OWJHeUZXczgtRl9Lc3VDTQ",
 "typ": "oidc-federation-listing+jwt"
}
.
{
 "iss": "https://openid.sunet.se",
 "iat": 1620050972,
 "entities": [
   {
    "https://ntnu.andreas.labs.uninett.no/": {
       "iat": 1588455866,
   },
   {
    "https://blackboard.ntnu.no/openid/callback": {
       "iat": 1588455856,
   },
   {
    "https://serviceprovider.say.no/": {
       "iat": 1588355866,
   },
   ... # many other entries
 ],
"page": 1,
"total_pages": 2,
"total_entries": 189,
"next_page_path": "/federation_listing?page=2",
"prev_page_path": ""
}
```

* **federation\_trustmark\_introspection**, allows a verifier to submit a trustmark in the form of a JWT and obtain an introspection of this. This endpoint allows you to verify in real time whether a trust mark has been disabled/revoked by its issuer. This endpoint is mandatory for all anchor trusts that issue trust marks. Below is a proposal for its possible use, Roland will create a PR for this. This endpoint is protected by **private\_key\_jwt** client authentication

#### FEDERATION TRUSTMARK INTROSPECTION REQUEST

```
POST /federation_trustmark_introspection HTTP/1.1
Host: openid.sunet.se
Content-Type: application/x-www-form-urlencoded

trustmark=2Yot [... many other bytes ofthe signed JWT ...] WpAA
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=PHNhbWxwOl[...omitted for brevity...]ZT
```

#### FEDERATION TRUSTMARK INTROSPECTION RESPONSE

```
HTTP/1.1 200 OKContent-Type: application/federation-trustmark-introspection+jwt

{
 "typ": "federation-trustmark-introspection+jwt",
 "alg": "RS256","kid": "wG6D"
}
.
{
 "iss":"https://openid.sunet.se",
 "iat":1514797892,
 "active":true,
 "sub":"https://that.trustmarked.memb.er"
}
```

* **federation\_trust\_negotiation**, performs the current federation\_api resolve\_metadata operation. 

####   
The value for a paged result

  
The proposal to obtain a pagination of the results with an order of these that exposes on top the entities recently updated or added, wants to cover effectively the following use cases:

* **Federation resilience**. Having a way to get in sync in a time T with the latest changes published by intermediaries and trusted anchors even though their endpoints federation\_api are unreachable in a time T\+1, makes the entire federation more resilient. This strategy avoids the concentration of many connections to the endpoints during the hot moments of the days \(from 10am to  3pm\). DDOS on an Internet backbone or any other service interruption may be wary of creating trust between an RP and an OP. Getting a delta of the latest changes will allow members of a federation to update/create their own chains of trust with a polling strategy, entirely optional compared to the specific requirements but vital for a better resilience of the infrastructure.
* **SIOP**, cross device use case with offline interactions. 

##### SIOP User CASES

we are in an underground discoteque/market with poor bandwidth.  If the wallet keeps updating the federation statements it will work completely offline even for cross device communications.  
  
I need to establish a trust with the requester and this latter needs to establish a trust with the sender, nowaday for offline validations of covid green certificates, the mobile apps need to download the certificates and the revocation list. With oidc fed they just have to keep the trust chains updated.

Even more on mobile devices, using sqlite3, it would be trivial the storage of millions of entries, the updating process just need a way to get the delta of the members to get in sync with their trust chains \(here paged result with descending iat makes the job\).