JWKS Authorization

This page outlines the steps for implementing JWKS (JSON Web Key Set) authorization for a SMART-on-FHIR Back-end Service client, including key generation, endpoint discovery, assertion building, and token generation.

Prerequisites

• The client generates an asymmetric cryptographic key pair (e.g., RSA or ECDSA). The private key is used to sign JWT (JSON Web Tokens) assertions, and the corresponding public key is made available to the authorization server for signature verification.
• A SMART-on-FHIR Back-end Service client is created as per the steps mentioned here.
• For endpoints, refer to FHIR Base URLs.

Steps

• Endpoint Discovery - In this step, your app obtains the Conformance Statement from the FHIR endpoint. This response contains the authentication servers, from which your app obtains the authentication code which it then exchanges for the token.

• Private Key - In this step, the stored private key is retrieved by your app. The private key is used as part of the assertion for token generation.
• Building an assertion - An "assertion" refers to a package of information, often a JWT itself, that facilitates the sharing of identity and security information across security domains. It acts as a statement or claim about a subject or principle issued by a trusted party and often includes conditions under which the assertion is considered valid. The assertion object must have the following attributes:
  • issuer: This field contains your app’s client ID.
  • sub: This field contains your app’s client ID.
  • aud: A value that identifies the authorization server as an intended audience. The authorization server must verify that it is an intended audience for the token. The audience should be the URL of the authorization server’s token endpoint. This field contains the token endpoint URL. This value will be available when invoking the well-known configuration URL. Use the “token_endpoint” attribute from the response.
  • jti: A unique identifier for the token, which can be used to prevent reuse of the token. These tokens must only be used once unless conditions for reuse are negotiated between the parties; any such negotiation is beyond the scope of this specification. Use a UUID (Universally Unique Identifier) for this field.
  • exp: These attributes denote expiration time on or after which the JWT must not be accepted for processing. It’s typically set to current date and time in UTC (Universal Time Coordinated) plus a time delta.

    📘

    Note:

    The exp claim in the JWT assertion must not exceed 60 minutes from the time of issuance. Our authorization server only supports a maximum token validity of 60 minutes. Assertions with longer expiration times will be rejected.

  • A JWT assertion must be digitally signed using a private key fetched in the previous step.
• Generating a token – To generate a token, invoke the token endpoint with the following payload as Form Encoded:
  • grant_type: client_credentials
  • client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  • client_assertion: Client Assertion built in previous step
  • scope: SMART-on-FHIR scopes needed for the app

Sequence Diagram