Skip to content
Connect2id

Server JWK set

1. Public keys

The Connect2id server publishes its public cryptographic keys:

  • To enable clients to verify the authenticity of issued ID tokens.

  • To enable clients to verify the authenticity of JWT-encoded UserInfo responses.

  • To enable clients to verify the authenticity of JWT-secured authorisation responses (JARM).

  • To enable resource servers (web APIs) to verify self-contained (JWT-encoded) access tokens.

  • To enable clients to encrypt request objects (JAR) to the server.

  • To enable clients to encrypt ID token hints to the server.

The public keys are extracted from the configured server JWK set and made available in the same format, as JSON Web Keys (JWK).

The signature validation (JWS) and encryption (JWE) of JWTs can be performed with the open source Nimbus JOSE+JWT library (Java), or any other compliant library.

2. The JWK set URLs

It is advertised in the jwks_uri server metadata and has this form:

[issuer-url]/jwks.json

If OpenID Connect Federation 1.0 is enabled the JWK set will also be published as a signed JWT:

[issuer-url]/jwks.jwt

3. Web API overview

Resources
Representations Errors

4. Resources

4.1 /jwks.json

4.1.1 GET

Retrieves the Connect2id server’s public JWK set.

Header parameters:

  • [ Issuer ] 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 public keys:

GET /jwks.json HTTP/1.1
Host: c2id.com

Example response with the server public JWK set, containing signing and encryption keys of type RSA, EC and OKP (for EdDSA):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "CXup",
      "n": "hrwD-lc-IwzwidCANmy4qsiZk11yp9kHykOuP0yOnwi36VomYTQVEzZXgh2sDJpGgAutdQudgwLoV8tVSsTG9SQHgJjH9Pd_9V4Ab6PANyZNG6DSeiq1QfiFlEP6Obt0JbRB3W7X2vkxOVaNoWrYskZodxU2V0ogeVL_LkcCGAyNu2jdx3j0DjJatNVk7ystNxb9RfHhJGgpiIkO5S3QiSIVhbBKaJHcZHPF1vq9g0JMGuUCI-OTSVg6XBkTLEGw1C_R73WD_oVEBfdXbXnLukoLHBS11p3OxU7f4rfxA_f_72_UwmWGJnsqS3iahbms3FkvqoL9x_Vj3GhuJSf97Q"
    },
    {
      "kty": "EC",
      "use": "sig",
      "crv": "P-256",
      "kid": "yGvt",
      "x": "pvgdqM3RCshljmuCF1D2Ez1w5ei5k7-bpimWLPNeEHI",
      "y": "JSmUhbUTqiFclVLEdw6dz038F7Whw4URobjXbAReDuM"
    },
    {
      "kty": "EC",
      "use": "sig",
      "crv": "P-384",
      "kid": "9nHY",
      "x": "JPKhjhE0Bj579Mgj3Cn3ERGA8fKVYoGOaV9BPKhtnEobphf8w4GSeigMesL-038W",
      "y": "UbJa1QRX7fo9LxSlh7FOH5ABT5lEtiQeQUcX9BW0bpJFlEVGqwec80tYLdOIl59M"
    },
    {
      "kty": "EC",
      "use": "sig",
      "crv": "P-521",
      "kid": "tVzS",
      "x": "AZgkRHlIyNQJlPIwTWdHqouw41k9dS3GJO04BDEnJnd_Dd1owlCn9SMXA-JuXINn4slwbG4wcECbctXb2cvdGtmn",
      "y": "AdBC6N9lpupzfzcIY3JLIuc8y8MnzV-ItmzHQcC5lYWMTbuM9NU_FlvINeVo8g6i4YZms2xFB-B0VVdaoF9kUswC"
    },
    {
      "kty": "OKP",
      "use": "sig",
      "crv": "Ed25519",
      "kid": "27zV",
      "x": "0I6olrZGYml7JGusuKJW9G7D0DZ9UormSady9kR7V4Q"
    },
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "enc",
      "kid": "IHMc",
      "n": "lLrhwERiPmq7XOz6Rwk8q4ey_OGcL4P56Ip01mzKMUfysIwo-nUdwDI_9ntYohpvqiTjnrtZOENhhoqne5M4hqpSfBMmCWSvWL_3wa8FanRWd6lPgGdKJ1a3vV0gLxnCbmdho1CSuSszV4736WkjdDhLcXSRN1kWwWbok94FdPD_egCyBY3cwhvuRzmUgE8LDh-VnNRh1BYc7e9yEMublza8qJpW-N5ljHEU0on08X-lsyl4djEac74H7taDcmtchPLYZy0-ZIxgLmosQ2aYIt6xycfPYsm5x9CGetUqhClpLLaTcyTGq_pH4ECdZtkYHcYJM-3q-XDZTqB6wUaggw"
    },
    {
      "kty": "EC",
      "use": "enc",
      "crv": "P-256",
      "kid": "1yFA",
      "x": "_-aKZeuwWDv4v89dPGdKtpOuOepc_0qDZDhcv3omzX0",
      "y": "Gc5b7muOqbi4QvYJO24a4IqQoOY1pPM69DcpI605Vmw"
    },
    {
      "kty": "EC",
      "use": "enc",
      "crv": "P-384",
      "kid": "TqZ6",
      "x": "3Ex0yUSLvhaOriP8U78kZEEJXxkC0oQmwo1zHTe_nhgKx2YPS97-qmDdRMkByxJ9",
      "y": "MCosrhjIYP4lkoan45MxAZE3QB6IKau5nZHpQ_qDXH8jgcIo2l3M8wdN6iI08kcW"
    },
    {
      "kty": "EC",
      "use": "enc",
      "crv": "P-521",
      "kid": "h38C",
      "x": "AVMBSexPHgq536pZQjN6Si1HAdUdfiW4xrdYzNHR2A9z4zovnKi5xrQ9hWX8QUs4ejVQ3bE9ufhOYL3D7oTwx9Jb",
      "y": "AeMeo858k_6ktxNhlpxBSwGL2hmTI1nBeGi2ZrMVl2qzdjOFf-AVFRSsE9DhAD9sWVUrGrzwONbfmqwIlgbjeH7L"
    }
  ]
}

4.2 /jwks.jwt

4.2.1 GET

Retrieves the Connect2id server’s public signed JWK set when OpenID Connect Federation 1.0 is enabled.

Header parameters:

  • [ Issuer ] 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:

5. Representations

5.1 Server JWK set

The Connect2id server’s public keys (one or more), in JWK set format RFC 7517.

Every key in the JWK set has a unique identifier (kid). The issued signed JWTs will identify the key in the JWS kid header parameter.

Example JWK set including a single public signing RSA key:

{
  "keys" : [
     {
       "kty" : "RSA",
       "use" : "sig",
       "kid" : "P9Zd",
       "e"   : "AQAB",
       "n"   : "kWp2zRA23Z3vTL4uoe8kTFptxBVFunIoP4t_8TDYJrOb7D1iZNDXVeEsYKp6ppmrTZDAgd-cNOTKLd4M39WJc5FN0maTAVKJc7NxklDeKc4dMe1BGvTZNG4MpWBo-taKULlYUu0ltYJuLzOjIrTHfarucrGoRWqM0sl3z2-fv9k"
     }
  ]
}

5.2 Signed server JWK set

The server JWK set as a signed JSON Web Token (JWT). The signature is intended to link the JWK set of the Connect2id server as an OpenID provider to the trust chain in OpenID Connect Federation 1.0 deployments.

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 jwks claim in the federation entity configuration.

  • typ {string} Set to jwk-set+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 JWT issue time, as number of seconds since the Unix epoch.

  • keys {object} The keys member of the server JWK set.

Example signed JWK set claims:

{
  "iss"  : "https://c2id.com",
  "sub"  : "https://c2id.com",
  "iat"  : 1594030600,
  "keys" : [
       {
         "kty" : "RSA",
         "use" : "sig",
         "kid" : "P9Zd",
         "e"   : "AQAB",
         "n"   : "kWp2zRA23Z3vTL4uoe8kTFptxBVFunIoP4t_8TDYJrOb7D1iZNDXVeEsYKp6ppmrTZDAgd-cNOTKLd4M39WJc5FN0maTAVKJc7NxklDeKc4dMe1BGvTZNG4MpWBo-taKULlYUu0ltYJuLzOjIrTHfarucrGoRWqM0sl3z2-fv9k"
       }
    ]
}

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