FHIR Server Security

By adding authorization requirements to basic authentication, you can restrict server access to InterSystems users who are authorized to work with a specific security resource (which is unrelated to an HL7® FHIR® resource). In InterSystems security terms, only users who belong to roles that have privileges to the security resource are authorized to perform interactions on the server. Users with a Write privilege to the required security resource can perform create, delete, update, and conditional update interactions on the FHIR server. Users with a Read privilege to the security resource can perform all interactions except the ones that require write access.

The following is a basic overview of how to create a security resource, assign privileges to the security resource for a role, and assign users to the role. For a detailed description of InterSystems authorization, see the Authorization Guide; for an introduction to security, see About InterSystems Security.

1. To create the security resource that controls whether users are authorized to perform interactions on the server, open the Management Portal and navigate to Home > System Administration > Security > Resources. Setting the Public Permission to Read allows all authenticated users to perform Read interactions on the server. For more information, see Create or Edit a Resource.

2. To create a role that will have privileges to the security resource, navigate to Home > System Administration > Security > Roles. Most commonly, there will be two roles, one for users who should have Read access and another for users who should have Write access. For more information, see Create Roles.

3. To grant privileges to a role:

   1. Click Add in the Privileges section of the role’s General tab.

   2. Select the security resource that will control server authorization, and click OK.

   3. Click Edit next to the new Privilege.

   4. Select the permissions you want the role to have for the security resource.

   For more information, see Give New Privileges to a Role.

4. Now that you have a role that has permissions to the security resource, select the Members tab and add the users that you want to have those permissions. For more information, see Assign Users or Roles to the Current Role.

Configuring a FHIR Server to Require a Security Resource

Once you have created or chosen the security resource that will control a user’s ability to perform FHIR interactions, configure the server to require this security resource in one of the following ways:

Adding a Security Resource to a FHIR Server Using the Management Portal

Navigate to the FHIR Server Management page, and under FHIR Server Authorization Settings, select a security resource. The management portal only allows you to add a security resource to an existing FHIR server.

Adding a Security Resource to a FHIR Server Using the REST API

In the FHIR Config REST APIOpens in a new tab, set the value of endpoint.service_config_data.required_resource to identify the chosen security resource:

• using the POST /endpoint method when creating a new FHIR server.

• using the PUT /endpoint method when adding a security resource to an existing FHIR server.

Adding a Security Resource to a FHIR Server Programmatically

In the terminal or using a custom method, in the namespace of an existing FHIR server:

 set config = ##class(HS.FHIRServer.ServiceAdmin).GetInstanceConfigData(serviceId)
 set config.Resource = "my_resource"
 do ##class(HS.FHIRServer.ServiceAdmin).SetInstanceConfigData(serviceId,config)

Where my_resource indicates the chosen security resource, and serviceID identifies the desired endpoint.

Adding a Security Resource to a FHIR Server Using the Command Line Interface

 do ##class(HS.FHIRServer.ConsoleSetup).Setup()

Using option 4 Configure a FHIRServer Endpoint set the value of RequiredResource to identify the chosen security resource.

This section explains how the FHIR server enforces the scopes of an OAuth 2.0 access token that is passed along with a request.

If your FHIR server needs to interpret scopes differently, you need to customize the FHIR server and override the OAuth2TokenHandlerClass parameter to specify your custom token handling class.

Access tokens can have the following scopes:

• Patient resource scopes (patient) limit authorization to resources related to the patient specified in the patient context claim. They are likely to be used, for example, when a patient is looking at their data through a web portal.

• User resource scopes (user) allow access to view or manipulate FHIR resource types that the particular user is authorized to access. This kind of authorization is subject to any implementation-specific authorization processing (for example, consent).

• System scopes (system) represent external systems. They are used to facilitate system-to-system interactions such as bulk data extracts.

You can configure the InterSystems IRIS for Health OAuth 2.0 authorization server (InterSystems OAuth server) by defining custom classes which implement its behavior. If you are using an InterSystems OAuth server to issue tokens for a FHIR server, InterSystems provides the following implementation classes, which extend the default classes in the %OAuth.Server package to implement compatibility with the FHIR server’s default token handling class:

* Extends %OAuth2.Server.JWTOpens in a new tab.

To quickly set up an InterSystems OAuth server on your instance which uses these classes, you can issue the following Terminal command:

 do ##class(HS.HC.OAuth2.Server.Installer).ConfigureInternalOAuthServer()

The normal token request process includes the Patient and Encounter contexts in the access token when those contexts are requested. To determine the presence or absence of a particular context in an access token, you can use either the GetIntrospection() method of the %SYS.OAuth2.AccessTokenOpens in a new tab class or the ValidateJWT() method of the %SYS.OAuth2.ValidationOpens in a new tab class.

If you want to further customize the behavior of the InterSystems OAuth server for use with your FHIR server, implement classes which extend these HS.HC.OAuth2.Server classes.

You can set up your FHIR server to be compatible with SMART on FHIR client applications.

1. Configure a FHIR server, following the instructions in Installing and Configuring a FHIR Server.

2. Create a client definition that registers your FHIR server as a resource server to your OAuth 2.0 server, as described in OAuth 2.0 Authentication. Be sure to specify the following for your FHIR server’s client configuration:

   Application name	Enter the local name of the client application.
   Client name	Enter the global name to be used for dynamic registration.
   Description	Enter a description of the server.
   Enabled	Check this box.
   Client Type	Check the Resource server radio button.
   SSL/TLS configuration	From this dropdown, select the same SSL option you selected previously.
   Authentication Type	Choose the basic radio button.

   When you finish filling out the form, save your configuration options by clicking Dynamic Registration and Save.

3. Configure the FHIR server to use the name in the OAuth 2.0 client registration, as follows:

   1. Navigate to Home > Health > FHIR.

   2. In the tile representing your FHIR server, open the menu and choose Edit.

   3. Under FHIR Server Authorization Settings, in the OAuth Client Name dropdown, choose the Client name that you assigned the FHIR resource server in the step above.

   4. Click Save.