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:
A JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.
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:
The JWK set URL can also be obtained from the server discovery endpoint.
2. Web API Overview
Resources |
---|
|
Representations | Errors |
---|---|
|
|
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:
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