Products » Connect2id server » Documentation » Standard endpoints »

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:

https://[base-server-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 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...

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, 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"
      }
  }
}

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

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