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:

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:

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

2. Web API Overview

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:

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:

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