Skip to content
Connect2id

Federation entity statement

1. Discovering the server’s federation configuration

A Connect2id server which is configured to participate in a OpenID Connect federation publishes a signed statement about itself at a well-known endpoint. The statement is a JSON document listing its federation authorities in order to enable other entities to determine whether it can be trusted or not, metadata about its OpenID provider capabilities, and statement signing keys.

The entity statement format and its retrieval from the well-known endpoint are detailed in the OpenID Connect Federation 1.0 specification.

OpenID providers participating in a federation publish their federation entity statement at a well-known URL which looks like this:

https://[base-server-url]/.well-known/openid-federation

2. Web API overview

Resources
Representations Errors

3. Resources

3.1 /.well-known/openid-federation

3.1.1 GET

Retrieves the server’s federation entity statement.

Success:

Errors:

Example request to get the server’s metadata:

GET /.well-known/openid-federation HTTP/1.1
Host: c2id.com

Example response of a JSON Web Signature (JWS) object / signed JWT with the statement claims:

HTTP/1.1 200 OK
Content-Type: application/jose;charset=UTF-8

eyJraWQiOiJleFI1IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJodHRwczpcL1wvZmFwaS5jMmlkLmNv
bSIsIm1ldGFkYXRhIjp7Im9wZW5pZF9wcm92aWRlciI6eyJyZXF1ZXN0X3BhcmFtZXRlcl9zdXBwb3J
0ZWQiOnRydWUsInB1c2hlZF9hdXRob3JpemF0aW9uX3JlcXVlc3RfZW5kcG9pbnQiOiJodHRwczpcL1
wvZmFwaS5jMmlkLmNvbVwvcGFyIiwiZmVkZXJhdGlvbl9yZWdpc3RyYXRpb25fZW5kcG9pbnQiOiJod
HRwczpcL1wvZmFwaS5jMmlkLmNvbVwvZmVkZXJhdGlvblwvY2xpZW50cyIsImludHJvc3BlY3Rpb25f
ZW5kcG9pbnQiOiJodHRwczpcL1wvZmFwaS5jMmlkLmNvbVwvdG9rZW5cL2ludHJvc3BlY3QiLCJj...

4. Representations

4.1 Federation entity statement

A self-signed JWT containing the federation entity statement claims.

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

JWT claims:

  • iss {string} The configured issuer URL (server identifier) e.g. https://c2id.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 configured 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:

  • constraints {object} The applicable constraints when resolving the entity statement of an OpenID relying party (RP):

    • max_path_length {integer} The maximum allowed number of entity statements between the RP statement and the last entity statement in the trust chain.

    • [ naming_constraints ] {object} Optional naming constraints:

Example entity statement claims:

{
  "iss"             : "https://c2id.com",
  "sub"             : "https://c2id.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_provider"  : {
          "issuer"                                : "https://c2id.com",
          "jwks_uri"                              : "https://c2id.com/jwks.json",
          "registration_endpoint"                 : "https://c2id.com/clients",
          "federation_registration_endpoint"      : "https://c2id.com/federation/clients",
          "pushed_authorization_request_endpoint" : "https://c2id.com/par",
          "authorization_endpoint"                : "https://c2id.com/login",
          "token_endpoint"                        : "https://c2id.com/token",
          "userinfo_endpoint"                     : "https://c2id.com/userinfo",
          "federation_types_supported"            : [ "explicit" ],
          "grant_types_supported"                 : [ "authorization_code", "refresh_token" ],
          "response_types_supported"              : [ "code" ],
          "token_endpoint_auth_methods_supported" : [ "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt", "self_signed_tls_client_auth", ],
          "subject_types_supported"               : [ "public", "pairwise" ],
          "id_token_signing_alg_values_supported" : [ "RS256" ],
          "userinfo_signing_alg_values_supported" : [ "RS256" ]
      },
      "federation_entity" : {
          "name"     : "OP Connect2id",
          "contacts" : [ "federation-admin@c2id.com" ]
      }
  },
  "constraints"     : {
      "max_path_length" : 2,
      "excluded"        : [ "https://some-authority.com" ]
  }
}

5. Errors

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