.. _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 `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

    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

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