6. Federation Metadata
This section preserves the RFC text for MATF, including federation trust model, metadata repository, public key pinning, JSON/JWS metadata, usage scenarios, deployments, security considerations, and JSON Schema.
6. Federation Metadata
Federation metadata is published as a JSON Web Signature (JWS)
[RFC7515]. The payload contains statements about entities of
federation members.
Metadata is used for authentication and service discovery. A client
selects a server based on metadata claims such as organization and
tags. To establish a connection, the client uses the base_uri, pins,
and, if needed, issuers of the selected server.
6.1. Federation Metadata Claims
This section defines the set of claims that can be included in
metadata.
* iat (REQUIRED)
Identifies the time at which the federation metadata was issued.
- Data Type: Integer
- Syntax: NumericDate as defined in [RFC7519], Section 4.1.6.
- Example: 1755514949
* exp (REQUIRED)
Identifies the expiration time on or after which the federation
metadata is no longer valid. Once the exp time has passed, the
metadata MUST be rejected regardless of cache state.
- Data Type: Integer
- Syntax: NumericDate as defined in [RFC7519], Section 4.1.4.
- Example: 1756119888
* iss (REQUIRED)
A URI uniquely identifying the issuing federation. This value
differentiates federations, prevents ambiguity, and ensures that
entities are recognized within their intended context.
Verification of the iss claim enables recipients to determine the
origin of the information and to establish trust with entities
within the identified federation.
- Data Type: String
- Syntax: StringOrURI as defined in [RFC7519], Section 4.1.1. In
MATF, this value MUST be a URI.
- Example: "https://federation.example.org"
* version (REQUIRED)
Indicates the schema version of the federation metadata. This
ensures compatibility between members of the federation by
defining a clear versioning mechanism for interpreting metadata.
- Data Type: String
- Syntax: The value MUST follow Semantic Versioning (see
<https://semver.org>).
- Example: "1.0.0"
* cache_ttl (OPTIONAL)
Specifies the duration in seconds for caching downloaded
federation metadata, allowing for independent caching outside of
specific HTTP configurations. This is particularly useful when
the communication mechanism is not based on HTTP. In the event of
a metadata publication outage, members can rely on cached metadata
until it expires, as indicated by the exp claim in the JWS
payload, defined in Section 6.1. Once expired, metadata MUST no
longer be trusted. If omitted, a mechanism to refresh metadata
MUST still exist to ensure the metadata remains valid.
- Data Type: Integer
- Syntax: Integer representing the duration in seconds.
- Example: 3600
* entities (REQUIRED)
Contains the list of entities within the federation.
- Data Type: Array of Objects
- Syntax: Each object MUST conform to the entity definition, as
specified in Section 6.1.1.
6.1.1. Entities
Metadata contains a list of entities that may be used for
communication within the federation. Each entity describes one or
more endpoints owned by a member. An entity has the following
properties:
* entity_id (REQUIRED)
A URI that uniquely identifies the entity. This identifier MUST
NOT collide with any other entity_id within the federation or
within any other federation that the entity interacts with.
- Data Type: String
- Syntax: URI as defined in [RFC3986].
- Example: "https://example.com"
* organization (OPTIONAL)
A name identifying the organization that the entity's metadata
represents. The federation operator MUST ensure that a mechanism
is in place to verify that the organization claim corresponds to
the rightful owner of the information exchanged between nodes.
This is crucial for the trust model, ensuring certainty about the
identities of the involved parties. The federation operator
SHOULD choose an approach that best suits the specific needs and
trust model of the federation.
- Data Type: String
- Syntax: A name identifying the organization represented by the
entity.
- Example: "Example Org"
* issuers (REQUIRED)
A list of certificate issuers allowed to issue certificates for
the entity's endpoints. For each issuer, the issuer's root CA
certificate MUST be included in the x509certificate property and
be encoded using the Privacy-Enhanced Mail (PEM) format.
Certificate verification relies on public key pinning, with the
list of allowed issuers used only when a certificate chain
validation mechanism is unavoidable. For self-signed
certificates, the certificate itself acts as its own issuer and
MUST be listed as such in the metadata.
- Data Type: Array of Objects
- Syntax: Each object contains an issuer certificate encoded as
PEM, as specified in [RFC7468]. The Base64 content MUST be
wrapped so that each line consists of exactly 64 characters,
except for the final line. In JSON text, line breaks in the
PEM value are represented using the "\n" escape sequence.
- Example: Issuer truncated for readability.
"issuers": [{
"x509certificate": "-----BEGIN CERTIFICATE-----\nMIIDDD"
}]
* servers (OPTIONAL)
Contains the list of servers within the entity.
- Data Type: Array of Objects
- Syntax: Each object MUST conform to the server definition, as
specified in Section 6.1.1.1.
* clients (OPTIONAL)
Contains the list of clients within the entity.
- Data Type: Array of Objects
- Syntax: Each object MUST conform to the client definition, as
specified in Section 6.1.1.1.
6.1.1.1. Servers / Clients
The entity's servers and clients are listed below.
* description (OPTIONAL)
A human-readable text describing the server or client.
- Data Type: String
- Syntax: Free-form text describing the server or client.
- Example: "SCIM Server 1"
* base_uri (REQUIRED for servers, OPTIONAL for clients)
The base URL of the server. This claim is REQUIRED for server
endpoints. The value MUST be an absolute URI as defined in
Section 4.3 of [RFC3986]. The value serves as the base URI for
resolving relative references to server resources, as described in
Section 5 of [RFC3986].
- Data Type: String
- Syntax: An absolute URI as defined in Section 4.3 of [RFC3986]
that is used as a URL.
- Example: "https://scim.example.com/"
* pins (REQUIRED)
A list of objects representing public key pins [RFC7469].
- Data Type: Array of Objects
- Syntax: A list of objects, where each object represents a
single public key pin with the following properties:
o alg (REQUIRED)
The name of the cryptographic hash algorithm. Currently,
the RECOMMENDED value is 'sha256'. As more secure
algorithms are developed over time, federations should be
ready to adopt these newer options for enhanced security.
+ Data Type: String
+ Syntax: The name of the algorithm.
+ Example: "sha256"
o digest (REQUIRED)
The public key of the end-entity certificate, converted to a
Subject Public Key Information (SPKI) fingerprint, as
specified in Section 2.4 of [RFC7469]. For clients, the
digest value MUST be unique across entities in the
federation metadata to enable unambiguous identification of
the peer. Within the same entity, the same digest value MAY
be assigned to multiple clients.
+ Data Type: String
+ Syntax: SPKI fingerprint.
+ Example: "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
- Example:
"pins": [{
"alg": "sha256",
"digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
}]
* tags (OPTIONAL)
A list of strings that describe the endpoint's capabilities.
- Data Type: Array of Strings
- Syntax: Strings describing endpoint capabilities.
- Pattern: ^[a-z0-9]{1,64}$
- Example: ["scim", "xyzzy"]
Tags are fundamental for discovery within a federation, aiding
both servers and clients in identifying appropriate connections.
- Server Tags: Tags associated with servers are used by clients
to discover servers offering the services they require.
Clients can search for servers based on tags that indicate
supported protocols or the type of data they handle, enabling
discovery of compatible servers.
- Client Tags: Tags associated with clients are used by servers
to identify clients with specific characteristics or
capabilities. For instance, a server might only accept
connections from clients that support particular protocols. By
filtering incoming requests based on these tags, servers can
identify suitable clients.
Federation-Specific Considerations: While tags are tied to
individual federations and serve distinct purposes within each,
several key considerations are crucial to ensure clarity and
promote consistent tag usage:
- Well-Defined Scope: Each federation MUST establish a clear
scope for its tags, detailing their intended use, allowed tag
values, associated meanings, and any relevant restrictions.
Maintaining a well-defined and readily accessible registry of
approved tags is essential for the federation.
- Validation Mechanisms: Implementing validation mechanisms for
tags is highly recommended. This can involve a dedicated
operation or service verifying tag validity and compliance with
the federation's regulations. Such validation ensures
consistency within the federation by preventing the use of
unauthorized or irrelevant tags.
6.2. Metadata Schema
The MATF metadata schema is defined in Appendix A. This schema
specifies the format for describing entities involved in MATF and
their associated information.
| Note: The schema in Appendix A is folded due to line length
| limitations as specified in [RFC8792].
6.3. Example Metadata
The following is a non-normative example of a metadata statement.
Line breaks in the issuers claim example are for readability only.
{
"iat": 1755514949,
"exp": 1756119888,
"iss": "https://federation.example.org",
"version": "1.0.0",
"cache_ttl": 3600,
"entities": [{
"entity_id": "https://example.com",
"organization": "Example Org",
"issuers": [{
"x509certificate": "-----BEGIN CERTIFICATE-----\nMIIDDDCCAf
SgAwIBAgIJAIOsfJBStJQhMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\nBAM
MEHNjaW0uZXhhbXBsZS5jb20wHhcNMTcwNDA2MDc1MzE3WhcNMTcwNTA2MD
c1\nMzE3WjAbMRkwFwYDVQQDDBBzY2ltLmV4YW1wbGUuY29tMIIBIjANBgk
qhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAyr+3dXTC8YXoi0LDJTH0lTfv
8omQivWFOr3+/PBE\n6hmpLSNXK/EZJBD6ZT4Q+tY8dPhyhzT5RFZCVlrDs
e/kY00F4yoflKiqx9WSuCrq\nZFr1AUtIfGR/LvRUvDFtuHo1MzFttiK8Wr
wskMYZrw1zLHTIVwBkfMw1qr2XzxFK\njt0CcDmFxNdY5Q8kuBojH9+xt5s
ZbrJ9AVH/OI8JamSqDjk9ODyGg+GrEZFClP/B\nxa4Fsl04En/9GfaJnCU1
NpU0cqvWbVUlLOy8DaQMN14HIdkTdmegEsg2LR/XrJkt\nho16diAXrgS25
3xbkdD3T5d6lHiZCL6UxkBh4ZHRcoftSwIDAQABo1MwUTAdBgNV\nHQ4EFg
QUs1dXuhGhGc2UNb7ikn3t6cBuU34wHwYDVR0jBBgwFoAUs1dXuhGhGc2U\
nNb7ikn3t6cBuU34wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAA
OCAQEA\nrR9wxPhUa2XfQ0agAC0oC8TFf8wbTYb0ElP5Ej834xMMW/wWTSA
N8/3WqOWNQJ23\nf0vEeYQwfvbD2fjLvYTyM2tSPOWrtQpKuvulIrxV7Zz8
A61NIjblE3rfea1eC8my\nTkDOlMKV+wlXXgUxirride+6ubOWRGf92fgze
DGJWkmm/a9tj0L/3e0xIXeujxC7\nMIt3p99teHjvnZQ7FiIBlvGc1o8FD1
FKmFYd74s7RxrAusBEAAmBo3xyB89cFU0d\nKB2fkH2lkqiqkyOtjrlHPoy
6ws6g1S6U/Jx9n0NEeEqCfzXnh9jEpxisSO+fBZER\npCwj2LMNPQxZBqBF
oxbFPw==\n-----END CERTIFICATE-----"
}],
"servers": [{
"description": "SCIM Server 1",
"base_uri": "https://scim.example.com/",
"pins": [{
"alg": "sha256",
"digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
}],
"tags": [
"scim"
]
}],
"clients": [{
"description": "SCIM Client 1",
"pins": [{
"alg": "sha256",
"digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
}]
}]
}]
}
6.4. Metadata Signing
Federation metadata is signed using JWS and published using JWS JSON
Serialization according to the general JWS JSON Serialization syntax
defined in [RFC7515]. Federation metadata signatures are RECOMMENDED
to be created using the algorithm ECDSA using P-256 and SHA-256
("ES256") as defined in [RFC7518]. However, to accommodate evolving
cryptographic standards, alternative algorithms MAY be used, provided
they meet the security requirements of the federation.
Federations may need to transition to post-quantum cryptographic
algorithms for federation metadata signatures and for endpoint
certificate public key types. MATF can accommodate such transitions
through key rollover and by updating published pins as new key types
are deployed.
The following JWS Protected Header parameters are REQUIRED:
* alg (Algorithm)
Identifies the algorithm used to generate the JWS signature
[RFC7515], Section 4.1.1.
* kid (Key Identifier)
Identifies the key in the issuer's key set that was used to
generate the JWS signature [RFC7515], Section 4.1.4.
6.5. Example Signature Protected Header
The following is a non-normative example of a signature protected
header.
{
"alg": "ES256",
"kid": "c2fb760e-f4b6-4f7e-b17a-7115d2826d51"
}