FHIR Server Security

You can control which clients can make requests to the FHIR server and the interactions they can perform using InterSystems security strategies and OAuth 2.0.

During development and debugging, you can temporarily allow requests without authentication credentials to reach the server.

Basic Authentication

By default, the FHIR server enforces basic authentication in which any user with credentials to an InterSystems product can access the FHIR server by including those credentials in the header of the REST call. In this security strategy, the user’s authorization within the InterSystems product is not a factor; any authenticated user can perform CRUD interactions on the FHIR server.

Adding Authorization Requirements

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 resource are authorized to perform interactions on the server. Users with a Write privilege to the required resource can perform create, delete, update, and conditional update interactions on the FHIR server. Users with a Read privilege to the resource can perform all interactions except the ones that require write access. Remember that FHIR transactions are recursive, so a user must hold Write privileges if the transaction request contains both read and write interactions.

The following is a basic overview of how to create a resource, assign privileges to the 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.

To create the resource that controls whether users are authorized to perform interactions on the server, open the Management Portal and navigate to 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.
To create a role that will have privileges to the resource, navigate to 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.
To grant privileges to a role:
1. Click Add in the Privileges section of the role’s General tab.
2. Select the 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 resource.
For more information, see Give New Privileges to a Role.
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 the Server

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 resource in one of the following ways:

In the management portal, using the FHIR Server Management page.
Via the the FHIR Config REST APIOpens in a new tab. When calling the POST /endpoint method to create a FHIR server endpoint using a REST client, or calling the PUT /endpoint method to update one, set the value of endpoint.service_config_data.required_resource to identify the chosen security resource.

Programmatically or in the Terminal

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

my_resource indicates the chosen security resource. serviceID identifies the desired endpoint.

Using a 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.

OAuth 2.0 Authentication

By setting up the FHIR server as an OAuth 2.0 resource server, you can reject a client’s FHIR requests unless it has a valid access token that it obtained from an OAuth 2.0 authorization server. A FHIR request’s access token is checked twice, once by the REST handler and again when it reaches the FHIR server’s internal Service. Because the access token is enforced when the request hits the REST handler, the token has already been validated when it enters an interoperability production (if the FHIR server has been configured to use a production). The REST handler and the Service use the same class to validate the token, which is the class specified by the OAuth2TokenHandlerClass parameter of the server’s Interactions class.

The FHIR server’s default OAuth2TokenHandlerClass is HS.FHIRServer.Util.OAuth2TokenOpens in a new tab. This default token handling class enforces access as described in Access Token Scopes to ensure SMART on FHIR compatibility.

Important:

If you are using an InterSystems IRIS for Health OAuth 2.0 server to issue authorization tokens for your FHIR server, configure your OAuth 2.0 server to use or extend the classes in the HS.HC.OAuth2.Server package, as described in Configuring the OAuth Server. Doing so ensures that the OAuth server behaves as expected by the FHIR server’s default token handing class.

The first step in identifying the FHIR server as a resource server is to create a client configuration using System Administration > Security > OAuth 2.0 > Client. After creating a Server Description for the OAuth 2.0 authorization server, create a new client configuration for the FHIR server, specifying that it is of type Resource Server. For more information about setting up a resource server in InterSystems products, see Using an InterSystems IRIS Web Application as an OAuth 2.0 Resource Server.

Note:

If you are using an InterSystems IRIS for Health OAuth 2.0 server to issue tokens to a FHIR server on the same instance, you can invoke the ConfigureInternalOAuthClients()Opens in a new tab method of the HS.HC.OAuth2.Client.InstallerOpens in a new tab class to quickly set up client configurations as described in the preceding paragraph.

Once you have defined the client configuration for the FHIR server:

In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.
Select the endpoint of the FHIR server.
Select Edit.
In the OAuth Client Name field, enter the Application Name of the resource server as defined in the Management Portal.
Select Update.

Access Token Scopes

Note:

Although read/write syntax is supported, permissions are best specified using SMART on FHIR v2–style syntax. See the HL7 specificationOpens in a new tab for details.

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 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 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 represent external systems. They are used to facilitate system-to-system interactions such as bulk data extracts.

Note:

When a FHIR interaction is authorized by patient or user resource scopes, it should be subject to any additional implementation-specific processing (such as consent) that may be in use. This type of additional processing is not expected for interactions authorized by system scopes.

Basic Processing

The access token that accompanies a request must include at least one server scope, patient resource scope, or user resource scope, or else the request is rejected with an HTTP 403 error. If multiple scopes are present, the union of the scopes is evaluated. For example, if both user and patient scopes are present, all scopes are potentially evaluated, until any of them authorizes the current FHIR interaction, or until none of them does.

Patient Resource Scope / Patient Context Value

If an access token includes a patient resource scope, it must also include a patient context value (also known as “launch context”) that is the Patient resource ID. This patient context value provides access to the specified Patient and its related resources. In most cases, the patient resource scope must provide explicit access to a related resource. For example, if the patient context value is 1234, and the patient resource scope is patient/Observation.cruds, the FHIR server can grant access to an Observation that references the Patient with the id 1234. In this case, patient/Observation.cruds (or another scope granting access to Observations) is required. As an exception to this requirement, a FHIR client can access a resource that is shared among multiple Patients without obtaining a patient resource scope that is specific to that resource. For example, if the scope is patient/Patient.rs, then a client can access an Organization referenced by the Patient without having a scope patient/Organization.rs.

To obtain the patient context value from the access token, the FHIR server examines the patient property of the access token.

The FHIR server handles search requests accompanied by a valid access token in the following manner:

_include and _revinclude parameters are allowed.
If the FHIR server is enforcing a patient context value:
- Chained and reverse chained (_has) parameters are allowed.
- The search resource type must be allowed by the patient scopes.
- If the search resource type is not Patient, reference search parameter values must indicate a Patient resource that is in the patient context.
- If _include and _revinclude parameters are present they must indicate only pulling in resources that are allowed by the scopes.
- For a Patient search, any _id value must match the patient context value.
- In all other cases, perform the search and check that all of the resources in the result set are allowed by the scope and context.

Create Interaction

Requests to create a new Patient resource must include a user resource scope that gives write permissions (user/Patient.cud or user/Patient.cruds). You cannot perform a .c interaction for a Patient resource with a patient resource scope; patient resource scopes must include a patient context value, and the .c interaction cannot include a resource id.

$everything

Requests for the Patient or Encounter $everything operation must include an access token that has read access to all of the resources that might be returned by the request. If a resource is encountered in the compartment that is not covered by the scope, then the entire request is rejected with an HTTP 403 Forbidden error.

The practical application of this requirement is:

If a _type operation query parameter is specified, then the scope must include read access to all of the resource types requested.
If no types are specified and the access token is using a patient resource scope, it should have a patient/*.rs or patient/*.cruds scope in order to return any resource encountered in the compartment.
If no types are specified and the access token is using a user resource scope, it should have a user/*.rs or user/*.cruds scope in order to return any resource encountered in the compartment.

Configuring the InterSystems IRIS for Health OAuth Server

You can configure the InterSystems IRIS for Health OAuth 2.0 server by defining custom classes which implement its behavior. If you are using an InterSystems IRIS for Health OAuth 2.0 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:

Function	Class Name
Authenticate Class	HS.HC.OAuth2.Server.AuthenticateOpens in a new tab
Validate User Class	HS.HC.OAuth2.Server.ValidateOpens in a new tab
Session Maintenance Class	HS.HC.OAuth2.Server.SessionOpens in a new tab
Generate Token Class	HS.HC.OAuth2.Server.GenerateOpens in a new tab *
Revoke Token Class	HS.HC.OAuth2.Server.RevokeOpens in a new tab

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

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

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

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

Setting up SMART on FHIR

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

Prerequisite

You must have an OAuth server that is configured to issue tokens as described in the SMART on FHIR specificationOpens in a new tab. For information about how to configure an InterSystems IRIS for Health OAuth 2.0 server, see Using InterSystems IRIS as an OAuth 2.0 Authorization Server. Ensure that the OAuth 2.0 server is using or extending the classes listed in Configuring the OAuth Server. For information about how the FHIR server enforices access token scopes, see Access Token Scopes.

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

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.

Configure the FHIR server to use the name in the OAuth 2.0 client registration, as follows:
1. Navigate to Health > Foundation Namespace and click Go.
2. In the tile representing your FHIR server, open the menu and choose Edit.
3. From the OAuth Client Name dropdown, choose the client name you assigned the server.
4. Click Save.

No Authentication

While authentication is essential on a live FHIR server, being forced to provide credentials to the FHIR server during development and testing can be cumbersome. You can allow FHIR requests with no authentication credentials to reach the server.

Note:

Allow Unauthenticated Access allows FHIR requests with no authentication credentials at all to reach the server. If Allow Unauthenticated Access is enabled and a request comes in with invalid Basic authentication or an invalid bearer token, it is still rejected. If Allow Unauthenticated Access is enabled and a request comes in with valid Basic authentication but the username does not have a Required Resource that has been defined by the server, the request is still rejected.

To allow unauthenticated access:

In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.
Select the endpoint of the FHIR server.
Select Edit.
Select the Allow Unauthenticated Access check box in the Debugging section.
Select Update.

FHIR Server Debugging

FHIRPath