Authentication requirements for SMART on FHIR - AWS HealthLake
Required authorization server elementsRequired claims

Authentication requirements for SMART on FHIR

To access FHIR resources in a SMART on FHIR HealthLake data store, a client application must be authorized by an OAuth 2.0-compliant authorization server and present an OAuth Bearer token as part of a FHIR REST API request. To find the authorization server's endpoint use the HealthLake SMART on FHIR Discovery Document via a Well-Known Uniform Resource Identifier. To learn more about this process, see Fetching a SMART on FHIR enabled HealthLake data store's Discovery Document.

When you create a SMART on FHIR HealthLake data store, you must define the authorization server's end point and the token endpoint in the metadata element of the CreateFHIRDatastore request. To learn more defining the metadata element, see Creating a SMART on FHIR enabled HealthLake data store.

Using the authorization server endpoints, the client application will authenticate a user with the authorization service. Once authorized and authenticated, a JSON Web Token (JWT) is generated by the authorization service and passed to the client application. This token contains FHIR resource scopes that the client application is allowed to use, which in turn restricts what data the user is able to access. Optionally, if the launch scope was provided then the response will contain those details. To learn more about the SMART on FHIR scopes supported by HealthLake, see Supported SMART on FHIR OAuth scopes by HealthLake.

Using the JWT granted by the authorization server, a client application makes FHIR REST API calls to a SMART on FHIR enabled HealthLake data store. To validate and decode the JWT, you need to create a Lambda function. HealthLake invokes this Lambda function on your behalf when a FHIR REST API request is received. To see an example starter Lambda function, see Using AWS Lambda for token validation with a SMART on FHIR enabled HealthLake data store.

Authorization server elements required to create a SMART on FHIR enabled HealthLake data store

In the CreateFHIRDatastore request, you need to provide the authorization endpoint and the token endpoint as part of the metadata element in the IdentityProviderConfiguration object. Both the authorization endpoint and token endpoint are required. To see example of how this is specifed in CreateFHIRDatastore request, see Creating a SMART on FHIR enabled HealthLake data store.

Required claims to complete a FHIR REST API request on a SMART on FHIR enabled HealthLake data store

Your AWS Lambda function must contain the following claims for it to be a valid FHIR REST API request on a SMART on FHIR enabled HealthLake data store.

  • nbf: (Not Before) Claim — The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. The processing of the "nbf" claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the "nbf" claim. The sample Lambda function we provide converts iat from the server response into nbf.

  • exp: (Expiration Time) Claim — The "exp" (expiration time) claim identifies the expiration time on or after which the JWT must not be accepted for processing.

  • isAuthorized: A boolean set to True. Indicates that request has been authorized on the authorization server.

  • aud: (Audience) Claim — The "aud" (audience) claim identifies the recipients that the JWT is intended for. This must be a SMART on FHIR enabled HealthLake data store endpoint.

  • scope: This must be at least one FHIR resource related scope. This scope is defined on your authorization server. To learn more about FHIR resource related scopes accepted by HealthLake, see HealthLake data store FHIR resource specific scopes.