OpenID Federation RP

Use this guide when Access is the OIDC Relying Party (RP) and the external OpenID Provider (OP) belongs to an OpenID Federation. Federation adds signed entity metadata, trust resolution and client-registration choices around the existing OIDC authorization code flow.

Note

Ordinary OIDC remains a separate, supported mode. Keep provider_discovery_mode: openid_connect and use discovery_metadata_url when federation trust is not required. See OIDC Relying Party.

Note

This page describes direct Access JSON configuration. For the guided UI workflow, see Set up a federated RP in Management Center.

How the components fit together

Two Access resources participate in the federated RP role:

• OIDCRP owns the login flow, redirect URI, scopes, protocol keys and the selected OP.
• OIDCFederationEntityModule owns the public federation entity ID, Entity Configuration endpoint, federation signing keys, trust anchor, resolver policy and explicit-registration storage.

The RP links to the federation entity through the public entity_id. The federation entity links back to the RP by the authenticator's Access resource ID. They are deliberately different identifiers.

OIDCFederationEntityModule
  |-- publishes <entity_id>/.well-known/openid-federation
  |-- resolves and verifies the selected OP
  |-- supplies effective federation policy
  `-- obtains RP metadata from the linked OIDCRP

OIDCRP
  |-- starts and completes the authorization code flow
  |-- owns redirect URI, scopes and RP protocol keys
  `-- requests verified OP metadata from the federation entity

The federation entity must be available before authentication starts. At Access startup it obtains the RP metadata exposed by the initialized authenticator and only then starts its public endpoint. A missing or invalid link prevents incomplete RP metadata from being published.

Prerequisites

Before configuring the resources, prepare:

• an external HTTPS entity_id for Access
• a public route to <entity_id>/.well-known/openid-federation
• a TLS server certificate trusted by the federation's participants
• a federation signing key and certificate in an Access-compatible keystore
• a pinned Trust Anchor entity ID and public JWKS
• the Trust Anchor fetch or resolve endpoint required by the selected resolver strategy
• the entity ID of the OP
• an existing named HttpClient destination for outbound federation and OIDC calls
• an existing named HTTP listener for the public Entity Configuration endpoint
• a separate RP protocol signing key when private_key_jwt or automatic registration is used
• a separate RP encryption key when encrypted ID tokens or UserInfo responses are required

Federation signing keys, OIDC protocol keys, response-decryption keys, explicit-registration storage keys and the TLS server key are separate key roles. Do not reuse one private key for all roles.

Configure a federated RP

Choose provider discovery mode

Set provider_discovery_mode to openid_federation. Configure federation_entity_id with Access's public federation entity ID and federation_op_entity_id with the OP's public entity ID.

Do not configure trust inside the authenticator. federation_trust_anchor is rejected; trust belongs to the linked federation entity.

Choose client registration

Set federation_client_registration_type explicitly:

• pre_registered uses a client that the OP already knows.
• automatic uses the RP entity ID as client_id and sends a signed Request Object.
• explicit asks the OP's federation registration endpoint for assigned credentials and stores the verified response.

See Client registration modes and Explicit registration and clustering.

Configure the OIDC RP authenticator

The following example uses automatic registration and private_key_jwt:

{
  "id": "external-federated-oidc",
  "type": "OIDCRP",
  "config": {
    "base_path": "/login/authn",
    "provider_discovery_mode": "openid_federation",
    "federation_entity_id": "https://access.example/rp",
    "federation_op_entity_id": "https://op.federation.example",
    "federation_client_registration_type": "automatic",
    "internal_http_destination": "oidcrp_httpclient",
    "redirect_uri": "https://access.example/login/authn/external-federated-oidc",
    "scope": "openid profile",
    "response_type": "code",
    "token_endpoint_auth_method": "private_key_jwt",
    "private_key_jwt": {
      "sign_ref": [
        {
          "keystore": {
            "type": "PKCS12",
            "path": "${system.customer_home}/resources/oidcf/rp-protocol-signing.p12",
            "password": "${secrets.oidcf_rp_keystore_password}",
            "key_password": "${secrets.oidcf_rp_key_password}",
            "alias": "rp-protocol-signing"
          }
        }
      ]
    },
    "rp_metadata": {
      "client_name": "Example service",
      "contacts": ["[email protected]"],
      "client_uri": "https://service.example",
      "logo_uri": "https://service.example/logo.png"
    }
  }
}

With automatic registration, omit client_id or set it to exactly the same value as federation_entity_id.

If the login requires a specific authentication level, set acr_values to the accepted space-separated ACR values and acr_requirement to required in this RP's config. Access then requests acr as an essential ID token claim in the signed Request Object and rejects a missing or unaccepted value in the signed ID token. Without acr_requirement, the default is preferred: Access requests the values but does not enforce the returned acr. See Require a returned ACR for configuration and signature requirements.

Configure the federation entity

Link oidc_rp_authenticator to the Access resource ID from the previous step. The example uses local chain building:

{
  "name": "OIDCFederationEntityModule",
  "enabled": true,
  "config": {
    "entity_id": "https://access.example/rp",
    "http_listener": "default",
    "http_context": "/",
    "internal_http_destination": "oidcrp_httpclient",
    "sign_ref": [
      {
        "keystore": {
          "type": "PKCS12",
          "path": "${system.customer_home}/resources/oidcf/federation-signing.p12",
          "password": "${secrets.oidcf_federation_keystore_password}",
          "key_password": "${secrets.oidcf_federation_key_password}",
          "alias": "federation-signing"
        }
      }
    ],
    "entity_statement_ttl_seconds": 3600,
    "resolver_strategy": "federation_chain",
    "authority_hints": ["https://registration.example"],
    "trust_anchor": {
      "entity_id": "https://trust-anchor.example",
      "jwks": {
        "keys": [
          {
            "kty": "RSA",
            "kid": "trust-anchor-key",
            "use": "sig",
            "n": "<base64url modulus>",
            "e": "AQAB"
          }
        ]
      },
      "federation_fetch_endpoint": "https://trust-anchor.example/fetch"
    },
    "oidc_rp_authenticator": "external-federated-oidc",
    "rp_metadata_profile": "generic"
  }
}

The examples use the secrets property-expansion scope. Enable and configure secrets management before starting Access so that every ${secrets.*} placeholder can be resolved. Do not commit clear-text credentials to config.json.

Publish and verify the Entity Configuration

Expose the listener route at exactly:

https://access.example/rp/.well-known/openid-federation

Verify that it returns HTTP 200 with media type application/entity-statement+jwt. Decode the JWT for inspection and check that iss and sub equal the configured entity_id, but verify the signature before trusting its contents.

The external path is derived from the path component of entity_id. Reverse proxies must preserve that route. The endpoint is available after Access has initialized both the linked RP and the federation entity.

Test trust resolution before user traffic

Confirm that Access can reach the configured federation fetch or resolve endpoints through internal_http_destination, that the pinned Trust Anchor key validates the response, and that the resolved openid_provider metadata has the expected issuer and authorization, token and JWKS endpoints.

Then run an authorization code flow and check both the federation status and the Access logs. Federation failures do not fall back to ordinary OIDC discovery.

Client registration modes

Pre-registered

Use pre_registered when the OP has already assigned the client. Configure client_id, redirect_uri and a token endpoint authentication method usable with the OP. Secret-based methods also require client_secret; private_key_jwt requires private_key_jwt signing keys. The existing auto behavior remains available for compatible pre-registered clients.

The OP metadata is still obtained and trusted through federation. Only client registration is pre-arranged.

Automatic

Use automatic when the federation permits the RP entity ID to act as the client ID. Access requires private_key_jwt, publishes the RP public key and sends a short-lived RS256 Request Object. The resolved OP must advertise automatic registration, Request Objects by value, RS256 Request Object signing and private_key_jwt.

Explicit

Use explicit when the OP advertises a federation_registration_endpoint and assigns credentials. Access signs the registration request, verifies the response with OP federation keys bound to the resolved trust chain, and renews the registration before its effective expiry.

Explicit registration requires a persistent store. Use Explicit registration and clustering to choose the correct backend.

Resolver strategies

resolver_strategy is mandatory and never falls back to another strategy:

• direct accepts only a direct Trust Anchor-to-OP relationship and requires trust_anchor.federation_fetch_endpoint.
• federation_chain builds and verifies a chain through authority_hints and requires trust_anchor.federation_fetch_endpoint.
• federation_resolver calls the Trust Anchor's resolver and requires trust_anchor.federation_resolve_endpoint. Access can also verify configured required trust marks with this strategy.

Use the topology defined by the federation operator. Do not select direct merely to bypass a failed chain or resolver call.

Sweden Connect sandbox

Follow Test a federated RP in Sweden Connect Sandbox for the current operator endpoints, Management Center fields, RP metadata and onboarding sequence. The sandbox Trust Anchor key is intentionally not copied into this manual configuration guide; pin the current public federation key using Sweden Connect's official federation settings and the operator's onboarding information.

For direct JSON configuration, use resolver_strategy: federation_resolver, the sandbox RP Registration Intermediate in authority_hints, and rp_metadata_profile: sweden_connect. Supply the Trust Anchor's Entity ID, public JWKS and Resolve Endpoint from the current sandbox settings. The OP Entity ID and automatic registration choice belong to the linked OIDCRP, not to the Federation Entity.

Response encryption

Access can require encrypted ID tokens, UserInfo responses or both. Configure each alg and enc as a complete pair and provide at least one encryption_ref keystore. Supported key-management algorithms are RSA-OAEP and RSA-OAEP-256; supported content-encryption algorithms are A128GCM, A192GCM and A256GCM.

When encryption is configured, an unencrypted response is rejected. An encrypted ID token must contain a signed ID token. A profile that requires signed UserInfo accepts only a signed and then encrypted nested JWT.

See Configuration reference for the exact fields and Explicit registration and clustering for persistent client-registration storage.

In this section

• Configuration reference
• Explicit registration and clustering