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:
-
Click Add in the Privileges section of the role’s General tab.
-
Select the resource that will control server authorization, and click OK.
-
Click Edit next to the new Privilege.
-
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.
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.
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.
You can use the OAuth FHIR Client Quickstart to connect the FHIR resource server and the 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.
-
If you wish to use an internal OAuth server, you must first set up secure communication. For details, see Setting Up Secure Communication for a Foundation Production.
Instructions:
-
In the Management Portal, navigate to Health > [foundation namespace] > FHIR Server Management, then 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 and Configuring a FHIR Server. Then click Next.
-
If you chose to use an existing FHIR server, choose the desired namespace and 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. You can choose whether to use an external OAuth server or (if you have set up secure communication) an internal OAuth server by clicking the tile that matches your choice, then click Next.
-
If you chose to use an external OAuth server, 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.
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 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.
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.
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.
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.
-
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.
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()
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 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.
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:
-
Navigate to Health > Foundation Namespace and click Go.
-
In the tile representing your FHIR server, open the menu and choose Edit.
-
From the OAuth Client Name dropdown, choose the client name you assigned the server.
-
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.
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.