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

The federation client registration endpoint URL can be found out from the server metadata endpoint and looks like this:

https://[base-server-url]/federation/clients

2. Web API overview

Resources
Representations Errors

3. Resources

3.1 /federation/clients

3.1.1 POST

Registers a new federated OAuth 2.0 / OpenID Connect client.

Header parameters:

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

Body:

Success:

Errors:

Example client registration request:

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

eyJraWQiOiJleFI1IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJodHRwczpcL1wvZmFwaS5jMmlkL...

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

eyJraWQiOiJleFI1IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJodHRwczpcL1wvZmFwaS5jMmlkL...

4. Representations

4.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, ES384, ES512.

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 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"             : "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.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"
      }
  }
}

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

  • 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"             : "https://c2id.com",
  "sub"             : "http://rp.example.com",
  "aud"             : "http://rp.example.com",
  "iat"             : 1594365784,
  "exp"             : 1594365843,
  "authority_hints" : [ "https://federation.com"],
  "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" },
      }
  }
}

5. 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 →