FHIR Server Security

Important:

This is prerelease documentation. The features described are subject to change and may not yet be available for use.

You can control which clients can make requests to the FHIR server and the interactions they can perform using the following:

OAuth 2.0

Using OAuth 2.0 with a FHIR Server

You can set up your FHIR server as an OAuth 2.0 resource server. This allows the FHIR server to reject a client FHIR request unless the client presents 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 reaches 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.

From the point of view of an OAuth authorization server, a FHIR resource server is a client. You can use the OAuth FHIR Client Quickstart in the Management Portal to connect your FHIR resource server to any OAuth 2.0 authorization server, as follows:

Prerequisites:

If you have not already done so, you must configure the Network Host Name before executing these steps.

Instructions:

Click OAuth FHIR Client Quickstart in the left-hand navigation bar.
Choose whether to use an existing FHIR server or to create a new one, by clicking the tile that matches your choice, then click Next.
Identify the desired FHIR server by doing one of the following:
- If you chose to create a new FHIR server, complete the Create New FHIR Server form. For field help, see Installing a FHIR Server. Then click Next.
- If you chose to use an existing FHIR server, choose the desired Namespace and FHIR server URL from the dropdowns in the Use an Existing FHIR Server form, then click Next.
Connect your selected FHIR server to an OAuth server by clicking the tile that matches your choice, then click Next.
Enter the issuer endpoint, then click Test. The system now tests to see whether the issuer endpoint is discoverable. This verifies the identity of the issuer endpoint as an OAuth 2.0 server. When the test has succeeded and the Next button appears, click Next.
Review the selections you have made. To confirm your selections, click Confirm.
Upon success, your OAuth server is associated with your FHIR resource server, and a list of configurations is displayed. If something goes wrong, you will instead see a list of the errors that occurred. You can use the Back button and edit configuration choices to eliminate errors.

Creating and Editing Credentials

If your production uses HTTP Credential ID or X-API Key Credential to authenticate between the OAuth server and a FHIR service such as Bulk FHIR, you will need appropriate credentials. You can set these up as follows:

In the FHIR service, choose the Security Config icon from the left-hand menu, then choose Credentials.
From the drop-down menu, choose the namespace in which you wish to manage credentials.

Note:

If you do not see your desired namespace in the list, you may require additional permissions. You must have read permission for the database associated with a namespace to see that namespace in the list.
To create a new set of credentials, click New, and specify Name, Username, and Password.
To save the new credentials, click Save. To cancel, click Cancel.

The process to edit an existing set of credentials is similar, but instead of clicking New, you will click the Edit icon associated with the credentials you wish to modify.

Note:

When editing a set of credentials, you cannot edit the Name field. If this field is incorrect, you can delete the credentials by clicking the associated Delete icon, then create new credentials with the correct name.

Access Token Scopes and FHIR

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.

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.

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 scope (system, patient resource, or user resource), 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 resource and patient resource 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:

The query parameters _include and _revinclude 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.

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 the FHIR server enforces access token scopes, see Access Token Scopes.

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

client definition that registers your FHIR server as a resource server to your OAuth 2.0 server as described in Configuring OAuth Clients for the Bulk FHIR Coordinator. Be sure to specify the following for your FHIR server’s client configuration:

Issuer Endpoint	Choose the issuer endpoint from the dropdown.
Client 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.
TLS configuration	From this dropdown, select the same SSL option you selected previously.
Auth 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. Open your FHIR server service.
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.