Skip to content
Connect2id

Federation entity configuration

1. Discovering the server’s federation configuration

A Connect2id server configured to participate in a OpenID Connect federation publishes a self-signed statement encoded as a JWT, called entity configuration. The entity configuration enables discovery of its federation authorities, federation JWK set and metadata with federation specific OpenID provider capabilities.

The entity configuration JWT structure and its retrieval are specified in OpenID Connect Federation 1.0.

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

[issuer-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 entity configuration when OpenID Connect Federation 1.0 is enabled.

Header parameters:

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

Success:

Errors:

Example request to get the server’s federation entity configuration:

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

Example response with the entity configuration JWT:

HTTP/1.1 200 OK
Content-Type: application/entity-statement+jwt

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

4. Representations

4.1 Federation entity configuration

A self-signed JWT containing federation entity configuration claims.

JWT header parameters:

  • alg {string} The JSON Web Signature (JWS) algorithm, set to RS256.

  • kid {string} The identifier of the signing RSA key from the JWK set in the jwks claim of the statement.

  • 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 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, as a JSON Web Key (JWK) set.

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

  • [ trust_marks ] {array of JSON objects} Optional list of trust mark entries. Each entry is represented by a JSON object with key id representing the trust mark identifier and value trust_mark representing the trust mark JWT.

  • 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",
          "signed_jwks_uri"                       : "https://c2id.com/jwks.jwt",
          "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
Content-Type: application/json

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

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