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

Back to top

URL

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

Back to top

Sample Request

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

Request URL

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

Sample request headers

Accept: application/json

Sample request body

Not applicable.

Back to top

Request Headers

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

Header Description
Accept application/json

Back to top

Request Parameters

None.

Back to top

Response

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

Back to top

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

Line breaks have been added for display reasons. Indentation in subsequent lines indicates a line break; it does not represent spaces in the content.

{
  "keys" : [ {
    "kty" : "RSA",
    "kid" : "1438289820780",
    "use" : "sig",
    "alg" : "RS256",
    "n" : "idWPro_QiAFOdMsJD163lcDIPogOwXogRo3Pct2MMyeE2GAGqV20Sc8QUbuLDfPl-7Hi9IfFOz--JY6QL5l9
2eV-GJXkTmidUEooZxIZSp3ghRxLCqlyHeF5LuuM5LPRFDeF4YWFQT_D2eNo_w95g6qYSeOwOwGIfaHa2RMPcQAiM6LX4ot
-Z7Po9z0_3ztFa02m3xejEFr2rLRqhFl3FZJaNnwTUk6an6XYsunxMk3Ya3lRaKJReeXeFtfTpShgtPiAl7lIfLJH9h26h
2OAlww531DpxHSm1gKXn6bjB0NTC55vJKft4wXoc_0xKZhnWmjQE8d9xE8e1Z3Ll1LYbw",
    "e" : "AQAB"
  }, {
    "kty" : "RSA",
    "kid" : "1438289856256",
    "use" : "sig",
    "alg" : "RS256",
    "n" : "zo5cKcbFECeiH8eGx2D-DsFSpjSKbTVlXD6uL5JAy9rYIv7eYEP6vrKeX-x1z70yEdvgk9xbf9alc8siDfAz3
rLCknqlqL7XGVAQL0ZP63UceDmD60LHOzMrx4eR6p49B3rxFfjvX2SWSV3-1H6XNyLk_ALbG6bGCFGuWBQzPJB4LMKCrOFq-
6jtRKOKWBXYgkYkaYs5dG-3e2ULbq-y2RdgxYh464y_-MuxDQfvUgP787XKfcXP_XjJZvyuOEANjVyJYZSOyhHUlSGJapQ8z
tHdF-swsnf7YkePJ2eR9fynWV2ZoMaXOdidgZtGTa4R1Z4BgH2C0hKJiqRy9fB7Gw",
    "e" : "AQAB"
  } ]
}

Back to top

Response Headers

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

Header Description
Content-Type application/json

Back to top

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.

Back to top

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 Enterprise API Platform API error messages.

Back to top

Related Topics