On this page:

7.19Security Recipes

 

This page provides examples of how to configure Smile CDR for specific security designs.

7.19.1App: Local Users with HTTP Basic Authentication

 

This example illustrates how to set up a simple application. In this example, we're using Smile CDR's database for both resource storage as well as user storage and authentication. We will set up two users:

  • A Regular User – with read-only access to data for a single patient
  • An App Admin – with access to create and maintain data on the server

The following diagram illustrates this setup.

Security Overview

Setting Up Modules

  • Create Security Module

If your configuration does not already have one, first you should create a Local Inbound Security module. Configure this module with appropriate password encoding settings for your needs.

  • Create FHIR Storage

Create a FHIR Storage (Relational) module for the version of FHIR you are looking to support.

  • Create FHIR Endpoint

Create a FHIR Listener module for the version of FHIR you are looking to support.

The FHIR REST endpoint should be configured with HTTP Basic security enabled, and the Username/Password Authentication dependency pointed to your Inbound Security module. This is shown in the screenshot below.

Basic settings

Defining Permissions: App Admin

We will define permissions for an administrative user, who is allowed to perform any function on the repository. This user can create, update, and delete resources as required.

To set this up, grant the user the following permissions:

Permission Argument Explanation
ROLE_FHIR_CLIENT (n/a) Allow user to be a FHIR client.
ROLE_FHIR_CLIENT_SUPERUSER (n/a) Allow user to perform any FHIR tasks.

Defining Permissions: Regular User

We will then define permissions for a user who is authorized to be a FHIR Client, and who can read any resource of types ValueSet and CodeSystem. Aside from that, the user can only read resources within a specific Patient compartment. This means that the user can access general administrative data (ValueSet and CodeSystem do not not typically contain sensitive data).

The user is blocked from reading other data that isn't in a specific Patient compartment to which they have access. The Patient compartment belongs to a specific Patient resource (e.g. Patient/123), and the only resources that can be read are limited to that specific patient instance as well as other resources with an explicit reference to that resource from one of the reference types defined by FHIR's Patient compartment (e.g. "Observations with the given patient as the subject" and "MedicationRequests with the given patient as the subject").

To set this up, grant the user the following permissions:

Permission Argument Explanation
ROLE_FHIR_CLIENT (n/a) Allow user to be a FHIR client.
FHIR_READ_ALL_OF_TYPE ValueSet Allow user to read any ValueSet resources.
FHIR_READ_ALL_OF_TYPE CodeSystem Allow user to read any CodeSystem resources.
FHIR_READ_ALL_IN_COMPARTMENT Patient/123 Allow user to read any Patient, Observation, QuestionnaireResponse, DiagnosticOrder, etc. that belong to the patient Patient/123.

Calling the API

Now that you have a FHIR Endpoint that has been secured using HTTP Basic Authentication, you will need to add an Authorization header to your requests.

Here is an example request showing the Authorization header:

GET /Patient/123
Accept: application/fhir+json
Authorization: Basic [credentials]

The [credentials] part above is a base64 encoded string in the format username:password. For example, the username admin and password password you would result in the following header:

Authorization: Basic YWRtaW46cGFzc3dvcmQ=

The base64 command can be used to base64 encode the credentials. For example:

echo -n "admin:password" | base64
YWRtaW46cGFzc3dvcmQ=