Skip to content
Connect2id

Federation client registration

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 tokens. This general rule also applies to clients that are entities in a OpenID Connect Federation 1.0.

Every compliant entity in a federation is expected to have a signed entity configuration (JWT) containing its authority reference and public keys for the trust establishment as well as metadata specific to its entity type, which for an OpenID relying party would be a redirection URI and preferred ID token algorithm.

The registration in a federation can happen in two ways:

  • Explicit – The OpenID relying party submits its signed entity configuration to this endpoint.

  • Automatic – The OpenID relying party simply initiates a request at the authorisation or PAR endpoint, setting the client_id in the request to its entity identifier URL. This triggers a background proccess to register the RP by resolving its trust chain and metadata.

2. The federation client registration endpoint URL

It is advertised in the federation_registration_endpoint server metadata and has this form:

[issuer-url]/federation/clients

3. Web API overview

Resources
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 entity-statement+jwt.

  • [ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body:

Success:

Errors:

Example client registration request:

POST /federation/clients HTTP/1.1
Host: c2id.com
Content-Type: entity-statement+jwt

eyJraWQiOiJleFI1IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJodHRwczpcL1wvZmFwaS5jMmlkL...

Example client registration response with the provisioned client_id, secret, and metadata:

HTTP/1.1 200 OK
Content-Type: entity-statement+jwt
Cache-Control: no-store
Pragma: no-cache

eyJraWQiOiJleFI1IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJodHRwczpcL1wvZmFwaS5jMmlkL...

5. Representations

5.1 OpenID relying party entity configuration

Self-signed JWT containing the federation entity configuration claims of 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, ES384, ES512.

  • typ {string} Set to entity-statement+jwt.

Required JWT claims:

  • iss {string} The entity identifier (URL) of the OpenID relying party, e.g. https://rp.example.com.

  • 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 immediate federation authorities (intermediates or trust anchors).

  • metadata {object} Metadata for the federation entity:

    • openid_relying_party {object} The OpenID relying party metadata. Must contain all parameters (redirect_uris, etc.) necessary for a client registration.

      For a successful registration the parameters must conform to the published OpenID provider metadata in the Connect2id server’s own entity configuration, 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"             : "https://rp.example.com",
  "sub"             : "https://rp.example.com",
  "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" : [ "https://federation.example.com" ],
  "metadata"        : {
      "openid_relying_party"  : {
          "redirect_uris" : [ "https://rp.example.com/cb" ],
          "client_name"   : "My Example Client",
          "logo_uri"      : "https://rp.example.com/logo.png"
      }
  }
}

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 configuration.

  • typ {string} Set to entity-statement+jwt.

JWT claims:

  • iss {string} The configured issuer URL (server identifier) e.g. https://c2id.com.

  • 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.

  • trust_anchor_id {string} The entity identifier of the trust anchor used by the Connect2id server to successfully resolve the submitted entity configuration.

  • authority_hints {string array} Contains the entity identifier of the immediate federation authority (intermediate or trust anchor) used by the Connect2id server to successfully resolve the submitted entity configuration.

  • metadata_policy {object} Metadata policy.

    • openid_relying_party {object} The resolved OpenID relying party policy, empty JSON object if none.

  • metadata {object} Metadata.

    • openid_relying_party {object} The registered OpenID relying metadata, including the provisioned client_id with its client_id_issued_at time. If the Connect2id server provisioned a secret a client_secret and client_secret_expires_at is also included.

Example registration statement claims:

{
  "iss"             : "https://c2id.com",
  "sub"             : "http://rp.example.com",
  "aud"             : "http://rp.example.com",
  "iat"             : 1594365784,
  "exp"             : 1594365843,
  "trust_anchor_id" : "https://federation.example.com",
  "authority_hints" : [ "https://federation.example.com"],
  "metadata_policy" : {
      "grant_types"    : { "subset_of" : [ "authorization_code", "refresh_token" ] },
      "response_types" : { "subset_of" : [ "code" ] }
  },
  "metadata" : {
      "openid_relying_party" : {
          "client_id"                    : "123",
          "client_id_issued_at"          : 94365783,
          "client_secret"                : "aiQu9coo6Deich0aht7eideeneeBai8xah9IeZ4PhootaBaShaecuefohh8Ooqua",
          "client_secret_expires_at"     : 0,
          "application_type"             : "web",
          "subject_type"                 : "public",
          "grant_types"                  : [ "authorization_code", "refresh_token" ],
          "response_types"               : [ "code" ],
          "token_endpoint_auth_method"   : "client_secret_basic",
          "id_token_signed_response_alg" : "RS256",
          "redirect_uris"                : [ "https://rp.example.com/cb" ],
          "client_name"                  : "My Example Client",
          "logo_uri"                     : "https://rp.example.com/logo.png"
      }
  }
}

6. Errors

400 Bad Request

Invalid or malformed request.

Example:

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.

Example:

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.

Example:

HTTP/1.1 404 Not Found

500 Internal Server Error

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

Example:

HTTP/1.1 500 Internal Server Error
Last updated:
PAR →