Products » Connect2id server » Documentation » Old versions » Connect2id server 7.x - 9.x » Standard endpoints »

OpenID Connect Federation 1.0 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
/.well-known/openid-federation [GET]
Representations	Errors
Federation entity statement	404 Not Found 500 Internal Server Error

3. Resources

3.1 /.well-known/openid-federation

3.1.1 GET

Retrieves the server's federation entity statement.

Success:

Code: 200
Content-Type: application/jose;charset=UTF-8
Body: {string} The signed entity statement.

Errors:

404 Not Found
500 Internal Server Error

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:
- openid_provider {object} A copy of the OpenID provider metadata.
- federation_entity {object} Common federation entity metadata:
  - [ name ] {string} Optional human-readable name of the entity.
  - [ contacts ] {string array} Optional list of contacts, such as email addresses, telephone numbers, addresses, and names.
  - [ policy_uri ] {string} Optional federation policy URL.
  - [ homepage_uri ] {string} Optional homepage URL.
  - [ trust_marks ] {string array} Optional list of certification marks as JWTs.
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:
  - [ permitted ] {string array} The explicitly permitted entity IDs in a trust chain, omitted if none.
  - [ excluded ] {string array} The excluded entity IDs in a trust chain, omitted if none.

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" : [ "[email protected]" ]
      }
  },
  "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.