OpenID Connect Federation 1.0 client registration endpoint

1. Explicit registration for federation clients

Client applications must be registered with the Connect2id server before they can login end-users with OpenID Connect or receive OAuth 2.0 access tokens. This also applies to clients which are entities in a OpenID Connect federation.

Each entity in a federation, whether OpenID relying party or provider, is capable of publishing a signed statement (JWT) with metadata about itself. Those entities which are OpenID relying parties include the required client metadata, such as redirection URI, in their statement.

The registration in a federation can happen in two ways:

  • explicit -- The OpenID relying party submits its signed entity statement containing metadata to this endpoint.

  • automatic -- The OpenID relying party simply proceeds to the authorisation endpoint or to the PAR endpoint, authenticating with a private key. The OpenID provider downloads the RP's signed entity statement with the client metadata from a well-known URL.

For details check out the OpenID Connect Federation 1.0 specification.

2. The federation client registration endpoint URL

It can be found out from the federation_registration_endpoint advertised in the Connect2id server metadata and has this form:


3. Web API overview

Representations Errors

4. Resources

4.1 /federation/clients

4.1.1 POST

Registers a new federated OAuth 2.0 / OpenID Connect client.

Header parameters:

  • Content-Type Must be set to application/jose.




Example client registration request:

POST /federation/clients HTTP/1.1
Content-Type: application/jose;charset=UTF-8


Example client registration response detailing the provisioned identifier, secret, registration access token and metadata:

HTTP/1.1 200 OK
Content-Type: application/jose;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache


5. Representations

5.1 OpenID relying party entity statement

Self-signed JWT containing the federation entity statement claims for an OpenID relying party.

Required JWT header parameters:

  • alg {string} The JSON Web Signature (JWS) algorithm, supported algorithms: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384ES512.

Required JWT claims:

  • iss {string} The entity identifier (URL) of the OpenID relying party, e.g.

  • sub {string} Set to the iss value.

  • iat {number} The statement issue time, as number of seconds since the Unix epoch.

  • exp {number} The statement expiration time, as number of seconds since the Unix epoch.

  • jwks {object} The public signing keys of the federation entity, in JSON Web Key (JWK) set format.

  • authority_hints {string array} One or more entity identifiers of federation authorities (intermediates or trust anchors).

  • metadata {object} Metadata for the federation entity:

    • openid_relying_party {object} The OpenID relying party metadata. Must contain the minimum required parameters (redirect_uris and potentially others, depending on the desired client authentication type) for a client registration.

      For a successful registration those parameters must observe the published OpenID provider metadata in the Connect2id server's own entity statement, such as the supported grant types (grant_types_supported) and token endpoint authentication methods (token_endpoint_auth_methods_supported).

Example entity statement claims from an OpenID relying party:

  "iss"             : "",
  "sub"             : "",
  "iat"             : 1594030600,
  "exp"             : 1594635400,
  "jwks"            : { "keys" : [ {
                            "kty" : "RSA",
                            "alg" : "RS256",
                            "use" : "sig",
                            "kid" : "exR5",
                            "e"   : "AQAB",
                            "n"   : "l9TeUfN0jztln5hVq6Z3vwS47MCyonpO-kJSVMqccKgoUkxLzo_IH1ekKf-3X1Tu4KrKoDn7Nk6Wrusw9gOI9JCszV8rCE1_SCYnKI4mCwI9RXhCgXC0NkvXg-1ySHn9PjNEurGsgpIFqA2u-66KItFP_BLsUKGDfC1w73EymUJ6ZHGc1FnAXCusWgLARceOep4oAO8q3_oFNW4A__1IphYnJ6zdqYwBHK6PWf210SKP8LAJ0tlq7RTZyiB0DG9ina95UHNFIoJnc_g-AOCa1-ShDcUNpWtpL1j3vZnAHyG3pB_9xi4Ngo2-vlZQXnalZmDbk1Cog4N3hI-3DXTTMw" } ] },
  "authority_hints" : [ "" ],
  "metadata"        : {
      "openid_relying_party"  : {
          "redirect_uris" : [ "" ],
          "client_name"   : "My Example Client",
          "logo_uri"      : ""

5.2 Registration statement

Self-signed JWT containing the claims for a successful client registration.

JWT header parameters:

  • alg {string} The JSON Web Signature (JWS) algorithm, set to RS256.
  • kid {string} The identifier of the signing key from the JWK set in the jwks claim of the OpenID provider entity statement.

JWT claims:

  • iss {string} The configured issuer URL (server identifier) e.g.

  • sub {string} Set to the entity identifier of the registered OpenID relying party.

  • aud {string} Set to the entity identifier of the registered OpenID relying party.

  • iat {number} The statement issue time, as number of seconds since the Unix epoch.

  • exp {number} The registration expiration time, as number of seconds since the Unix epoch.

  • authority_hints {string array} Contains a single successfully validated federation authority (intermediate or trust anchor) from the submitted entity statement which is also recognised by the Connect2id server.

  • metadata_policy {object} Metadata policy.

    • openid_relying_party {object} The policy operations to apply to the OpenID relying party metadata in the submitted entity statement and thus create the final client registration JSON object.

Example registration statement claims:

  "iss"             : "",
  "sub"             : "",
  "aud"             : "",
  "iat"             : 1594365784,
  "exp"             : 1594365843,
  "authority_hints" : [ ""],
  "metadata_policy" : {
      "openid_relying_party" : {
          "client_id"                    : { "value" : "123" },
          "client_id_issued_at"          : { "value" : 1594365783 },
          "client_secret"                : { "value" : "63kqtDL0KxOM_VInDkvWjWVvt7JSkVHLwQAYO0uceWo" },
          "client_secret_expires_at"     : { "value" : 0 },
          "grant_types"                  : { "value" : [ "authorization_code" ] },
          "response_types"               : { "value" : [ "code" ] },
          "token_endpoint_auth_method"   : { "value" : "client_secret_basic" },
          "id_token_signed_response_alg" : { "value" : "RS256" },

6. Errors

400 Bad Request

Invalid or malformed request.


HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

  "error"             : "federation_not_enabled",
  "error_description" : "OpenID Connect Federation 1.0 not enabled"

401 Unauthorized

The request was denied due to an invalid entity statement signature or failed trust chain resolution.


HTTP/1.1 401 Unauthorized;charset=UTF-8
Content-Type: application/json

  "error"             : "unauthorized_client",
  "error_description" : "Trust chain resolution failed"

404 Not Found

The requested resource doesn't exist.


HTTP/1.1 404 Not Found

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.


HTTP/1.1 500 Internal Server Error