.. _authentication:

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`:

.. code-block:: bash

    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:

.. code-block:: bash

    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
^^^^^^
.. list-table:: Scopes
   :widths: 20 50 25
   :header-rows: 1

   * - 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
    :doc:`versioning`.