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 security, see the Security Administration Guide.

  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 Creating or Editing 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 Creating 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 Giving 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 Assigning 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. From the InterSystems Terminal, change to the FHIR server’s namespace. For example:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard
  2. Run the installation and configuration utility:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  3. Choose option 3) Configure a FHIRServer Endpoint.

  4. Choose the endpoint of the FHIR server that you are configuring.

  5. Accept the default configuration options until you get to the RequiredResource: prompt.

  6. At the RequiredResource: prompt, enter the name of the security resource that controls access to the FHIR server.

  7. Continue with the prompts and save your changes.

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. From the InterSystems Terminal, change to the FHIR server’s namespace. For example:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard
  2. Run the installation and configuration utility:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  3. Choose option 3) Configure a FHIRServer Endpoint.

  4. Choose the endpoint of the FHIR server that you are configuring.

  5. Accept the default configuration options until you get to the OAuthClientName: prompt.

  6. At the OAuthClientName: prompt, enter the Application Name of the resource server as defined in the Management Portal.

  7. Continue with the prompts and save your changes.

Caution:

The default FHIR server does not respect the scopes passed in an OAuth access token; by default, these scopes are ignored. InterSystems strongly recommends that you use InterSystems IRIS for Health to create an application or use an API management tool, such as InterSystems API Manager, that enforces scopes consistent with the FHIR standard to provide resource-based and identity-based access control. Failing to write custom code or implement another mechanism to handle scopes can result in privacy violations where FHIR clients can access or perform functions on data beyond or inconsistent with the scope that was specified in the access token.

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. By setting the server’s DebugMode configuration to 4, you can allow all FHIR requests to reach the server, temporarily ignoring authentication and authorization strategies. For more information about setting the DebugMode to allow unauthenticated requests, see Debug Mode.