6. Federation Metadata (联邦元数据)

Federation Metadata (联邦元数据) 以 JSON Web Signature (JWS) [RFC7515] 形式发布. 其负载包含关于联邦成员实体的声明 (claim).

元数据用于认证和服务发现. 客户端根据组织和标签等元数据声明选择服务器. 为了建立连接, 客户端使用所选服务器的 base_uri, pins, 以及在需要时使用 issuers.

6.1. Federation Metadata Claims (联邦元数据声明)

本节定义可包含在元数据中的一组声明.

iat (REQUIRED)

标识 Federation Metadata 的签发时间.
- 数据类型: Integer
- 语法: NumericDate, 如 [RFC7519] 第 4.1.6 节所定义.
- 示例: 1755514949
exp (REQUIRED)

标识 Federation Metadata 不再有效的到期时间或其后的时间. 一旦 exp 时间已经过去, 无论缓存状态如何, metadata 都 MUST 被拒绝.
- 数据类型: Integer
- 语法: NumericDate, 如 [RFC7519] 第 4.1.4 节所定义.
- 示例: 1756119888
iss (REQUIRED)

唯一标识签发联邦的 URI. 该值用于区分联邦, 防止歧义, 并确保在预期上下文中识别实体. 对 iss claim 的验证使接收方能够确定信息来源, 并与所标识联邦内的实体建立信任.
- 数据类型: String
- 语法: StringOrURI, 如 [RFC7519] 第 4.1.1 节所定义. 在 MATF 中, 该值 MUST 是 URI.
- 示例: "https://federation.example.org"
version (REQUIRED)

指示 Federation Metadata 的 schema version. 通过定义清晰的 metadata 解释版本机制, 该字段确保联邦成员之间的兼容性.
- 数据类型: String
- 语法: 该值 MUST 遵循 Semantic Versioning (见 https://semver.org).
- 示例: "1.0.0"
cache_ttl (OPTIONAL)

指定已下载 Federation Metadata 的缓存持续时间, 单位为秒, 从而允许在特定 HTTP 配置之外进行独立缓存. 当通信机制不基于 HTTP 时, 这一点尤其有用. 如果发生 metadata 发布中断, 成员可以依赖缓存的 metadata, 直到 JWS 负载中的 exp claim 指示其过期为止, 该 claim 定义于第 6.1 节. 一旦过期, metadata MUST 不再被信任. 如果省略该字段, 仍然 MUST 存在一种刷新 metadata 的机制, 以确保 metadata 保持有效.
- 数据类型: Integer
- 语法: 表示持续时间秒数的 Integer.
- 示例: 3600
entities (REQUIRED)

包含联邦内实体的列表.
- 数据类型: Array of Objects
- 语法: 每个对象 MUST 符合第 6.1.1 节指定的 entity 定义.

6.1.1. Entities (实体)

元数据包含可用于联邦内通信的实体列表. 每个实体描述成员拥有的一个或多个端点 (endpoint). 实体具有以下属性:

entity_id (REQUIRED)

唯一标识实体的 URI. 该标识符 MUST NOT 与联邦内的任何其他 entity_id 冲突, 也 MUST NOT 与该实体交互的任何其他联邦内的 entity_id 冲突.
- 数据类型: String
- 语法: URI, 如 [RFC3986] 所定义.
- 示例: "https://example.com"
organization (OPTIONAL)

标识实体 metadata 所代表组织的名称. 联邦运营方 MUST 确保存在一种机制, 用于验证 organization claim 与节点之间交换的信息的合法所有者相对应. 这对于信任模型至关重要, 可确保明确参与方的身份. 联邦运营方 SHOULD 选择最适合该联邦具体需求和信任模型的方法.
- 数据类型: String
- 语法: 标识实体所代表组织的名称.
- 示例: "Example Org"
issuers (REQUIRED)

允许为实体端点签发证书的证书签发者列表. 对于每个 issuer, issuer 的 root CA certificate MUST 包含在 x509certificate 属性中, 并使用 Privacy-Enhanced Mail (PEM) 格式编码. 证书验证依赖 public key pinning (公钥固定), 仅当无法避免使用证书链验证机制时, 才使用允许的 issuer 列表. 对于自签名证书, 证书本身充当自己的 issuer, 并且 MUST 以此身份列在 metadata 中.
- 数据类型: Array of Objects
- 语法: 每个对象包含一个按 PEM 编码的 issuer certificate, 如 [RFC7468] 所指定. Base64 内容 MUST 被换行, 使每行恰好包含 64 个字符, 最后一行除外. 在 JSON 文本中, PEM 值中的换行使用 "\n" 转义序列表示.
- 示例: 为便于阅读, issuer 已截断.

"issuers": [{
  "x509certificate": "-----BEGIN CERTIFICATE-----\nMIIDDD"
}]

servers (OPTIONAL)

包含实体内服务器的列表.
- 数据类型: Array of Objects
- 语法: 每个对象 MUST 符合第 6.1.1.1 节指定的 server 定义.
clients (OPTIONAL)

包含实体内客户端的列表.
- 数据类型: Array of Objects
- 语法: 每个对象 MUST 符合第 6.1.1.1 节指定的 client 定义.

6.1.1.1. Servers / Clients (服务器 / 客户端)

实体的 servers 和 clients 如下所列.

description (OPTIONAL)

描述服务器或客户端的可读文本.
- 数据类型: String
- 语法: 描述服务器或客户端的自由格式文本.
- 示例: "SCIM Server 1"
base_uri (REQUIRED for servers, OPTIONAL for clients)

服务器的 base URL. 对于服务器端点, 该 claim 是 REQUIRED. 该值 MUST 是 [RFC3986] 第 4.3 节定义的 absolute URI. 如 [RFC3986] 第 5 节所述, 该值用作解析服务器资源相对引用的 base URI.
- 数据类型: String
- 语法: [RFC3986] 第 4.3 节定义的 absolute URI, 并作为 URL 使用.
- 示例: "https://scim.example.com/"
pins (REQUIRED)

表示 public key pins [RFC7469] 的对象列表.
- 数据类型: Array of Objects
- 语法: 对象列表, 其中每个对象表示单个 public key pin, 并具有以下属性:
  - alg (REQUIRED)
    
    密码学哈希算法的名称. 当前 RECOMMENDED 值为 'sha256'. 随着更安全算法逐步发展, 联邦应准备采用这些较新的选项来增强安全性.
    - 数据类型: String
    - 语法: 算法名称.
    - 示例: "sha256"
  - digest (REQUIRED)
    
    终端实体证书的公钥, 转换为 Subject Public Key Information (SPKI) fingerprint, 如 [RFC7469] 第 2.4 节所指定. 对于客户端, digest 值在 Federation Metadata 的各实体之间 MUST 唯一, 以支持对对等方 (peer) 的无歧义识别. 在同一实体内, 同一个 digest 值 MAY 分配给多个客户端.
    - 数据类型: String
    - 语法: SPKI fingerprint.
    - 示例: "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
- 示例:

"pins": [{
  "alg": "sha256",
  "digest": "+hcmCjJEtLq4BRPhrILyhgn98Lhy6DaWdpmsBAgOLCQ="
}]

tags (OPTIONAL)

描述端点能力的字符串列表.
- 数据类型: Array of Strings
- 语法: 描述端点能力的字符串.
- 模式: ^[a-z0-9]{1,64}$
- 示例: ["scim", "xyzzy"]
Tags 是联邦内发现的基础, 帮助 servers 和 clients 识别适当连接.
- Server Tags: 与服务器关联的 tags 由客户端用于发现提供其所需服务的服务器. 客户端可以根据指示所支持协议或所处理数据类型的 tags 搜索服务器, 从而发现兼容服务器.
- Client Tags: 与客户端关联的 tags 由服务器用于识别具有特定特征或能力的客户端. 例如, 服务器可能只接受来自支持特定协议的客户端的连接. 通过基于这些 tags 过滤传入请求, 服务器可以识别合适的客户端.
Federation-Specific Considerations: 虽然 tags 绑定到各个联邦, 并在每个联邦内服务于不同目的, 但若要确保清晰性并促进 tags 的一致使用, 以下几个关键考虑事项至关重要:
- Well-Defined Scope: 每个联邦 MUST 为其 tags 建立清晰的 scope, 详细说明其预期用途, 允许的 tag 值, 相关含义以及任何相关限制. 维护一个定义清晰且易于访问的已批准 tags 注册表, 对联邦而言至关重要.
- Validation Mechanisms: 强烈推荐实现 tags 的 validation mechanisms. 这可以包括由专用操作或服务验证 tag 的有效性, 以及其是否符合联邦规定. 这种验证通过防止使用未经授权或无关的 tags, 确保联邦内的一致性.

6.2. Metadata Schema (元数据模式)

MATF metadata schema 在 Appendix A 中定义. 该 schema 指定了描述 MATF 所涉及实体及其关联信息的格式.

Note: Appendix A 中的 schema 根据 [RFC8792] 规定, 由于行长限制而进行了折叠.

6.3. Example Metadata (元数据示例)

以下是 metadata statement 的非规范性示例. issuers claim 示例中的换行仅用于提高可读性.

{
  "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 使用 JWS 签名, 并根据 [RFC7515] 中定义的一般 JWS JSON Serialization 语法, 使用 JWS JSON Serialization 发布. Federation Metadata 签名 RECOMMENDED 使用 [RFC7518] 中定义的 ECDSA using P-256 and SHA-256 ("ES256") 算法创建. 但是, 为了适应不断发展的密码学标准, 也 MAY 使用替代算法, 前提是这些算法满足联邦的安全要求.

联邦可能需要将 Federation Metadata 签名和端点证书公钥类型迁移到后量子密码算法. MATF 可以通过 key rollover (密钥轮换), 并随着部署新的密钥类型而更新已发布的 pins, 来适应这类迁移.

以下 JWS Protected Header 参数是 REQUIRED:

alg (Algorithm)

标识用于生成 JWS 签名的算法 [RFC7515], 第 4.1.1 节.
kid (Key Identifier)

标识签发者 key set 中用于生成 JWS 签名的密钥 [RFC7515], 第 4.1.4 节.

6.5. Example Signature Protected Header (签名保护头部示例)

以下是 signature protected header 的非规范性示例.

{
    "alg": "ES256",
    "kid": "c2fb760e-f4b6-4f7e-b17a-7115d2826d51"
}

6.1. Federation Metadata Claims (联邦元数据声明)​

6.1.1. Entities (实体)​

6.1.1.1. Servers / Clients (服务器 / 客户端)​

6.2. Metadata Schema (元数据模式)​

6.3. Example Metadata (元数据示例)​

6.4. Metadata Signing (元数据签名)​

6.5. Example Signature Protected Header (签名保护头部示例)​