Skip to main content

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. If both forms of authentication are provided in the same request, both must be valid for the request to succeed.

During development and debugging, you can temporarily disable all security restrictions.

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.

  1. 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.

  2. 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.

  3. 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.

  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 the Server

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

  1. In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.

  2. Select the endpoint of the FHIR server.

  3. Select Edit.

  4. In the Required Resource field, enter the name of the security resource that controls access to the FHIR server.

  5. Select Update.

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 request 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. For a default FHIR server, this token handling class is HS.FHIRServer.Util.OAuth2TokenOpens in a new tab.

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.

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

  1. In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.

  2. Select the endpoint of the FHIR server.

  3. Select Edit.

  4. In the OAuth Client Name field, enter the Application Name of the resource server as defined in the Management Portal.

  5. Select Update.

Access Token Scopes


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


When a FHIR interaction is authorized by patient or user 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/, then a client can access an Organization referenced by the Patient without having a scope patient/

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.


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.

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 all FHIR requests to reach the server, temporarily ignoring authentication and authorization strategies. To allow unauthenticated access:

  1. In the Management Portal, navigate to Health > FHIR Configuration > Server Configuration. Make sure you are in the FHIR server’s namespace.

  2. Select the endpoint of the FHIR server.

  3. Select Edit.

  4. Select the Allow Unauthenticated Access check box in the Debugging section.

  5. Select Update.

FeedbackOpens in a new tab