openid-federation-services

Sweden Connect

Demo Mode Configuration

The fastest way to understand the configuration model is to read the demo Spring profile, since it exercises every configuration layer at once. For how to start it up and try it out, see Getting Started (Demo Mode); this page instead walks through why it is configured the way it is. It is activated by ./run-demo.sh, which is equivalent to:

mvn -pl oidf-services spring-boot:run -Dspring-boot.run.profiles=demo

This loads oidf-services/src/main/resources/application.yml (the defaults, always active) and layers application-demo.yml on top of it. The relevant part of application-demo.yml looks like this:

credential:
  bundles:
    keystore:
      demo-federation-key-store:
        location: classpath:demo/signkey.p12
        password: changeit
        type: JKS
    jks:
      demo-federation-key:
        store-reference: demo-federation-key-store
        name: "Demo Federation Key"
        key:
          alias: 1
          key-password: changeit

federation:
  keys:
    kid-algorithm: serial
    mapping:
      federation:
        - "demo-federation-key"
      hosted:
        - "demo-hosted-key"
  service:
    storage: memory
  routing:
    enabled: true
    mode: IGNORING
  resolver:
    client:
      name: demo-resolver-client
  registry:
    integration:
      enabled: false
  local-registry:
    trust-anchors: "classpath:demo/trust-anchors.json"
    resolvers: "classpath:demo/resolvers.json"
    entities: "classpath:demo/entities.json"

Read top to bottom, this configures:

  1. credential.bundles — two keystores (demo-federation-key-store, demo-hosted-key-store) loaded from PKCS#12 files on the classpath, each exposing one signing key (demo-federation-key, demo-hosted-key). This block is not an openid-federation property — it is provided by the credentials-support library that Spring Boot auto-configures. credential.bundles.keystore.<name> describes where a keystore lives (location, password, type — a standard java.security.KeyStore type such as PKCS12 or JKS), and credential.bundles.jks.<name> describes which key inside that keystore to use (store-reference points back at the keystore, key.alias + key.key-password select the entry, and name is a human-readable label used in logs/JWK metadata).
  2. federation.keys.mapping — takes the credential bundle names (demo-federation-key, demo-hosted-key) and assigns them a usage: keys listed under federation sign federation-protocol artifacts (entity statements, subordinate statements, trust marks), keys listed under hosted sign an entity’s own hosted metadata. This is what makes federation:demo-federation-key and hosted:demo-hosted-key valid key references in the JSON files below (see Reference Configuration).
  3. federation.service.storage: memory — state (cached entity statements, resolve trees, etc.) is kept in-process instead of Redis. Fine for a demo/single-node setup, not for a clustered deployment (see 2.2 Federation Service).
  4. federation.routing.* — since demo mode hosts five entities (/ta, /im, /op, /rp, /resolver) behind one Spring Boot application on one port, internal routing must be enabled so each request is dispatched to the right virtual entity based on its path (see Routing for how this dispatch works). mode: IGNORING is used because the demo only ever runs on localhost — it does not need to validate the Host header the way a multi-domain deployment would with STRICT.
  5. federation.local-registry.* — instead of a live registry (federation.registry.integration), the demo loads its entities, trust anchor hierarchy and resolver straight from three JSON files on the classpath. This is the same local-registry format a standalone (non-managed) production deployment would use, just pointed at classpath: instead of file:.
  6. federation.resolver.client.name — names the outbound HTTP client the service’s Resolver module uses when it needs to fetch entity/subordinate statements over the network (see 2.6 Resolver HTTP Client). It is required configuration even in the demo, although the demo’s single resolver only ever resolves entities that are already present in its own local registry, so this client is never actually dispatched against a remote host.

The three demo JSON files

These files are the actual federation data: who the entities are, how they are keyed, how they relate to each other, and how the resolver is configured. All three live under oidf-services/src/main/resources/demo/ and are wired in via federation.local-registry.entities, federation.local-registry.trust-anchors and federation.local-registry.resolvers respectively.

entities.json — the entities themselves

One entry per entity hosted by this service instance. This is where an entity’s own metadata is declared.

{
  "entity-identifier": "http://localhost:8080/op",
  "virtual-entity-id": "http://localhost:8080/op",
  "jwks": "hosted:demo-hosted-key",
  "authority-hints": ["http://localhost:8080/im"],
  "metadata": {
    "federation_entity": {
      "organization_name": "Demo OpenID Provider"
    },
    "openid_provider": {
      "issuer": "http://localhost:8080/op"
    }
  }
}

trust-anchors.json — the trust hierarchy

One entry per trust anchor or intermediate, listing its immediate subordinates. This is what the /subordinate_listing and /fetch endpoints serve, and it is where policy and constraints are attached.

{
  "entity-identifier": "http://localhost:8080/im",
  "subordinates": [
    {
      "entity-identifier": "http://localhost:8080/op",
      "entity-types": ["federation_entity", "openid_provider"],
      "jwks": "hosted:demo-hosted-key",
      "policy": {
        "id": "MyMetadataProfile",
        "policy": {
          "oauth_client": {
            "organization_identifier": {
              "value": "urn:glue:iso6523:0007:2021006552"
            },
            "organization_name": {
              "value": "Myndigheten för OIDF"
            }
          }
        }
      }
    },
    {
      "entity-identifier": "http://localhost:8080/rp",
      "entity-types": ["openid_relying_party"],
      "jwks": "hosted:demo-hosted-key"
    }
  ]
}

This says: the Intermediate (/im) is itself a subordinate of the Trust Anchor (/ta, see the first entry in the file) and has two subordinates of its own, /op and /rp. The /op subordinate statement additionally carries a metadata_policy that the Resolver applies when resolving /op’s effective metadata — see Policy below.

A subordinate entry supports:

Property Description Type
entity-identifier Entity ID of the subordinate String
entity-types Required. The Entity Type Identifiers of the subordinate, used by the entity_type filter of /subordinate_listing List<String>
is-intermediate true if the subordinate is an Intermediate Entity, used by the intermediate filter of /subordinate_listing. Requires federation_entity in entity-types Boolean
virtual-entity-id Overrides the entity ID used inside the statement, if different String
jwks Key(s) the subordinate signs its own entity configuration with Object/reference
metadata Metadata asserted directly in the subordinate statement’s metadata claim Object
policy Metadata policy applied to this subordinate’s metadata on resolve Object/reference
constraints Trust chain constraints enforced below this subordinate Object
crit Critical claims the subordinate statement must assert support for List<String>
metadata-policy-crit Critical policy operators used in policy, see Section 6.1.3 of the specification List<String>
ec-location Where this subordinate’s Entity Configuration is found, issued as ec_location. See ec-location values String

Policy

policy.policy is issued as the metadata_policy claim of the Subordinate Statement, and follows Section 6.1.2 of OpenID Federation 1.0: a map of entity-type -> claim-name -> { operator: value }. The standard operators are:

Operator Effect
value Force the claim to exactly this value, null removes the claim
add Add value(s) to a list-valued claim
default Value to use if the claim is not already present
essential true/false — whether the claim must be present after merging
one_of The claim’s value must be one of the listed values
subset_of Reduce the claim’s (list) value to the values that are listed
superset_of The claim’s (list) value must be a superset of the listed values

In the example above, the policy forces /op’s oauth_client.organization_identifier and oauth_client.organization_name metadata to fixed values regardless of what /op itself publishes — typical for a Trust Anchor/Intermediate that wants to assert authoritative organization identity on behalf of a subordinate. policy.id is a free-text label for the policy (useful for logging/debugging); policy.policy is the object that is actually evaluated.

Like jwks, policy can be given as a reference (e.g. policy: file:/path/to/policy.json) instead of inlined, which is convenient for sharing one policy across several subordinates.

Constraints

constraints follows §4.1.4 of OpenID Federation 1.0 and limits what is trusted below this subordinate in the chain:

"constraints": {
  "max-path-length": 1,
  "allowed-entity-types": ["openid_provider", "openid_relying_party"],
  "naming": {
    "permitted": [".example.com"],
    "excluded": ["blocked.example.com"]
  }
}
Property Description Type
max-path-length Maximum number of intermediates allowed below this entity Long
allowed-entity-types Entity types (openid_provider, openid_relying_party, …) permitted below List<String>
naming.permitted Hosts (host.example.com) or domains (.example.com) subordinate identifiers must be under List<String>
naming.excluded Hosts or domains subordinate identifiers must not be under, takes precedence over permitted List<String>

Naming constraints use the domain name syntax of RFC 5280 and apply to the host part of the entity identifier. .example.com matches any host below example.com but not example.com itself, while host.example.com matches that host only.

Entity types not listed in allowed-entity-types are removed from the metadata of entities below this subordinate when a trust chain is resolved. federation_entity is always kept, and an empty list allows only federation_entity.

The demo does not set any constraints, so any entity type and any nesting depth is allowed under /im.

resolvers.json — the resolver

{
  "entity-identifier": "http://localhost:8080/resolver",
  "trust-anchor": "http://localhost:8080/ta",
  "trusted-keys": "federation:demo-federation-key",
  "resolve-response-duration": "PT1H"
}

Each entry configures one Resolver entity: which Trust Anchor it resolves chains under (trust-anchor), which key(s) it trusts to validate fetched statements with (trusted-keys, a key reference), and how long a /resolve response’s exp claim should be set to relative to now (resolve-response-duration, an ISO-8601 duration such as PT1H, default 7 days). A resolver entry’s own entity-identifier must also exist in entities.json, since that is where its own signing key and published metadata (federation_resolve_endpoint, etc.) come from.

Running against production data instead of the demo files

The only thing that changes for a non-demo deployment using the same standalone/local-registry mode is where these three JSON files come from and what they contain — swap classpath: for file: (or mount them and point at an absolute path), and enable TLS/Redis/tracing as appropriate. If instead you want configuration to be centrally managed and hot-reloadable without restarts, use managed mode (federation.registry.integration.enabled: true) against the OpenID Federation Registry instead of federation.local-registry.*. See Service Configuration for the full property reference used by both modes.