GET /oauth/jwks

Returns information about the JWK Set for the specified OAuth Provider.

If OpenID Connect is enabled in the platform, the platform’s OAuth Provider publishes a JSON Web Key Set document. Using this operation, you can access the document and retrieve the values.

Per the OpenID specification, http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys:

"Rotation of signing keys can be accomplished with the following approach. The signer publishes its keys in a JWK Set at its jwks_uri location and includes the kid of the signing key in the JOSE Header of each message to indicate to the verifier which key is to be used to validate the signature. Keys can be rolled over by periodically adding new keys to the JWK Set at the jwks_uri location. The signer can begin using a new key at its discretion and signals the change to the verifier using the kid value. The verifier knows to go back to the jwks_uri location to re-retrieve the keys when it sees an unfamiliar kid value. The JWK Set document at the jwks_uri SHOULD retain recently decommissioned signing keys for a reasonable period of time to facilitate a smooth transition."

In the platform, if the time period for JWK validity has passed, it is deprecated, but the JWK doesn't expire until every id_token that is using it has expired.

Authorization Roles/Permissions: Anyone can run this operation.

This topic includes the following sections:

HTTP Method

GET

URL

https://{oauth-provider-url}/oauth/jwks

Sample Request

The example below shows a request for the JWK sets for the platform's OAuth provider.

Sample Request URL

https://oauth.acmepaymentscorp.com/oauth/jwks

Sample request headers

Accept: application/json

Sample request body

Not applicable.

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header	Description
Accept	application/json

Request Parameters

None.

Response

If successful, this operation returns HTTP status code 200, with the JWK set information for the specified OAuth provider.

Sample Response

The sample response below shows successful completion of this operation.

Sample response headers: application/json

Content-Type: application/json
Expires: Thu, 30 Jul 2015 15:58:47 GMT

Sample response body: application/json

{
  "keys" : [ {
    "kty" : "RSA",
    "kid" : "1438289820780",
    "use" : "sig",
    "alg" : "RS256",
    "n" : "idWPro_QiAFOdMsJD163lcDIPogOwXogRo3Pct2MMyeE2GAGqV20Sc8QUbuLDfPl-7Hi9IfFOz--JY6QL5l92eV-GJXkTmidUEooZxIZSp3ghRxLCqlyHeF5LuuM5LPRFDeF4YWFQT_D2eNo_w95g6qYSeOwOwGIfaHa2RMPcQAiM6LX4ot-Z7Po9z0_3ztFa02m3xejEFr2rLRqhFl3FZJaNnwTUk6an6XYsunxMk3Ya3lRaKJReeXeFtfTpShgtPiAl7lIfLJH9h26h2OAlww531DpxHSm1gKXn6bjB0NTC55vJKft4wXoc_0xKZhnWmjQE8d9xE8e1Z3Ll1LYbw",
    "e" : "AQAB"
  }, {
    "kty" : "RSA",
    "kid" : "1438289856256",
    "use" : "sig",
    "alg" : "RS256",
    "n" : "zo5cKcbFECeiH8eGx2D-DsFSpjSKbTVlXD6uL5JAy9rYIv7eYEP6vrKeX-x1z70yEdvgk9xbf9alc8siDfAz3rLCknqlqL7XGVAQL0ZP63UceDmD60LHOzMrx4eR6p49B3rxFfjvX2SWSV3-1H6XNyLk_ALbG6bGCFGuWBQzPJB4LMKCrOFq-6jtRKOKWBXYgkYkaYs5dG-3e2ULbq-y2RdgxYh464y_-MuxDQfvUgP787XKfcXP_XjJZvyuOEANjVyJYZSOyhHUlSGJapQ8ztHdF-swsnf7YkePJ2eR9fynWV2ZoMaXOdidgZtGTa4R1Z4BgH2C0hKJiqRy9fB7Gw",
    "e" : "AQAB"
  } ]
}

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header	Description
Content-Type	application/json

Response Body

The response is a JSON Web Key Set document.

A JSON Web Key Set (JWK Set) is a JSON object that represents a set of JWKs. The JSON object MUST have a "keys" member, with its value being an array of JWKs.

A JSON Web Key (JWK) is a JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.

The Akana OpenID Connect Provider publishes all the valid JSON Web Keys that were used to sign ID tokens at this endpoint.

Below is more information about the common parameters for different key families inside a JWK Set document.

Name	Type	Description
keys[ ]	string	JWK values. One or more.
kty	string	Identifies the cryptographic algorithm family used with the key; for example, RSA or EC. A a case-sensitive string.
use	string	Public key use: identifies the intended use of the public key. This parameter indicates whether a public key is used for encrypting data or verifying the signature on data. Possible values: sig (signature) enc (encryption)
alg	string	identifies the algorithm intended for use with the key. A case-sensitive ASCII string.
kid	string	Key ID: used to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover. Distinct "kid" values are used within a JWK Set when representing different keys.

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item	Value
404	This operation might return a 404 for any of the following reasons: OpenID Connect is not enabled in the OAuth provider The host name is not mapped to the OAuth provider correctly The URL is accessed over HTTP but the provider is configured to accept only HTTPS requests
500	An error occurred processing the call.

More information about Akana OAuth API error messages.

Related Topics