Public JSON Web Key Set

cidaas uses the JWK specification to represent the cryptographic keys used for signing RS256 tokens. This specification defines two high level data structures: JSON Web Key (JWK) and JSON Web Key Set (JWKS).

Here are the definitions directly from the specification:

JSON Web Key (JWK)
A JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.
JSON Web Key Set (JWKS)
A JSON object that represents a set of JWKs. The JSON object MUST have a keys member, which is an array of JWKs.

At the most basic level, the JWKS is a set of keys containing the public keys that should be used to verify any JWT issued by the authorization server. Cidaas exposes a JWKS endpoint for each tenant, which is found at https:///.well-known/jwks.json. This endpoint will contain the JWK used to sign all cidaas issued JWTs for this tenant.

This is an example of the JWKS used by a demo tenant.

{
    "keys": [
            {
            "n": "xe_69ro6qOFosdY2gA1theO3RwJFbd0zW025aDEGbJpwknFhaCsOQDBmjA8ZNuI5WQ",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig",
            "kid": "ffa5009f-f815-4d87-a36b-e4c29e5829b5",
            "kty": "RSA"
            }
           ]
}
  • alg: is the algorithm for the key

  • kty: is the key type

  • use: is how the key was meant to be used.

    For the example above sig represents signature.

  • e: is the exponent for a standard pem

  • n: is the modulus for a standard pem

  • kid: is the unique identifier for the key

Open ID: Open ID is an authentication protocol, it allows users to authenticate sites using a third-party service, for webmasters to provide their own ad hoc login systems, and allowing users to log into multiple unrelated websites without having to have a separate identity and password to login.

For more information on default and custom scopes refer Scope Management.

1. Public RSA Keys

A JSON object that represents a set of JWKs. The JSON object MUST have a keys member, which is an array of JWKs.

The cidaas server publishes its public RSA keys as a JSON Web Key (JWK) set. This is done for the following purposes:

  • To enable clients and other parties to verify the authenticity of identity tokens issued by the server.
  • To enable clients and other parties to verify the authenticity of JWT-encoded claims returned at the UserInfo endpoint.
  • To enable resource servers (web APIs) to verify self-contained (JWT-encoded) access tokens that clients pass to them .
  • To encrypt OpenID Connect request objects to the server.

The public keys are exported from the configured JWK pairs and made available at the following URL:

JSON Web Key set URL: https:///.well-known/jwks.json

The JWK set URL can also be obtained from the server discovery endpoint.

2. Web API Overview

Resources
  • /.well-known/jwks.json [GET]
RepresentationsErrors
  • JWK set
  • 404 Not Found
  • 500 Internal Server Error

3 Resources

3.1 /.well-known/jwks.json

Retrieves the server’s public JWK set.

Success:

  • Code: 200
  • Content-Type: application/json
  • Body: {object} The OpenID provider JWK set.

Errors:

  • 404 Not Found
  • 500 Internal Server Error

Example: request to get the server’s public keys:

GET:/.well-known/jwks.json HTTP/1.1
Host:

The response containing a JSON object with a single public RSA keys and its identifier (to enable key roll-over):

HTTP/1.1 200 OK
Content-Type: application/json
{
    "keys": [
            {
            "n": "jr9m57AZl1elwU6Ztxe09DRz3wANws8f1rXB-q94uqumum5Ia2lXAznc_TDTyNdNG6zB4uDQ7eINa8lyW6ar2w",
            "e": "AQAB",
            "kid": "8e2d2bf3-cd6a-4074-99af-791e753775a6",
            "kty": "RSA"
            },
            {
            "n": "xe_69ro6qOFosdY2gA1theO3RwJFbd0zW025aDEGbJpwknFhaCsOQDBmjA8ZNuI5WQ",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig",
            "kid": "ffa5009f-f815-4d87-a36b-e4c29e5829b5",
            "kty": "RSA"
            }
           ]
}

Here is a quick breakdown of what each property represents:

Metadata Description
alg The alg is the algorithm for the key.
kty The kty is the key type.
use The use is how the key was meant to be used. For the example above sig represents signature.
e The e is the exponent for a standard pem.
n The n is the modulus for a standard pem.
kid The kid is the unique identifier for the key.

4. Representations

4.1 OpenID provider JWK set

The server’s public RSA keys (one or more), as specified in JSON Web Keys (JWK).

Each key in the JWK set has a unique identifier (kid). The issued identity and self-contained access tokens issued by the server will specify the identifier of the used key in the JWT kid header parameter.

Example: JWK set including a single public RSA key:

{
    "keys": [
            {
            "n": "iwlNcEM5m5Dy7bm_X1ZTJthzD_KIWpJ3gD79U-lt6fhO3Dyt9lqo447RyseEc1ZCUBDlpr7jTqlb3ZAeQb-sVw",
            "e": "AQAB",
            "kid": "47ce2098-311c-436d-ad1d-7379db3ac2d5",
            "kty": "RSA"
            }

            ]
}

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 cidaas server logs for details.

Example:

HTTP/1.1 500 Internal Server Error



results matching ""

    No results matching ""