# OpenID Federation RP Documentation owner: product `access`; documentation version: `next`. Source: `content/products/access/next/authenticators/protocol-managers/oidc/openid-federation-rp.md` at commit `eaf7a020437971baeee95e87eaf963636040ac71`. 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](/products/access/next/authenticators/protocol-managers/oidc/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](/products/access/next/authenticators/protocol-managers/oidc/openid-federation-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. ```text OIDCFederationEntityModule |-- publishes /.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 `/.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](#client-registration-modes) and [Explicit registration and clustering](/products/access/next/authenticators/protocol-managers/oidc/openid-federation-explicit-registration/). ## Configure the OIDC RP authenticator The following example uses automatic registration and `private_key_jwt`: ```json { "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": ["operations@example.com"], "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](/products/access/next/authenticators/protocol-managers/oidc/oidc-relying-party/#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: ```json { "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": "", "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](/products/access/next/configuration-reference/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: ```text 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](/products/access/next/authenticators/protocol-managers/oidc/openid-federation-explicit-registration/) 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](/products/access/next/authenticators/protocol-managers/oidc/openid-federation-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](https://docs.swedenconnect.se/federation/oidf-structure.html) 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](/products/access/next/authenticators/protocol-managers/oidc/openid-federation-configuration/) for the exact fields and [Explicit registration and clustering](/products/access/next/authenticators/protocol-managers/oidc/openid-federation-explicit-registration/) for persistent client-registration storage.