Skip to main content

Authentication

Introduction​

This document describes the available authentication options for the Helios FHIR Server.

There are three ways to configure these configuration settings.

  • Manually modify the $KARAF_HOME/etc/authentication.properties.cfg file prior to, or after startup.
  • Use the Helios FHIR Server administrative user interface (Default - http://localhost:8181/ui), Settings menu to view or modify these values. Changes to these values in the administrative user interface will overwrite the values in authentication.properties.cfg.
  • Use environment variables to override the authentication.properties.cfg values. This approach is helpful when you need to pass configuration values to a Docker container or otherwise do not wish to modify the values in the authentication.properties.cfg file.

Each setting section below lists two values.

  • The first is the authentication.properties.cfg value, and
  • the second is the same value expressed as an environment variable.

No Authentication​

By default, the Helios FHIR Server is configured without authentication. While this is convenient for getting up and running quickly, you should never run a production FHIR Server without configuring one of the authentication options below.

Basic Authentication​

In HTTP Basic Access Authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where credentials is the Base64 encoding of ID and password joined by a single colon :.

Basic Authentication involves the transmission of credentials in each request. It must always be used in combination with TLS/HTTPS.

To enable Basic Authentication for the Helios FHIR Server, first make sure you have configured a user using the Administrative User Interface.

Basic Enabled​

Set to true to enable Basic Authentication, false to disable.

basicEnabled = false
AUTHENTICATION_PROPERTIES_BASICENABLED = false

CORS Origins​

A comma separated list of allowed origins, e.g. http://example.org Use the wildcard character * to allow all domains, which is the default setting. Permitting all domains is not recommended for production systems.

corsOrigins = *
AUTHENTICATION_PROPERTIES_CORSORIGINS = *

Whitelisted HTTP Methods​

A comma separated list of HTTP operations listed below, or NONE that are permitted even if Basic Authentication is enabled. Using this setting, if set to GET, a Helios FHIR Server will offer an open, read-only FHIR Server, but POST, PUT and DELETE operations will be secured using Basic Authentication.

  • GET
  • POST
  • PUT
  • DELETE
  • NONE
whiteListedMethods = NONE
AUTHENTICATION_PROPERTIES_WHITELISTEDMETHODS = NONE

Open Authentication (OAuth)​

OAuth Enabled​

Set to true to enable SMART’s client-confidential-asymmetric authentication/OAuth Authentication, false to disable.

If oauthEnabled is changed to true, oauthInitialAccessToken MUST also be set to a non-null value.

oauthEnabled = false
AUTHENTICATION_PROPERTIES_OAUTHENABLED = false

OAuth Initial Access Token​

This property is used in the OAuth 2.0 Dynamic Client Registration Management Protocol. The client is issued this initial access token for use with the OAuth client registration endpoint. localhost:8181/fhir/oauth/register

Although the specification indicates that the initial access token is optional, the Helios FHIR Server requires an initial access token when using the Dynamic Client Registration Management Protocol.

Set to null by default, this setting effectively disables the Dynamic Client Registration Management Protocol. To enable it, set this property and communicate it to the clients that wish to dynamically register OAuth clients.

This value must be set in the Authorization header with a Bearer prefix. For example, if this value is set to 12345, clients must set the Authorization header to Bearer 12345

oauthInitialAccessToken =
AUTHENTICATION_PROPERTIES_OAUTHINITIALACCESSTOKEN =

Keystore Password​

The password to access the $KARAF_ROOT/etc/helios-keystore.jks file. You should change this value for production systems. See Post Installation Steps.

After changing this setting, perform a complete server restart
keystorePassword = changeit
AUTHENTICATION_PROPERTIES_KEYSTOREPASSWORD = changeit

Keystore Alias​

The alias of the signing key stored in the $KARAF_ROOT/etc/helios-keystore.jks file. Change this value for production systems. See Post Installation Steps.

After changing this setting, perform a complete server restart
keystoreAlias = helios
AUTHENTICATION_PROPERTIES_KEYSTOREALIAS = helios

Block Unsecure Requests​

Set to false by default, this value will cause an exception to be thrown (and processing will stop) if a request is received using HTTP instead of HTTPS. Set this value to true for production systems after you have installed your TLS/HTTPS encryption certificate to ensure that all traffic is encrypted.

blockUnsecureRequests = false
AUTHENTICATION_PROPERTIES_BLOCKUNSECUREREQUESTS = false