Security Configuration

Ontoserver offers several configuration options relating to secured access to its APIs.

For details on configuring Ontoserver to act as a trusted client for upstream Syndication servers, see Syndication Configuration.

RBAC in Ontoserver

Ontoserver can be configured to enforce role-based access control (RBAC) itself.

Ontoserver provides three endpoint families: api (Admin), fhir (FHIR), and synd (Syndication). Within each of these familes there are two role types: READ and WRITE, corresponding to whether the operation can change the state of the server (WRITE) or not (READ). Details regarding authorization server setup are provided below.

ontoserver.security.enabled (false)

If true, enables role-based security on the various Ontoserver API families. Each of the api, fhir, and synd endpoints has separate READ and WRITE roles.

ontoserver.security.token.secret

The secret signing key for the JWT tokens that allows Ontoserver to trust the tokens produced by your authorization server.

When configuring Ontoserver to work with an authorization server, this parameter should be the shared key (using HS256 shared secret/symmetric key). Since version 5.5 of Ontoserver, an asymmetric (RS256 public-private) key is supported, although not recommended due to potential performance degradation.

Note, if used, RS256 keys should be in OpenSSH format, as produced by ssh-keygen, and including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- markers.

ontoserver.security.readOnly.api (false)

If true, and role-based security is enabled, then all users (including unauthenticated users) get minimum of READ access to the api endpoint.

ontoserver.security.readOnly.fhir (false)

If true, and role-based security is enabled, then all users (including unauthenticated users) get minimum of READ access to the fhir endpoint.

ontoserver.security.readOnly.synd (false)

If true, and role-based security is enabled, then all users (including unauthenticated users) get minimum of READ access to the synd endpoint.

Advertising security details

The FHIR Conformance Resource is used to advertise security related information and this can be configured through the following properties:

conformance.security.description

Allows you to provide a general description of how security works for inclusion in the Conformance.security.description element.

conformance.security.kinds

is a comma-separated list of codes drawn from the ValueSet https://www.hl7.org/fhir/STU3/valueset-restful-security-service.html. Only the codes Basic and SMART-on-FHIR are currently supported.

conformance.security.authorize

is a URL indicating the OAuth 2 "authorize" endpoint. This is required if conformance.security.kinds contains SMART-on-FHIR

conformance.security.token

is a URL indicating the OAuth2 "token" endpoint. This is required if conformance.security.kinds contains SMART-on-FHIR

More details about SMART-on-FHIR are available at http://docs.smarthealthit.org/authorization/conformance-statement/.

Authorization server setup details

To support RBAC, appropriate claims have to be provided in the JWT token that is returned by the authorization server. These claims SHOULD be provided in the scope field, which is an array containing zero or more of:

  • system/*.read
  • system/*.write
  • onto/api.read
  • onto/api.write
  • onto/synd.read
  • onto/synd.write

    Strictly for backwards compatibility purposes, these claims CAN alternatively be provided in the authorities field, which is an array containing zero or more of:

  • FHIR_READ
  • FHIR_WRITE
  • API_READ
  • API_WRITE
  • SYND_READ
  • SYND_WRITE

SSL/TLS support

Ontoserver can use a secure HTTPS connector (this is the default) or a plain HTTP connector (this can be configured by setting the ONTOSERVER_INSECURE variable to true).

The HTTPS connector can be configured by adding the following properties:

server.ssl.key-store (/keystore.p12)

Path to the key store that holds the SSL certificate (typically a p12 or jks file). For example: classpath:ontoserverkeystore.p12.

server.ssl.key-store-password

Password used to access the key store.

server.ssl.keyStoreType (PKCS12)

Type of the key store. For example, PKCS12. Other possible values include JKS, PKCS11 and JCEKS.

server.ssl.keyAlias (ontoserver)

Alias that identifies the key in the key store. For example, ontoserver.

server.ssl.key-password

Password used to access the key within the key store.

Furthermore, HTTP Strict Transport Security (HSTS) is enabled by default for HTTPS. It can be disabled with:

ontoserver.security.hsts (true)

If false, then the Strict-Transport-Security header will not be sent for HTTPS responses.