Trustworthy Federation Registry API

Full Title

Identity Ecosystem Framework Registry (IDEF-R) Application Program Interface.

Context

• The context is defined in the wiki page Trust Framework Membership Validation.
• This page defines the API to enable validation.

Problem

• The user of a ID Ecosystem currently has limited resources to determine the validity and trustworthiness of the web sites visited.

Solution

All entities that are expected to publish entity statements about themselves or other entities, MUST expose a Federation API endpoint. The federation API endpoint of an entity is resolved from the entity identifier. The Federation API endpoint is found using the Well known URIs specification, with the suffix openid-federation. The scheme, host and port is taken directly from the entity identifier combined with the following path: /.well-known/idef and followed by the specific endpoint name.

• Note* that since the path component of a entity ID is not included when constructing the URL above, one API endpoint may serve as the federation API endpoint for several entities.

The Federation API is an HTTPS API that may support multiple operations. Fetching entity statements is one of the operations, and the only one that all Federation API endpoints are REQUIRED to support. All the other operations are OPTIONAL. The list of defined operations may be extended in a future.

While all operations in the specification make use of a GET request, other operations may choose to use other HTTP methods. If the op parameter is left out, it is considered to be a fetch entity statements request. Unless otherwise agreed, requests to the federation API are not authenticated.

Fetching Entity Statement (REQUIRED)

Fetching entity statement is used to collect entity statements one by one in order to gather trust chains. In order to fetch an entity statement, an entity needs to know the identifier of the entity to ask (the issuer), and the identifier of the entity that you want the statement to be about (the subject).

Fetch Entity Statements Request

The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:

• op

OPTIONAL. If not present MUST be treated as fetch.

• iss

REQUIRED. The entity identifier of the issuer from which you want an entity statement issued. Because of the normalization of the URL, multiple issuers may resolve to a shared federation API. This parameter makes it explicit exactly which issuer we want entity statements from.

• sub

OPTIONAL. The entity identifier of the subject for which you would like an entity statement issued. If this parameter is left out, it is considered to be the same as the issuer, and would indicate a request for a self issued statement.

• aud

OPTIONAL. The entity identifier of the requester. The issuing entity may choose to include this parameter to form the entity statement specifically for this target, in which the aud claim also SHOULD be present in the entity statement self.

The following is a non-normative example of an API request for an entity statement:

GET /.well-known/openid-federation?
iss=https%3A%2F%2Fopenid.sunet.se%2Ffederation HTTP/1.1
Host: openid.sunet.se

Fetch Entity Statements Response

A positive response is a signed entity statement where the content type MUST be set to application/jose. If it is negative response it will be a JSON object and the content type MUST be set to application/json. More about error responses below A non-normative example of a response:

200 OK
Last-Modified: Mon, 17 Dec 2018 11:15:56 GMT
Content-Type: application/jose

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodHRwczovL3Nlc...
(the signed JWT is truncated)