Disclaimer

This document provides an overview of the Swefed OIDF Sandbox environment. It focuses on metadata handling, trust chain validation, and Trust Mark usage in the context of OpenID Federation 1.0. For complete details, consult the OpenID Federation 1.0 specification - draft 43.

Introduction

The Swefed OIDF Sandbox is an isolated environment for testing OpenID Federation. It allows Relying Parties, OpenID Providers, and supporting entities to validate interoperability, metadata exchange, and trust chain resolution under a Trust Anchor.

Federation Architecture and Core Entities

The federation has a hierarchical structure with the Trust Anchor as the root of trust. Subordinate entities include Resolvers, Intermediates, Trust Mark Issuers, OpenID Providers, and Relying Parties.

Entities and Their Roles

Trust Anchor: Root of trust. Defines policies and signs metadata.

Resolver: Provides trust chain resolution services, enabling entities to validate metadata against the Trust Anchor.

Intermediate: Manages subordinate entities and aggregates metadata.

Trust Mark Issuer: Issues signed Trust Marks certifying compliance with federation requirements.

OpenID Provider: Authenticates users and issues tokens under federation policies.

Relying Party: Consumes identity information from OpenID Providers through validated trust chains.

Trust Workflow

Each entity publishes an Entity Configuration at /.well-known/openid-federation. This is a signed JWT containing the entity identifier, role-specific metadata, authority hints, and a JWKS by value. Trust Marks may be included.

Validation is done by building a trust chain from the entity to the Trust Anchor. The chain is verified using the Trust Anchor's keys. Trust Marks add assurance of policy compliance.

Trust is established dynamically through metadata exchange and chain resolution, enabling scalable onboarding without static configuration.

Trust Mark Issuance

A Trust Mark Issuer evaluates an entity against defined requirements. If compliant, it issues a signed JWT Trust Mark including the required claims iss (issuer), sub (subject), id (trust mark identifier), iat (issued at), and exp (expiration).

Examples

RP to OP Interaction

1. The Relying Party fetches the OpenID Provider’s Entity Configuration.
2. The Relying Party resolves and validates the trust chain using the Resolver to the Trust Anchor.
3. If trust is valid, the Relying Party registers with the OpenID Provider.
4. Authentication and token flows proceed under validated trust.

Fetching Entity Configuration

The following command extracts and displays the payload of an Entity Configuration. It is useful for inspection, but it does not validate the JWT signature. Signature validation must always be performed with trusted keys.

curl -s https://trust-anchor.oidf.swefed.se/.well-known/openid-federation \
| cut -d '.' -f2 \
| tr '_-' '/+' \
| base64 -d 2>/dev/null \
| jq .

Explanation of each step

• curl -s: fetches the JWT, -s silences progress.

• cut -d '.' -f2: extracts the payload from the JWT (middle part).

• tr '_-' '/+': translates Base64URL alphabet into standard Base64.

• base64 -d: decodes the payload.

• jq .: pretty-prints the JSON.

Nodes

The following nodes are available in the Swefed OIDF Sandbox.

Trust Anchor

• URL: https://trust-anchor.oidf.swefed.se
• Role: Root of trust. Publishes federation policies and signing keys.
• Provides federation endpoints: fetch, list, resolve.

Resolver

• URL: https://trust-anchor.oidf.swefed.se (co-located with TA)
• Role: Resolves trust chains by processing authority hints and building validated chains up to the TA.
• Endpoint: /resolve.

Trust Mark Issuer

• URL: https://trust-mark-issuer.oidf.swefed.se
• Role: Issues and manages Trust Marks.
• Provides endpoints: trust_mark, trust_mark_list, trust_mark_status.
• Declares the Trust Anchor in authority_hints.

Intermediate

• URL: https://intermediate.oidf.swefed.se
• Role: Aggregates and distributes metadata.
• Provides federation endpoints: fetch, list, resolve.
• Declares the Trust Anchor in authority_hints.

OpenID Provider

• URL: https://op.oidf.swefed.se
• Role: Provides authentication and token services.
• Publishes OP metadata in the metadata.openid_provider section.
• Trust is established dynamically through its Entity Configuration and chain to the TA.

Relying Party

• URL: https://rp.oidf.swefed.se
• Role: Consumes tokens and user information from OPs.
• Publishes RP metadata in the metadata.openid_relying_party section.
• Trust is established dynamically through its Entity Configuration and chain to the TA.

Usage Notes

• All nodes expose their Entity Configuration at /.well-known/openid-federation.
• Trust chains must always be validated against the Trust Anchor.
• JWT signatures must be verified with the published keys from trusted entities.
• Trust Marks must be validated against the Trust Mark Issuer’s published metadata.

Entity Integration

This section explains how to connect an entity to the Swefed Sandbox Trust Infrastructure. It covers metadata exposure, configuration of trust anchors, authority hints, and trust marks.

Prerequisites

• Network access from your entity to the Sandbox Trust Anchor
• Externally accessible HTTPS endpoint for your entity

Key Configuration Points

entity Configuration Information

The entity must expose an entity configuration document at:

/.well-known/openid-federation

The configuration endpoint publishes the entity Configuration document, which provides the entity’s configuration details for participants in the Trust Infrastructure.

• Define the Endpoint: The endpoint is defined under the following path: /.well-known/openid-federation
• Implementation: Ensure this endpoint serves the entity’s entity Configuration.

Shortened example of an entity Configuration:

{
  "sub": "https://my-entity.example.com",
  "authority_hints": [
    "https://mi-intermediate.example.org"
  ],
  "metadata": {
    "federation_entity": {
      "organization_name": "Example Org",
      "contacts": ["support@example.com"]
    },
    "oauth_authorization_server": {
      "token_endpoint": "https://entity.example.com/token",
      "authorization_endpoint": "https://entity.example.com/authorize",
      "jwks_uri": "https://entity.example.com/jwks/oauth"
    },
  },
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "use": "sig",
        "kid": "example-key-id",
        "e": "AQAB",
        "n": "example-modulus"
      }
    ]
  }
}

Trust Anchors

The Trust Anchor is the root of the Trust Infrastructure’s trust chain. Trust Anchors establish trust within the federation by defining policies and anchoring trust chains.

• Trust Anchor URL: For your setup, the Trust Anchor URL is: https://trust-anchor.oidf.swefed.se
• Trust Anchor Keys: Add the Trust Anchor’s and public keys to your configuration
  

  { "jwks": { "keys": [ { "kty": "RSA", "use": "sig", "kid": "d2ZPZDVKa0Z4N1J4LTB2VWM1VFFhTUdSdnU3czZKQzhwc1F1U3ZHWEV3SQ", "e": "AQAB", "n": "lzLK1jAEMh4duP6Ym_pHWXYJZkJ-LuJvPHqIuQrxZnEhB4ODpA0hfj9g2UdBBVzbZdhOXKg9ObTQhG_TTISDliyjKAphxF5EObMpPtCoy_ImZ262zRdK4nii6AGVuABd5777GEBIwb-zZncWypjCX-1T6CBVECi4DnoHGDHDWhBTcIa9DE6ZDAjAgrKeiDz96gOL3BrGTYHDkjIpp__FP9dZJXJjgDV2n0cvC_MDmp8N8C-Rc1vd63lpmoXxvIqBy8bSM8jXSDxPTNkcJdlducNo9sR9j-7TsGdgE9PNK-iVzyp67QnmokreMCHx3NExkmi-MfkHrPAHwE_OneNVhw" }, { "kty": "EC", "use": "sig", "kid": "R180Y3dtOWY2TzVoU3NYT1I2OUcyay0waWdVYVJ2YkFQZmRqaDBJZHZPMA", "crv": "P-256", "x": "OSKZj-f9PT5UKWHiQ-VdhY-gfh0h-dA_weaYFqfkuUg", "y": "4y8u3C-CMWySQFMHN0tvafgwKWbDLS5XSQEo83HupyY" } ] } }

Authority Hints

The authority_hints parameter specifies the URL of the Intermediate Entities or Trust Anchors that are Immediate Superiors of the entity. This helps other Trust Infrastructure participants understand upstream trust relationships.

• Add to Configuration: Add authority_hints in your entity’s configuration

Registering the Entity as a Subordinate Entity

In the Sandbox Trust Infrastructure, every entity must be registered as a Subordinate Entity under a Superior Entity (such as a Trust Anchor or an Intermediate). Registration ensures that the entity is formally included in the federation trust hierarchy.

Preparing the Registration Document

To register, you must prepare a JSON document that includes your entity identifier, declared entity types, and public keys.

Start with this template:

{
  "<entity-identifier>": {
    "entity_types": [
      "federation_entity",
      "<additional-entity-types>"
    ],
    "jwks": {
      "keys": [
        {
          "kty": "RSA",
          "use": "sig",
          "kid": "example-kid",
          "n": "example-n-value",
          "e": "AQAB"
        }
      ]
    }
  }
}

Instructions

• Replace <entity-identifier> with the entity_id of your entity (typically its HTTPS URL).

• Every entity must include federation_entity as one of its types.

• Add the entity types that apply to your role in the Sandbox:

  • openid_relying_party for RPs.
  • openid_provider for OPs.
  • oauth_authorization_server for entities acting as OAuth 2.0 AS.

• Place your public keys in the "jwks" section. Only public key parameters are included. Private key material must never be published.

Example

{
  "https://entity.example.com": {
    "entity_types": [
      "federation_entity",
      "openid_provider",
      "oauth_authorization_server"
    ],
    "jwks": {
      "keys": [
        {
          "kty": "RSA",
          "use": "sig",
          "kid": "abc123",
          "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAF...",
          "e": "AQAB"
        }
      ]
    }
  }
}

This registration document should be submitted to the Sandbox operator to complete onboarding of the entity.

Trust Marks

Trust Marks are JWTs issued by a Trust Mark entity to validate compliance with Trust Infrastructure policies.

Types of Trust Marks

The following Trust Marks are available for issuance:

TBD

Retrieving Trust Marks

Trust Marks will be supplied on request.

1. Inputs to Trust Mark Issuer operator:
   • id: The identifier for the Trust Mark.
   • sub: The entity's entity Identifier.
2. Steps:
   • Supply the id and sub to the Trust Mark entity.
   • Retrieve the issued Trust Mark as a signed JWT.
3. Include in Metadata: Add issued Trust Marks to your entity’s metadata:

Look for the updated trust_marks in the JSON response.

Testing Trust Marks

1. Decode JWT: Use tools like jwt.io to inspect the Trust Mark's claims and ensure all required fields are present.
2. Verify Signature: Validate the JWT signature against the Trust Mark entity's public key.
3. Check Expiration: Ensure the exp claim (if present) has not expired.
4. Validate References: Follow the ref URL (if provided) to confirm compliance with human-readable policy documents.

Steps to Connect the entity

1. Configure the entity:
   • Update the entity’s configuration to include authority_hints, trust_marks, and trust_anchors.
2. Register with the Trust Infrastructure:
   • Share your entity_registration.json with the Trust Anchor or superior entity for registration.
3. Validate Configuration:
   • Test the entity using testing tools or with other entities sandbox environment.
4. Monitor the Connection:
   • Regularly verify the status and ensure Trust Marks are up-to-date.

Testing the Trust Relationships

1. Validate trust marks
   Use tools like jwt.io to decode and verify trust marks using the Trust Anchor's public keys.

2. Retrieve metadata
   Ensure the .well-known/openid-federation endpoint correctly serves the entity’s entity configuration:

   curl https://your-entity.example.com/.well-known/openid-federation

3. Check authority hints
   Verify that authority_hints points to the correct Superior

4. Validate public keys
   Confirm that the Trust Anchor’s public keys match those provided in your local configuration.