Authentication

OpenFHIR provides built-in support for securing its RESTful APIs using Keycloak as an OAuth2 identity provider. This allows fine-grained access control via JWT-based authentication.

Enabling Authentication with Keycloak

To protect your OpenFHIR instance using Keycloak, set the openfhir.protected flag in your configuration and provide standard Spring Security OAuth2 settings.

Configuration

Add the following configuration in your application.yml or application.properties:

openfhir:
  protected: true

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://keycloak/realms/open-fhir
          jwk-set-uri: http://keycloak/realms/open-fhir/protocol/openid-connect/certs

Alternatively, if using application.properties:

openfhir.protected=true

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://keycloak/realms/open-fhir
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=http://keycloak/realms/open-fhir/protocol/openid-connect/certs

How it works

  • Protected Mode: When openfhir.protected: true, OpenFHIR enforces authentication for all API requests.

  • JWT-Based Authentication: OpenFHIR validates JWTs issued by Keycloak, ensuring only authorized users with correct scopes can access resources.

  • Authorization Headers: Clients must send a valid Bearer Token in the Authorization header when making API requests.

Scopes

Scopes

Scope

Description

Protected API

fc.(c,r,u,d)

FHIR Connect APIs used for state configuration

are protected with (c)reate, (r)ead, (u)pdate,

(d)elete scopes (i.e. fc.c means a create is allowed, ..)

/fc/model, /fc/context

opt.(c,r,u,d)

API through which one is able to create an operational

template

/opt

openfhir.map

granting access to mapping API

/openfhir/tofhir, /openfhir/toopenehr

conceptmap.(c,r,u,d)

granting access to /fhir/ConceptMap

/terminology/fhir/ConceptMap

fhirpackage.(c,r,d)

granting access to the FHIR IG npm package store

(upload, list/download, delete); re-uploading the

same name and version is also a create (c)

/fhir/packages

versioning.(r,w)

git versioning: (r)ead settings, status, journal,

diffs, blame, releases and reviews; (w)rite settings,

connect, push, checkpoint, releases and reviews.

Restores and other operations that change the engine

state also need the fc, opt and conceptmap scopes

/versioning

Note

GET /$export needs fc.r, opt.r and conceptmap.r (plus fhirpackage.r with includePackages and versioning.r with ref). POST /$import needs the c and u scopes of fc, opt and conceptmap, their d scopes as well for mode=mirror, and fhirpackage.c with importPackages. See Versioning (git).