Trustworthy Federation Registry API

Full Title

Trust Federation Membership Validation based on 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 of websites and mobile apps as a part of the reference federation.
• Websites and apps can supply an entity statement issued by a Trust Registry and validate the currency of that validation with the Registry.

Problems

1. The user in an ID Ecosystem currently has limited resources to determine the validity and trustworthiness of the web sites visited or of the apps offered to allow authenticated access to websites in that federation.
2. In OpenID Connect 1.0 it is assumed that the Identity Provider (IdP) and the Attribute Provider (AP) share the same information about the identity and consent of the user. In a federated environment this requires an additional level of abstraction between the IdP and the AP to accommodate the likenly differences in the identifiers used for the subject and other entities to the transaction. Note that the AP is called the "Resource" in the OpenID specs and may provide access to other content than user attributes, but that is beyond the scope of this discussion.

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.
• The Entity statement for each endpoint must contain the information needed to identify the role of the endpoint and to allow interoperation between the various endpoints in the federation.

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/idef/registry?
iss=https%3A%2F%2Fopenid.sunet.se%2Ffederation HTTP/1.1
Host: idef.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)

Entity Listings (OPTIONAL)

An entity may query another entity for a list of all the entities that match a query for which the entity is prepared to issue statements.

Entity Listings 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

REQUIRED. MUST be set to listing.

• iss

REQUIRED. The entity identifier of the entity from which an entity listing is requested. Because of the normalization of the URL, multiple entity identifiers may resolve to a shared federation API. This parameter makes it explicit exactly which entity is expected.

• type

OPTIONAL. Provide this parameter to filter the results to entity statements that contain entries for this specific metadata type.

• sub_is_leaf

OPTIONAL. If left out, result should include both leaf entities and intermediate nodes. If set to true, the response should contain only leaf entities. If set to false, the response should contain only intermediate nodes.

• metadata_claims

OPTIONAL. A comma separated list of claim names that the requester would like to get values for for each entity. If left out or an empty string, the response should contain an empty object for each of the known entities. The set of claim names that can be used are defined in metadata. *Note* that while type and sub_is_leaf can be used to filter out which entities to return this only affects what is returned about each returned entity.

The following is a non-normative example of an API request for trust negotiation: GET /.well-known/openid-federation? op=listing& iss=https%3A%2F%2Fopenid.sunet.se%2Ffederation& type=openid_client& metadata_claims=client_name HTTP/1.1 Host: openid.sunet.se

Entity Listing Response

The response MUST contain an JSON object where the known entity identifiers are the property keys, and a JSON object with the requested claims is the property value. Requested claims that the responder is not able to provide should be left out. A non-normative example of a response:

200 OK
Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT
Content-Type: application/json

{
  "https://ntnu.andreas.labs.uninett.no/": {
    "client_name": "NTNU Labs"
  },
  "https://blackboard.ntnu.no/openid/callback": {
    "client_name": "Blackboard"
  },
  "https://serviceprovider.andreas.labs.uninett.no/application17": {
    "client_name": "Test application"
  }
}

Generic Error Response

If the request was malformed, or some error occurred during processing of the request, the following standardized error format should be used regardless of the operation specified. The HTTP response code MUST be something in 400/500-range, giving an indication of the type of error. The response body MUST be a JSON object containing the claims below and the content type MUST be set to application/json.:

• op

REQUIRED. Which operation was the request processed as.

• error

REQUIRED. The error code.

• error_description

REQUIRED. A human readable short text describing the error.

A non-normative example of an error response:

400 Bad request
Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT
Content-Type: application/json

{
  "op": "fetch",
  "error": "invalid_request",
  "error_description":
    "Required request parameter [iss] was missing."
}

References

• This specification was derived from The OpenID Connect Federation spec (draft 10) and other documents, some of which are included below.
• The HL7 FHIR plication Launch Framework Implementation Guide Release 1.0.0 was used to ensure that its needs were met.