Skip to main content
Previous sectionNext section

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 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 a 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 Authorization

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 the OAuth 2.0 authorization server. 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

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 subclass HS.FHIRServer.Util.OAuth2Token, and create your own Interactions and InteractionsStrategy subclasses. The Interactions class contains a parameter that points to the class that handles OAuth access tokens.

Basic Processing

The access token that accompanies a request must include at least one patient clinical scope or user clinical scope, or else the request is rejected with an HTTP 403 error. If an access token contains both a patient clinical scope and a user clinical scope, the FHIR server enforces the patient clinical scope while ignoring the user clinical scope.

Patient Clinical Scope / Patient Context Value

If an access token includes a patient clinical scope, it must also include a patient context value (also known as “launch context”) that is the id of a Patient resource. This patient context value provides access to the specified Patient and its related resources. In most cases, the patient clinical scope must provide explicit access to a related resource. For example, if the patient context value is 1234, and the patient clinical scope is patient/Observation.*, the FHIR server can grant access to an Observation that references the Patient with the id 1234. In this case, patient/Observation.* (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 clinical scope that is specific to that resource. For example, if the scope is patient/Patient.read, then a client can access an Organization referenced by the Patient without having a scope patient/Organization.read.

When an access token includes a patient context value, it must also include a patient clinical scope, or else the request is rejected with a HTTP 403 error.

To obtain the patient context value from the access token, the FHIR server examines two locations, in the following order:

  • Third non-blank piece of a launch/patient/ scope.

  • patient property of access token.

Search

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

    • For a Patient search, the search must be by _id only, and the _id value must match the patient context value.

    • For a Patient compartment search, the resource id of the compartment must match the patient context value.

Create Interaction

Requests to create a new Patient resource must include a user clinical scope that gives write permissions (user/Patient.write or user/Patient.*). You cannot perform a create interaction for a Patient resource with a patient clinical scope; patient clinical scopes must include a patient context value, and the create 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 resources. If the access token is using a patient clinical scope, it must have a patient/*.read or patient/*.* scope. If the access token is using a user clinical scope, it must have a user/*.read or user/*.* scope.

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.

Feedback