Configure SMART Inbound Security

The SMART on FHIR Inbound Security module validates the access tokens that third-party applications present to the Patient Access API. Its onAuthenticateSuccess callback script grants the session access to the member's data and stores the token claims needed for usage reporting.

Create the Module

1. Create a SMART on FHIR Inbound Security module, for example with the module ID smart_auth_pa.
2. Define the payer's IdP as a trusted OpenID Connect server, either through the Web Admin Console or with a seed file. See Creating a Server Definition and the server pre-seed file setting.
3. Set the callback script described below.

module.smart_auth_pa.type=SECURITY_IN_SMART
module.smart_auth_pa.config.seed_servers.file=classpath:/config_seeding/oidc-servers-pa.json
module.smart_auth_pa.config.callback_script.file=classpath:/scripts/PatientAccessAuthCallback.js

Write the Callback Script

The following script grants read access to the Patient compartment named in the patient claim, and stores three claims as user data on the session. The user data keys (patient_id, client_id, and subject) must match the keys read by the transaction log interceptor.

function onAuthenticateSuccess(theOutcome, theOutcomeFactory, theContext) {
   let patientId = theContext.getClaim('patient');
   // Keycloak and some other IdPs carry the client ID in the "azp" claim
   let clientId = theContext.getClaim('client_id') || theContext.getClaim('azp');
   let subject = theContext.getClaim('sub');

   theOutcome.addAuthority('ROLE_FHIR_CLIENT');
   theOutcome.addAuthority('FHIR_CAPABILITIES');

   if (patientId) {
      theOutcome.addAuthority('FHIR_READ_ALL_IN_COMPARTMENT', 'Patient/' + patientId);
      theOutcome.setUserData('patient_id', patientId);
   } else {
      Log.warn('No "patient" claim in access token for user ' + theOutcome.getUsername());
   }

   if (clientId) {
      theOutcome.setUserData('client_id', clientId);
   }
   if (subject) {
      theOutcome.setUserData('subject', subject);
   }

   return theOutcome;
}

Adjust the claim names to match the access tokens issued by your IdP. A token without a patient claim receives no access to member data, and its requests are logged without a patient_id.

Leave enforce_approved_scopes_to_restrict_permissions at its default value of true, so that the permissions granted above are reduced to the scopes the member approved.