Skip to main content

JWKS Usage Example

Understand how JSON Web Key Sets and key pairs are used by web applications.

JWKS are utilized, for example, by OAuth authorization servers and client applications for transferring in a standardized way the client application's credentials. When a client application registers with an authorization server, it can submit its public keys, or a reference that points to those keys, in the form of JWKS.

This setup is particularly relevant in the OAuth private_key_jwt client authentication method. Here, the client application sends a JWT, signed with its private key, to authenticate itself to the authorization server. The authorization server then uses the corresponding public key from the JWKS, provided at registration, to verify the token's authenticity. This process ensures that the communication between the client and the server is both secure and verifiable.

  1. The client application is registered at the authorization server with it's public key.

  2. The client application generates a JSON Web Token (JWT) header and payload and base64URL encode them.

  3. The payload and header are concatenated together in the encodedHeader.encodedPayload format to form an assertion.

  4. The assertion is signed using a cryptographic algorithm that takes the input data (assertion) and the client's private key to produce a signature.

  5. The signature is base64URL encoded.

  6. The result is concatenated to from the JWT using the encodedHeader.encodedPayload.encodedSignature format.

  7. The client application passes the JWT to the authorization server for client authentication, for example, while calling the authorization server's /token endpoint.

    The JWT is passed as the value of the client_assertion request body parameter.

    The request must contain the client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer parameter.

  8. The authorization server decrypts the received JWT using client application's public key to verify the assertion.

Below, you can see examples of each object used to create a JWT.

{
    "kty": "RSA",
    "e": "AQAB",
    "use": "sig",
    "kid": "12345",
    "alg": "RS256",
    "n": "k_QHrbcA0rUGhSXl51zwlT_I8Lh7FMTdRAv87opf5q7kql8L4AKaSWjDC8LZyA83jDLkiSK_LkbZmVc_MWFi50kLHkoN92bacu_mK_rP0gjVLZsQkN04CU-DOWcf0vl-yRRKLsXGO04SMdrBLRGK1L1nFP8oV4Ea7I9qMrnDA9xtkEduqronrQRqqNo13dD0lVu4exZ5PFOJg7QpeLQGqxeSTiS-Z5GT8zOrZJUPw6EV_VAUDm-LizGMGWUT5izReFf6z4gNKiGLdjZeuDY4bJNdHquVPQJ8ic1_Uyg4llNbL_VnPEMKMuMz3PE3IQYOCGFfA72l0xrEYs5hzDb8Jw"
}

Below, you can find a working example of a JWT you would receive as a result along with both keys in X.509 PEM format for simplicity. You can use the below resources at sites like, for example, jwt.io to test it. Once you paste the sample JWT, public key, and private key, you will receive the message that your signature was successfully verified.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMzQ1In0.eyJpc3MiOiJjbGllbnRfaWQiLCJzdWIiOiJjbGllbnRfaWQiLCJhdWQiOiJodHRwczovL3NhbXBsZS1hdXRob3JpemF0aW9uLXNlcnZlci5jb20vb2F1dGgvdG9rZW4iLCJleHAiOjE3MTYyMzkwMjIsImlhdCI6MTkxNjIzOTAyMn0.jhesV1CTAdqumzdU0ce-wtMyQgl_TpSGsPmO1lwABS1roPFOrsPbfD18CyacCXvbKgI8B3WIIB0fJxCSJhXwMGBmVtV0y71jp-WIB8NAnqiGxZq4hVhpMteLc6xpMmeOD4VKg85Gq6sFK3PLI0eEA9yIoV8NFgwMTwhQNhMWl9vFvnN8yC5eFVwGE6MBxRkjYIcqr84OX96Dg2LLqU4h6ruFcXGPTYJWNzw__J6a3FAqUN9IrKFHmTMNkSTaYyhYiEPebLYgGECnl3jWPdNCyMQgNdVSCOATJIikRZMRh46Yvkme06zeSyKHDBSHUj_qmSrFQ9sE1b7BVQMHzfiycA