Page History

...

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

Key Configuration Points

...

entity Configuration Information

Each The entity must expose its Entity Configuration an entity configuration document at:

/.well-known/openid-federation

Trust Anchors

The Sandbox Trust Anchor (TA) is the root of trust for the federation. All trust chains must terminate at this Trust Anchor. Entities must include the TA in their configuration for proper validation.

...

Trust Anchor URL: https://trust-anchor.oidf.swefed.se

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:
...
 Code Block
language
js
{
...
  "
...
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
 Code Block
language
js
{
    "jwks": {
    "crv": "P-256",
                "x": "OSKZj-f9PT5UKWHiQ-VdhY-gfh0h-dA_weaYFqfkuUg",
                "ykeys": "4y8u3C-CMWySQFMHN0tvafgwKWbDLS5XSQEo83HupyY"[
            }{
          ]
    }
}
Registering as a Subordinate Entity
Entities are formally connected to the federation by registering under a superior. Registration consists of:
Publishing the Entity Configuration with correct metadata and keys
Supplying the entity identifier (URL)
Ensuring the authority_hints field points to the correct superior
Authority Hints
Entities must declare their immediate superior in the trust hierarchy.
Example:
"authority_hints": [
  "https://intermediate.oidf.swefed.se"
]
Trust Marks
Trust Marks may be required depending on Sandbox policies.
Trust Mark Issuer URL: https://trust-mark-issuer.oidf.swefed.se
Entities can request signed Trust Marks to certify compliance with Sandbox requirements. Issued Trust Marks are included in the trust_marks field of the Entity Configuration.
Steps to Connect
Configure the Entity
Publish a valid Entity Configuration at /.well-known/openid-federation.
Include keys, metadata, and authority hints.
Reference the Trust Anchor
Ensure the Trust Anchor URL is included in authority_hints.
Register with the Sandbox
Share the entity identifier with the Sandbox operators to complete registration.
Request Trust Marks (if required)
Contact the Trust Mark Issuer for any required Trust Marks and include them in your configuration.
Testing the Trust Relationships
Retrieve metadata Fetch your entity’s Entity Configuration and verify the payload:
curl -s https://<entity-host>/.well-known/openid-federation | cut -d '.' -f2 | tr '_-' '/+' | base64 -d | jq .
Check authority hints Confirm that the authority_hints field points to the Sandbox Trust Anchor or an Intermediate.
Resolve trust chain Use the Resolver at https://trust-anchor.oidf.swefed.se/resolve to validate your entity’s trust chain.
Verify keys and signatures Ensure JWT signatures are valid against the keys published by the Trust Anchor and Trust Mark Issuer.
Validate Trust Marks If your entity includes Trust Marks, verify their signatures and claims against the Trust Mark Issuer.
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.
Example entity Configuration: Below is a 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
 Code Block
language
js
{
    "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 metadata configuration
Registering the entity as a Subordinate entity
In the Trust Infrastructure, the entity must be registered as a Subordinate entity under a Superior entity (e.g., a Trust Anchor or an Intermediate entity). This ensures the entity's formal inclusion in the trust hierarchy.
...
  "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 metadata 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:
 Code Block
language
js
{
  "<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
 Code Block
language
js
{
  "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 can then 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.
Inputs to Trust Mark Issuer operator:
id: The identifier for the Trust Mark.
sub: The entity's entity Identifier.
Steps:
Supply the id and sub to the Trust Mark entity.
Retrieve the issued Trust Mark as a signed JWT.
Include in Metadata: Add issued Trust Marks to your entity’s metadata:
Look for the updated trust_marks in the JSON 
 Code Block
language
js
{
  "<entity-entity-identifier>": {
    "entity_types": [
      "federation_entity",
      "openid_credential_entity",
      "oauth_authorization_server"
    ],
    "jwks": 
  }
}
Change <entity-entity-identifier> to the entity_id of the entity
In OIDF the metadata object inside the Entity Configuration is structured by federation entity types, and each corresponds to a role that an entity can play.
The specification defines the following standard metadata types. insert the one that corresponds with the entity:
federation_entity
Mandatory for every participant.
Contains federation-related endpoints such as federation_fetch_endpoint, federation_resolve_endpoint, federation_list_endpoint, and optionally federation_trust_mark_endpoint, etc.
openid_relying_party
Used when the entity is a Relying Party.
Contains metadata (like redirect_uris, application_type, etc.), similar to OIDC Dynamic Client Registration metadata.
openid_provider
Used when the entity is an OpenID Provider.
Contains metadata (like authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, supported algorithms, etc.), aligned with OIDC Discovery.
oauth_authorization_server
Used when the entity acts as a generic OAuth 2.0 Authorization Server.
Contains metadata per RFC 8414 (OAuth 2.0 Authorization Server Metadata).
Open the file in a text editor of your choice
Move the Public Keys into jwks:
Locate the "keys" array in the entity configuration
Move it inside the "jwks" section
The file should look like this:
 Code Block
 {
  "https://entity.example.com": {
    "entity_types": [
      "federation_entity",
      "openid_credential_entity",
      "oauth_authorization_server"
    ],
    "jwks": {
      "keys": [
        {
          "kty": "RSA",
          "use": "sig",
          "kid": "example-kid",
          "n": "example-n-value",
          "e": "AQAB"
        }
      ]
    }
  }
}
Option 2: One-Liner Command (Automated)
For users who prefer a quick and automated approach, use this single command to generate the JSON document:
Replace "https://entity.example.com" with the actual entity entity Identifier.
entity_entity_identifier="https://entity.example.com" && \
jq --arg uri "$entity_entity_identifier" \
  '{($uri): {
    "entity_types": [
      "federation_entity",
      "openid_credential_entity",
      "oauth_authorization_server"
    ],
    "jwks": .
  }}' \
  satosa/public/pid_fed_keys.json \
  > entity_registration.json
Final Step: Send the Document
Once the file entity_registration.json is created using either method, send it to:
support@dc4eu.eu
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:
EHIC Credential:
ID: http://dc4eu.example.com/EHICCredential/se
PDA1 Credential:
ID: http://dc4eu.example.com/PDA1Credential/se
Retrieving Trust Marks
For now, Trust Marks will be supplied when the entity is added to the Trust Infrastructure.
Inputs to Trust Mark entity:
id: The identifier for the Trust Mark (e.g., http://dc4eu.example.com/EHICCredential/se).
sub: The entity's entity Identifier.
Steps:
Supply the id and sub to the Trust Mark entity.
Retrieve the issued Trust Mark as a signed JWT.
Validation:
Use a JWT library to verify the Trust Mark's signature using the Trust Mark entity's public key:
Retrieve public keys from the Trust Mark entity's /.well-known/jwks.json endpoint.
Validate claims such as iss, sub, id, and iat for compliance.
Include in Metadata: Add issued Trust Marks to your entity’s metadata:
config:
  op:
    trust_marks:
  - "eyJhbGciOiJIUzI1NiIsInR..."
  - "eyJhbGciOiJIUzI1NiIsInR..."
Add Trust Marks to the vc_up_and_running entity
To update the trust marks, you need to modify the trust_marks section of the satosa/plugins/oidc_frontend.yaml file. Follow the steps below to replace the existing trust marks with the ones received from the Trust Infrastructure operator.
Locate the trust marks section
In the current configuration, the trust marks are defined under:
config:
  op:
    trust_marks:
      - "eyJhbGciOiJIUzI1NiIsInR..."
      - "eyJhbGciOiJIUzI1NiIsInR..."
Replace these values with the updated trust marks provided by the operator.
Example update
If the operator provided the following new trust marks:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjM2NWQ2MjY3LTI5MzQtNGJhNy05YjEyLWU4ZmFkNTYwj9...
eyJhbGciOiJSUzI1NiIsImtpZCI6IjkwNTFjZTgzLTY1NzEtNDliYi04ODdjLTc3OWQzMDNmJ9...
Then update your configuration as follows:
trust_marks:
  - eyJhbGciOiJSUzI1NiIsImtpZCI6IjM2NWQ2MjY3LTI5MzQtNGJhNy05YjEyLWU4ZmFkNY...
  - eyJhbGciOiJSUzI1NiIsImtpZCI6IjkwNTFjZTgzLTY1NzEtNDliYi04ODdjLTc3OWQyJ9...
Restart the entity to Apply Changes
Once you've updated the configuration file, restart the entity container to apply the changes:
./stop.sh && \
./start.sh
Verify the Changes
After restarting the entity, verify that the new Trust Marks are correctly applied:
curl -k -s https://<entity-host>:8000/.well-known/openid-federation | \
cut -d '.' -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq .
...
response.
Testing Trust Marks
Decode JWT: Use tools like jwt.io to inspect the Trust Mark's claims and ensure all required fields are present.
Verify Signature: Validate the JWT signature against the Trust Mark entity's public key.
Check Expiration: Ensure the exp claim (if present) has not expired.
Validate References: Follow the ref URL (if provided) to confirm compliance with human-readable policy documents.
...
Configure the entity:
Update the entity’s configuration to include authority_hints, trust_marks, and trust_anchors.
Register with the Trust Infrastructure:
Share your entity_registration.json with the Trust Anchor or superior entity for registration.
Validate Configuration:
Test the entity using testing tools or with a other entities sandbox environment.
Monitor the Connection:
Regularly verify the status and ensure Trust Marks are up-to-date.
Testing the Trust Relationships
Validate trust marks
Use tools like jwt.io to decode and verify trust marks using the Trust Anchor's public keys.
Retrieve metadata
Ensure the .well-known/openid-federation endpoint correctly serves the entity’s entity configuration:
curl -X GET https://your-entity.example.com/.well-known/openid-federation
Check authority hints
Verify that authority_hints points to the correct Trust Anchor:
authority_hints:
  - https://openidfed-test-1.sunet.se:7001
Superior

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