Skip to content

configuration.md

Latest commit

 

History

History
291 lines (229 loc) · 21.5 KB

configuration.md

File metadata and controls

291 lines (229 loc) · 21.5 KB
Raw

Logo

Application Configuration

This document describes the configuration settings available for the OpenID Federation Entity Registry Service.

Table of Contents

Server Configuration

Setting Example Value Description
server.port 8010 Port the server will run on.
server.compression.enabled true Enables response compression for the server. Recommended.
management.endpoints.web.exposure.include * Configures the exposure of all management endpoints.

Spring Application Configuration

Setting Example Value Description
spring.application.name EntityRegistryService The name of the Spring application.
spring.threads.virtual.enabled true Enables virtual thread support.

Database Configuration

Spring DataSource

Setting Example Value Description
spring.datasource.url jdbc:mariadb://db:3306/testdb URL of the database connection.
spring.datasource.username test Username for the database.
spring.datasource.password test Password for the database.

Spring Flyway

Setting Example Value Description
spring.flyway.enabled true Enables Flyway database migration.

Spring JPA

Setting Example Value Description
spring.jpa.database-platform org.hibernate.dialect.MariaDBDialect Specifies the JPA database platform (MariaDB dialect).
spring.jpa.hibernate.ddl-auto none Configures Hibernate's schema generation strategy. None is recommended since Flyway handles database migrations.
spring.jpa.show-sql true Enables logging of SQL queries executed by JPA.
spring.jpa.properties.hibernate.format_sql true Formats the logged SQL queries.

Security Configuration

Setting Example Value Description
spring.security.oauth2.resourceserver.jwt.public-key-location classpath:my-key.pub Location of the public key for the JWT resource server.

Logging Configuration

Setting Example Value Description
logging.level.se.swedenconnect.oidf debug Sets the logging level for the se.swedenconnect.oidf package.

Observability

Setting Example Value Description
management.server.port 8081 Port for the management/actuator endpoints (separate from the main server port).
management.metrics.tags.application_name oidf-registry Tag added to all metrics for filtering by application name.
management.metrics.tags.application_version 1.0.0 Tag added to all metrics for filtering by application version.
management.prometheus.metrics.export.enabled true Enables Prometheus metrics export.
management.tracing.sampling.probability 1.0 Fraction of requests to sample for distributed tracing. 1.0 = 100 %.
management.opentelemetry.tracing.export.otlp.endpoint http://localhost:4318/v1/traces OTLP endpoint for exporting traces. Can also be set via OTEL_EXPORTER_OTLP_ENDPOINT env var.
management.endpoints.web.exposure.include * Controls which actuator endpoints are exposed over HTTP.

API Documentation (SpringDoc)

Setting Example Value Description
springdoc.api-docs.path /v3/api-docs Path where the OpenAPI JSON descriptor is served.
springdoc.api-docs.enabled true Enables or disables the OpenAPI descriptor endpoint.
springdoc.swagger-ui.path /swagger-ui.html Path where the Swagger UI is served.
springdoc.swagger-ui.enabled true Enables or disables the Swagger UI.
springdoc.swagger-ui.operationsSorter method Sort order for operations in the UI (method or alpha).
springdoc.swagger-ui.tagsSorter alpha Sort order for tags in the UI.
springdoc.swagger-ui.tryItOutEnabled true Enables the "Try it out" button in Swagger UI by default.
springdoc.swagger-ui.filter true Enables the filter/search box in Swagger UI.
springdoc.swagger-ui.persistAuthorization true Persists authorization tokens across page reloads in Swagger UI.

Credential Bundles

Setting Example Value Description
credential.bundles.keystore.signkey.location file:config/local/rsa1.jks Path to the keystore for the signing key.
credential.bundles.keystore.signkey.password Test1234 Password for the signing key keystore.
credential.bundles.keystore.signkey.type JKS Specifies the type of the keystore (JKS).
credential.bundles.jks.federationapi.store-reference signkey References the signing key keystore for the Federation API.
credential.bundles.jks.federationapi.name FederationAPI-JWKSignkey Name of the Federation API signing key.
credential.bundles.jks.federationapi.key.alias rsa1 Alias of the key used for signing in the Federation API keystore.
credential.bundles.jks.federationapi.key.key-password Test1234 Password for the signing key in the Federation API keystore.

Audit Logging

Setting Example Value Description
audit-logging.loglevel INFO (default) Configures the log level for audit logging. Supported values are INFO, DEBUG, TRACE, or NONE. If no value is set, it defaults to INFO.

OpenID Federation Registry Settings

Federation Service API

Setting Example Value Description
openid.federation.registry.federation_service_api.issuer http://oidf-registry.swedenconnect.se Issuer URI set on JWT from Federation Service API.
openid.federation.registry.federation_service_api.sign-key-alias federationapi Key alias used for signing operations in the Federation Service API.
openid.federation.registry.federation_service_api.kid-algorithm serial Kid algorithm used when generating kid in response in federationapi, can be set to: serial
openid.federation.registry.federation_service_api.token-expiry-duration PT1H Token ExpiryDuration for all tokens delivered from federation endpoint.
openid.federation.registry.federation_service_api.notification-active false Flag indicating whether notifications are enabled.
openid.federation.registry.federation_service_api.notification-trust-key-alias trustKey Alias to spring trust-bundle for outgoing notification requests.
openid.federation.registry.federation_service_api.notifications[0].endpoint https://example.com/notify The URI of the notification endpoint.
openid.federation.registry.federation_service_api.notifications[0].instance_id UUID The unique identifier for the instance sending notifications.

Federation Instances

Each entry in openid.federation.registry.instances represents one federation instance managed by this registry. An instance maps a set of organisations to a specific federation endpoint.

Instance properties

Setting Required Example Value Description
openid.federation.registry.instances[i].instance_id Yes 123e4567-e89b-12d3-a456-426614174000 UUID that uniquely identifies this instance. Must match the instance record in the database.
openid.federation.registry.instances[i].name Yes Swedenconnect Human-readable name for the instance. Also identifies the tenant (see Federation Instances); must be unique across instances.
openid.federation.registry.instances[i].base_url Yes https://registry.swedenconnect.se/oidf Base URL for this instance. Used to compute the entityPrefix for every organisation assigned to it: base_url/orgNumber.
openid.federation.registry.instances[i].org_base_url_overrides No See example below Optional per-organisation override of base_url. When set for an org, its entityPrefix is computed as override/orgNumber instead of base_url/orgNumber.
openid.federation.registry.instances[i].function_group Yes swedenconnect The single function group that administrates this tenant. Must be unique across instances; organisations are routed to the instance whose function_group matches.
openid.federation.registry.instances[i].oidf_service_api_validation_key No See below Public key used to verify signed JWT responses from the oidf-service node attached to this instance. See OIDF Service API Validation Key.

An organisation number is no longer required to be globally unique — the same org_number may be registered on more than one instance; it is only required to be unique per instance.

Entity prefix computation

The entityPrefix for an organisation is resolved at request time — it is not stored in the token:

  1. The matching instance is found by matching function_group against the tenant's function group.
  2. If the organisation number exists in org_base_url_overrides, the override URL is used as the base.
  3. Otherwise base_url is used.
  4. The final value is <base>/orgNumber, e.g. https://registry.swedenconnect.se/oidf/5590026042.

Per-organisation URL override

openid:
  federation:
    registry:
      instances:
        - instance_id: "123e4567-e89b-12d3-a456-426614174000"
          name: "Swedenconnect"
          base_url: "https://registry.swedenconnect.se/oidf"
          function_group: "swedenconnect"
          org_base_url_overrides:
            "5590026042": "https://dev.swedenconnect.se/oidf-test"

In this example all organisations use https://registry.swedenconnect.se/oidf/{orgNumber} except 5590026042, which resolves to https://dev.swedenconnect.se/oidf-test/5590026042.

OIDF Service API Validation Key

Each instance can optionally declare a public key that is used to verify signed JWT responses from the oidf-service node attached to that instance. The key is a single KeyEntry object — not a list. Exactly one of base64_encoded_public_jwk or certificate must be provided.

Sub-property Required Description
openid.federation.registry.instances[i].oidf_service_api_validation_key.name Yes Logical name for the key entry (used in logs and error messages).
openid.federation.registry.instances[i].oidf_service_api_validation_key.base64_encoded_public_jwk One of the two Public JWK encoded as a Base64 string (the full JWK JSON, Base64-encoded).
openid.federation.registry.instances[i].oidf_service_api_validation_key.certificate One of the two PEM-encoded X.509 certificate whose public key is used for verification.

Note: If neither or both of base64_encoded_public_jwk and certificate are set the application will fail to start with a validation error.

Example using a Base64-encoded JWK:

openid:
  federation:
    registry:
      instances:
        - instance_id: "123e4567-e89b-12d3-a456-426614174000"
          name: "Swedenconnect"
          base_url: "https://registry.swedenconnect.se/oidf"
          function_group: "swedenconnect"
          oidf_service_api_validation_key:
            name: OidfService
            base64_encoded_public_jwk: "<Base64-encoded JWK JSON>"

Example using a PEM certificate:

openid:
  federation:
    registry:
      instances:
        - instance_id: "123e4567-e89b-12d3-a456-426614174000"
          name: "Swedenconnect"
          base_url: "https://registry.swedenconnect.se/oidf"
          function_group: "swedenconnect"
          oidf_service_api_validation_key:
            name: OidfService
            certificate: |
              -----BEGIN CERTIFICATE-----
              MIIBxT...
              -----END CERTIFICATE-----

To generate the Base64-encoded JWK value, export the public JWK from your oidf-service node and encode it:

# Encode an existing JWK JSON file
base64 -w 0 my-public-key.json

Full example

openid:
  federation:
    registry:
      instances:
        - instance_id: "123e4567-e89b-12d3-a456-426614174000"
          name: "Swedenconnect"
          base_url: "https://registry.swedenconnect.se/oidf"
          function_group: "swedenconnect"

        - instance_id: "223e4567-e89b-12d3-a456-426614174001"
          name: "ENA"
          base_url: "https://registry.ena.se/oidf"
          function_group: "ena"

Entity Configuration Loader

Controls how the registry fetches and validates entity configurations from external entities during registration flows. All settings are optional; the loader is disabled by default.

Setting Required Default Description
openid.federation.registry.entity-configuration-loader.enabled No false Enables loading entity configuration (and JWKS) from an entity's self-signed entity statement during registration.
openid.federation.registry.entity-configuration-loader.trust-bundle-alias No — Alias of the Spring credential bundle used to trust HTTPS connections when fetching remote entity configurations.
openid.federation.registry.entity-configuration-loader.enable-local-ip-address-ranges No false When true, the loader may resolve entity IDs that map to private/local IP ranges. Security risk — enables SSRF to internal hosts.
openid.federation.registry.entity-configuration-loader.disable-system-properties No false When true, JVM system properties (e.g. proxy settings) are ignored when building the outgoing HTTP client.
openid.federation.registry.entity-configuration-loader.block-hostname No — List of regular expressions. Any entity ID whose host matches one of these patterns is rejected before the outgoing request is made.

Example

openid:
  federation:
    registry:
      entity_configuration_loader:
        enabled: true
        trust-bundle-alias: "myTrustBundle"
        enable-local-ip-address-ranges: false
        block-hostname:
          - ".*\\.internal\\.example\\.com"
          - "localhost"

Copyright © 2026, Sweden Connect. Licensed under version 2.0 of the Apache License.