Leadership advocacy, structured training, and local champions within teams are the fundamental components of a pragmatic Generative AI adoption strategy.

Leadership advocacy: Lead from the front, supporting and promoting the adoption of Generative AI.

Structured training: What is Generative AI and what can it do for me?

Local champions: Team members who champion the role of Generative AI tools in the SDLC.

Resources

• AWS docs: What is Generative AI?
• Google blog: Ask a Techspert: What is generative AI?
• coursera: Introduction to Generative AI
• Angular dev: Build with AI
• GitHub: Awesome Spring AI
• PAIR blog: AI Explorables

Introduction

Open Policy Agent is a general-purpose policy engine that includes a high-level declarative language that you can use to define policies.

Getting Started

The easiest way to get started with Open Policy Agent (OPA) is to use Docker Compose.

Docker Compose

I created a Docker Compose configuration file, as follows:

  opa:
    image: openpolicyagent/opa:1.6.0-static
    command:
      - "run"
      - "--server"
      - "--addr=0.0.0.0:8181"
      - "--log-level=info"
      - "--log-format=json-pretty"
    restart: unless-stopped
    ports:
      - 8181:8181

Policy Definition

OPA uses a declarative language called Rego to define policies.

For example:

package organization.read

methods := "GET HEAD"

default allow := false

allow if contains(methods, input.request.method)

You can use Rego to specify rules for authorisation and other security aspects of your application.

Loading Policies and Data

The simplest way to load policies and data into OPA is to provide them via the file system (i.e., Docker volumes) and command line arguments.

Let's update our Docker Compose configuration file, as follows:

  opa:
    image: openpolicyagent/opa:1.6.0-static
    command:
      - "run"
      - "--server"
      - "/policies/organization-read.rego"
      - "/policies/organization-write.rego"
      - "--addr=0.0.0.0:8181"
      - "--log-level=info"
      - "--log-format=json-pretty"
    restart: unless-stopped
    ports:
      - 8181:8181
    volumes:
      - '${PWD}/services/opa/conf/policies:/policies'

Policy Evaluation

OPA can act as a policy decision point in combination with an API Gateway (e.g., APISIX) acting as a policy enforcement point.

When an application requests access to a resource (using standard HTTP methods like GET, HEAD, POST, PUT, PATCH and DELETE), the request is intercepted by the API Gateway and routed to OPA.

For example:

  - name: provider-directory-api-organization-read
    uri: /fhir/Organization*
    methods: [ "GET", "HEAD" ]
    upstream_id: 1
    plugins:
      opa:
        host: "https://opa:8282"
        policy: "organization/read"

  - name: provider-directory-api-organization-write
    uri: /fhir/Organization*
    methods: [ "POST", "PUT", "PATCH", "DELETE" ]
    upstream_id: 1
    plugins:
      opa:
        host: "https://opa:8282"
        policy: "organization/write"

OPA evaluates the (access control) policy and decides if the request should be 'allowed' or 'denied'.

You can obtain additional information about OPA decisions by setting your log level to 'debug' and including the decision logs:

  opa:
    image: openpolicyagent/opa:1.6.0-static
    command:
    
      ...
      
      - "--log-level=debug"
      - "--set=decision_logs.console=true"

For example:

docker container logs opa

You should see something like:

{
  "current_version": "1.6.0",
  "level": "debug",
  "msg": "OPA is up to date.",
  "time": "2025-07-18T23:00:45Z"
}
{
  "client_addr": "172.18.0.2:34608",
  "level": "info",
  "msg": "Received request.",
  "req_body": "{\"input\":{\"request\":{\"port\":9443,\"query\":{\"_id\":\"adv-hearing-care\"},\"scheme\":\"https\",\"headers\":{\"authorization\":\"Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJMOFRkd19mLTRlUDJOVmZzMUVDbDJka0ZwNmFGbi1QR2xZZWlxb0FvSkowIn0.eyJleHAiOjE3NTI4ODAwNzMsImlhdCI6MTc1Mjg3OTc3MywianRpIjoidHJydGNjOmQ5OTk3MzEzLWQwNzMtZTkxYi1jMDc0LTgxNjQ1NGFlNWQ2YyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXUubG9jYWxob3N0Ojg0NDMvcmVhbG1zL2hhcGktZmhpci1kZXYiLCJhdWQiOlsib2F1dGgyLXByb3h5IiwiYWNjb3VudCJdLCJzdWIiOiJkYTRmMDkxMi0xY2Q5LTQzMmQtOWM5ZC1hNTVkYjExMDkzZGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJvYXV0aDItcHJveHkiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtaGFwaS1maGlyLWRldiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJvYXV0aDItcHJveHkiOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBzeXN0ZW0vT3JnYW5pemF0aW9uLnJlYWQgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxNzIuMTguMC4xIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LW9hdXRoMi1wcm94eSIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC4xIiwiY2xpZW50X2lkIjoib2F1dGgyLXByb3h5In0.XAZXKtzk6lGnYYS0LcWc66MDalhWJ_p7E3-KYNse_LM9MKBgTrNqtizBdNgCeS8jgJ-366szDNv9ZvOMVgt3y-Hd2PhMMD-z93GuwcrOefcAH2Ji8ZgtgSt5VG4R7J5F_3ty1VP-Jhhq6EAMtsm1H8t-5AQjoDTaZjqZLpnVX8P-8nhkEfNZWZEILGyXWN0lcko-1lhLdIbbRYMl5cOxKM7s7FuK23G5y1JJQZRC5HWVF6Xa9zqQo-yioTpVlr2OIVE-eNA7FE17d_lDzAHQm-InNHkGEpiMcA3Wfgc-CS9slBfmIQxuU2N6Qnc1z7ZPHznAhzxcgPetCIGFjwSaTw\",\"user-agent\":\"curl/8.7.1\",\"host\":\"provider-directory.au.localhost\",\"accept\":\"*/*\",\"content-type\":\"application/fhir+json\"},\"method\":\"GET\",\"path\":\"/fhir/Organization\",\"host\":\"provider-directory.au.localhost\"},\"type\":\"http\",\"var\":{\"server_port\":\"9443\",\"remote_addr\":\"172.18.0.1\",\"timestamp\":1752879785,\"remote_port\":\"56920\",\"server_addr\":\"172.18.0.2\"}}}",
  "req_id": 2,
  "req_method": "POST",
  "req_params": {},
  "req_path": "/v1/data/organization/read",
  "time": "2025-07-18T23:03:05Z"
}
{
  "decision_id": "6ce6af4a-9ad2-4a23-ad8d-83428683ff37",
  "input": {
    "request": {
      "headers": {
        "accept": "*/*",
        "authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJMOFRkd19mLTRlUDJOVmZzMUVDbDJka0ZwNmFGbi1QR2xZZWlxb0FvSkowIn0.eyJleHAiOjE3NTI4ODAwNzMsImlhdCI6MTc1Mjg3OTc3MywianRpIjoidHJydGNjOmQ5OTk3MzEzLWQwNzMtZTkxYi1jMDc0LTgxNjQ1NGFlNWQ2YyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXUubG9jYWxob3N0Ojg0NDMvcmVhbG1zL2hhcGktZmhpci1kZXYiLCJhdWQiOlsib2F1dGgyLXByb3h5IiwiYWNjb3VudCJdLCJzdWIiOiJkYTRmMDkxMi0xY2Q5LTQzMmQtOWM5ZC1hNTVkYjExMDkzZGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJvYXV0aDItcHJveHkiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtaGFwaS1maGlyLWRldiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJvYXV0aDItcHJveHkiOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBzeXN0ZW0vT3JnYW5pemF0aW9uLnJlYWQgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxNzIuMTguMC4xIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LW9hdXRoMi1wcm94eSIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC4xIiwiY2xpZW50X2lkIjoib2F1dGgyLXByb3h5In0.XAZXKtzk6lGnYYS0LcWc66MDalhWJ_p7E3-KYNse_LM9MKBgTrNqtizBdNgCeS8jgJ-366szDNv9ZvOMVgt3y-Hd2PhMMD-z93GuwcrOefcAH2Ji8ZgtgSt5VG4R7J5F_3ty1VP-Jhhq6EAMtsm1H8t-5AQjoDTaZjqZLpnVX8P-8nhkEfNZWZEILGyXWN0lcko-1lhLdIbbRYMl5cOxKM7s7FuK23G5y1JJQZRC5HWVF6Xa9zqQo-yioTpVlr2OIVE-eNA7FE17d_lDzAHQm-InNHkGEpiMcA3Wfgc-CS9slBfmIQxuU2N6Qnc1z7ZPHznAhzxcgPetCIGFjwSaTw",
        "content-type": "application/fhir+json",
        "host": "provider-directory.au.localhost",
        "user-agent": "curl/8.7.1"
      },
      "host": "provider-directory.au.localhost",
      "method": "GET",
      "path": "/fhir/Organization",
      "port": 9443,
      "query": {
        "_id": "adv-hearing-care"
      },
      "scheme": "https"
    },
    "type": "http",
    "var": {
      "remote_addr": "172.18.0.1",
      "remote_port": "56920",
      "server_addr": "172.18.0.2",
      "server_port": "9443",
      "timestamp": 1752879785
    }
  },
  "labels": {
    "id": "5db6ed80-30b9-42f1-a151-b8b63ca504e5",
    "version": "1.6.0"
  },
  "level": "info",
  "metrics": {
    "counter_server_query_cache_hit": 0,
    "timer_rego_external_resolve_ns": 459,
    "timer_rego_input_parse_ns": 1074000,
    "timer_rego_query_compile_ns": 337042,
    "timer_rego_query_eval_ns": 1389209,
    "timer_server_handler_ns": 3634125
  },
  "msg": "Decision Log",
  "path": "organization/read",
  "req_id": 2,
  "requested_by": "172.18.0.2:34608",
  "result": {
    "allow": true,
    "bearer_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJMOFRkd19mLTRlUDJOVmZzMUVDbDJka0ZwNmFGbi1QR2xZZWlxb0FvSkowIn0.eyJleHAiOjE3NTI4ODAwNzMsImlhdCI6MTc1Mjg3OTc3MywianRpIjoidHJydGNjOmQ5OTk3MzEzLWQwNzMtZTkxYi1jMDc0LTgxNjQ1NGFlNWQ2YyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXUubG9jYWxob3N0Ojg0NDMvcmVhbG1zL2hhcGktZmhpci1kZXYiLCJhdWQiOlsib2F1dGgyLXByb3h5IiwiYWNjb3VudCJdLCJzdWIiOiJkYTRmMDkxMi0xY2Q5LTQzMmQtOWM5ZC1hNTVkYjExMDkzZGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJvYXV0aDItcHJveHkiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtaGFwaS1maGlyLWRldiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJvYXV0aDItcHJveHkiOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBzeXN0ZW0vT3JnYW5pemF0aW9uLnJlYWQgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxNzIuMTguMC4xIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LW9hdXRoMi1wcm94eSIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC4xIiwiY2xpZW50X2lkIjoib2F1dGgyLXByb3h5In0.XAZXKtzk6lGnYYS0LcWc66MDalhWJ_p7E3-KYNse_LM9MKBgTrNqtizBdNgCeS8jgJ-366szDNv9ZvOMVgt3y-Hd2PhMMD-z93GuwcrOefcAH2Ji8ZgtgSt5VG4R7J5F_3ty1VP-Jhhq6EAMtsm1H8t-5AQjoDTaZjqZLpnVX8P-8nhkEfNZWZEILGyXWN0lcko-1lhLdIbbRYMl5cOxKM7s7FuK23G5y1JJQZRC5HWVF6Xa9zqQo-yioTpVlr2OIVE-eNA7FE17d_lDzAHQm-InNHkGEpiMcA3Wfgc-CS9slBfmIQxuU2N6Qnc1z7ZPHznAhzxcgPetCIGFjwSaTw",
    "is_client": true,
    "is_method": true,
    "is_request_path": true,
    "is_scope": true,
    "methods": "GET HEAD",
    "path": "/fhir/Organization",
    "scope": "system/Organization.read",
    "token": {
      "acr": "1",
      "allowed-origins": [
        "*"
      ],
      "aud": [
        "oauth2-proxy",
        "account"
      ],
      "azp": "oauth2-proxy",
      "clientAddress": "172.18.0.1",
      "clientHost": "172.18.0.1",
      "client_id": "oauth2-proxy",
      "email_verified": false,
      "exp": 1752880073,
      "iat": 1752879773,
      "iss": "https://keycloak.au.localhost:8443/realms/hapi-fhir-dev",
      "jti": "trrtcc:d9997313-d073-e91b-c074-816454ae5d6c",
      "preferred_username": "service-account-oauth2-proxy",
      "realm_access": {
        "roles": [
          "default-roles-hapi-fhir-dev",
          "offline_access",
          "uma_authorization"
        ]
      },
      "resource_access": {
        "account": {
          "roles": [
            "manage-account",
            "manage-account-links",
            "view-profile"
          ]
        },
        "oauth2-proxy": {
          "roles": [
            "uma_protection"
          ]
        }
      },
      "scope": "profile system/Organization.read email",
      "sub": "da4f0912-1cd9-432d-9c9d-a55db11093de",
      "typ": "Bearer"
    }
  },
  "time": "2025-07-18T23:03:05Z",
  "timestamp": "2025-07-18T23:03:05.314506801Z",
  "type": "openpolicyagent.org/decision_logs"
}
{
  "client_addr": "172.18.0.2:34608",
  "level": "info",
  "msg": "Sent response.",
  "req_id": 2,
  "req_method": "POST",
  "req_path": "/v1/data/organization/read",
  "resp_body": "{\"decision_id\":\"6ce6af4a-9ad2-4a23-ad8d-83428683ff37\",\"result\":{\"allow\":true,\"bearer_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJMOFRkd19mLTRlUDJOVmZzMUVDbDJka0ZwNmFGbi1QR2xZZWlxb0FvSkowIn0.eyJleHAiOjE3NTI4ODAwNzMsImlhdCI6MTc1Mjg3OTc3MywianRpIjoidHJydGNjOmQ5OTk3MzEzLWQwNzMtZTkxYi1jMDc0LTgxNjQ1NGFlNWQ2YyIsImlzcyI6Imh0dHBzOi8va2V5Y2xvYWsuYXUubG9jYWxob3N0Ojg0NDMvcmVhbG1zL2hhcGktZmhpci1kZXYiLCJhdWQiOlsib2F1dGgyLXByb3h5IiwiYWNjb3VudCJdLCJzdWIiOiJkYTRmMDkxMi0xY2Q5LTQzMmQtOWM5ZC1hNTVkYjExMDkzZGUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJvYXV0aDItcHJveHkiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtaGFwaS1maGlyLWRldiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJvYXV0aDItcHJveHkiOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBzeXN0ZW0vT3JnYW5pemF0aW9uLnJlYWQgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxNzIuMTguMC4xIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LW9hdXRoMi1wcm94eSIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTguMC4xIiwiY2xpZW50X2lkIjoib2F1dGgyLXByb3h5In0.XAZXKtzk6lGnYYS0LcWc66MDalhWJ_p7E3-KYNse_LM9MKBgTrNqtizBdNgCeS8jgJ-366szDNv9ZvOMVgt3y-Hd2PhMMD-z93GuwcrOefcAH2Ji8ZgtgSt5VG4R7J5F_3ty1VP-Jhhq6EAMtsm1H8t-5AQjoDTaZjqZLpnVX8P-8nhkEfNZWZEILGyXWN0lcko-1lhLdIbbRYMl5cOxKM7s7FuK23G5y1JJQZRC5HWVF6Xa9zqQo-yioTpVlr2OIVE-eNA7FE17d_lDzAHQm-InNHkGEpiMcA3Wfgc-CS9slBfmIQxuU2N6Qnc1z7ZPHznAhzxcgPetCIGFjwSaTw\",\"is_client\":true,\"is_method\":true,\"is_request_path\":true,\"is_scope\":true,\"methods\":\"GET HEAD\",\"path\":\"/fhir/Organization\",\"scope\":\"system/Organization.read\",\"token\":{\"acr\":\"1\",\"allowed-origins\":[\"*\"],\"aud\":[\"oauth2-proxy\",\"account\"],\"azp\":\"oauth2-proxy\",\"clientAddress\":\"172.18.0.1\",\"clientHost\":\"172.18.0.1\",\"client_id\":\"oauth2-proxy\",\"email_verified\":false,\"exp\":1752880073,\"iat\":1752879773,\"iss\":\"https://keycloak.au.localhost:8443/realms/hapi-fhir-dev\",\"jti\":\"trrtcc:d9997313-d073-e91b-c074-816454ae5d6c\",\"preferred_username\":\"service-account-oauth2-proxy\",\"realm_access\":{\"roles\":[\"default-roles-hapi-fhir-dev\",\"offline_access\",\"uma_authorization\"]},\"resource_access\":{\"account\":{\"roles\":[\"manage-account\",\"manage-account-links\",\"view-profile\"]},\"oauth2-proxy\":{\"roles\":[\"uma_protection\"]}},\"scope\":\"profile system/Organization.read email\",\"sub\":\"da4f0912-1cd9-432d-9c9d-a55db11093de\",\"typ\":\"Bearer\"}}}\n",
  "resp_bytes": 2445,
  "resp_duration": 8.023,
  "resp_status": 200,
  "time": "2025-07-18T23:03:05Z"
}

Source Code

• GitHub: Australian Healthcare Provider Directory Starter Project

References

OAuth 2.0

• IETF: The OAuth 2.0 Authorization Framework
• IETF: OAuth 2.0 Token Exchange
• IETF: The OAuth 2.0 Authorization Framework: Bearer Token Usage
• IETF: Resource Indicators for OAuth 2.0
• IETF: JSON Web Token (JWT)
• IETF: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
• IETF: OAuth 2.0 Dynamic Client Registration Protocol
• IETF: OAuth 2.0 for Browser-Based Applications
• Spring docs: Implementation Guidelines for Browser-Based Applications

Open Policy Agent

• Open Policy Agent docs: Introduction
• Styra docs: Rego Style Guide
• GitHub: Awesome OPA - A curated list of awesome OPA-related tools, frameworks and articles
• Open Policy Agent: Playground
• Styra Academy courses: OPA Policy Authoring
• Open Policy Agent: Ecosystem

Introduction

Open Policy Agent (OPA) is a general-purpose policy engine that includes a high-level declarative language that you can use to define access control policies, enabling fine-grained access control in applications that leverage SMART on FHIR for authorisation and FHIR for data exchange.

SMART on FHIR

Let's take a look at how OPA can be used to support SMART on FHIR authorisation.

Policy Definition

OPA uses a declarative language called Rego to define policies. Rego allows you to specify rules for authorisation and other security aspects of your SMART on FHIR application.

For example, you could define a policy that uses request attributes (e.g., method and path), data elements in a Bearer Token (e.g., scope) and other constraints:

package organization.read

methods := "GET HEAD"
path := "/fhir/Organization"
scope := "system/Organization.read"

default allow := false

allow if {
    is_method
    is_request_path
    is_scope
}

is_method if contains(methods, input.request.method)
is_request_path if input.request.path == path
is_scope if contains(token.scope, scope)

bearer_token := t if {
    v := input.request.headers.authorization
    startswith(v, "Bearer ")
    t := substring(v, count("Bearer "), -1)
}

token := payload if {
    [_, payload, _] := io.jwt.decode(bearer_token)
}

See: organization-read.rego

Policy Evaluation

OPA can act as a policy decision point in combination with an API Gateway acting as a policy enforcement point.

When a SMART on FHIR application requests access to a FHIR resource (using standard HTTP methods like GET, HEAD, POST, PUT, PATCH and DELETE), the request is intercepted by the API Gateway and routed to OPA.

For example:

  - name: provider-directory-api-organization-read
    uri: /fhir/Organization*
    methods: [ "GET", "HEAD" ]
    upstream_id: 1
    plugins:
      opa:
        host: "https://opa:8282"
        policy: "organization/read"

  - name: provider-directory-api-organization-write
    uri: /fhir/Organization*
    methods: [ "POST", "PUT", "PATCH", "DELETE" ]
    upstream_id: 1
    plugins:
      opa:
        host: "https://opa:8282"
        policy: "organization/write"

See: api-gateway-configuration.yml

OPA evaluates the (access control) policy and decides if the request should be 'allowed' or 'denied'.

Benefits of using Open Policy Agent

Fine-grained Access Control

OPA enables granular control over FHIR resource access, allowing you to specify exactly which FHIR resources an application can access and under what conditions.

Centralised Policy Management

OPA provides a central point for managing and enforcing policies, making it easier to maintain a consistent approach to access control across your application portfolio.

Improved Security

By decoupling policy enforcement from application logic, OPA helps reduce the risk of vulnerabilities and improves the overall security posture of your organisation.

Auditability

OPA policies are code, making them version-controlled and auditable.

Flexibility and Extensibility

OPA's Rego language is flexible and extensible, allowing you to define complex access control rules based on your specific needs.

Example Use Case

Imagine a SMART on FHIR application that needs to access a patient's medication information.

Using OPA, you could define a policy that allows access to medication information only if the application is launched by a clinician and if the patient has consented to data sharing.

When the application requests access to medication data, OPA would evaluate the request against the defined policy. If the conditions are met, OPA would grant access, otherwise, access would be denied.

In essence, OPA provides a powerful way to enhance the security and flexibility of SMART on FHIR applications by enabling fine-grained, policy-based access control, making it a valuable tool for organisations looking to leverage the benefits of both SMART on FHIR and a general-purpose policy engine.

Source Code

• GitHub: Australian Healthcare Provider Directory Starter Project

References

OAuth 2.0

• IETF: The OAuth 2.0 Authorization Framework
• IETF: OAuth 2.0 Token Exchange
• IETF: The OAuth 2.0 Authorization Framework: Bearer Token Usage
• IETF: Resource Indicators for OAuth 2.0
• IETF: JSON Web Token (JWT)
• IETF: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
• IETF: OAuth 2.0 Dynamic Client Registration Protocol
• IETF: OAuth 2.0 for Browser-Based Applications
• Spring docs: Implementation Guidelines for Browser-Based Applications

HL7

• HL7: Implementation Guide
• HL7: FHIR NPM Packages
• AU Core: Publication (Version) History
• AU Core FHIR Implementation Guide: AU Core - 1.0.0-preview
• AU Core FHIR Implementation Guide: Testing FAQs
• Sparked AU Core Test Data: Postman collection
• HL7 AU: Australian Provider Directory Implementation Guide

SMART on FHIR

• HL7: SMART App Launch
• SMART Health IT: SMART on FHIR

SMART on FHIR - Standalone Launch

• Project Alvearie: SMART App Launch
• Project Alvearie: Keycloak extensions for FHIR
• Keycloak extensions for FHIR: Upgrade to the Quarkus-based distribution
• Keycloak discussion: Fine grained scope consent management

SMART on FHIR - EHR Launch

• GitHub: Zedwerks - Keycloak extensions for FHIR

Keycloak

• Keycloak docs: Configuring Keycloak for production
• Keycloak docs: Configuring TLS
• Keycloak docs: Configuring trusted certificates
• Keycloak docs: Configuring the hostname
• Keycloak docs: Using a reverse proxy
• Keycloak docs: Running Keycloak in a container
• Keycloak docs: Migrating to the Quarkus distribution
• Keycloak docs: Upgrading Guide - 26.1.0
• Keycloak docs: Authorization Services Guide

Keycloak-based Development

• GitHub: Keycloak Project Example
• GitHub: Awesome Keycloak

Keycloak Support

• Google Group: Keycloak User
• Google Group: Keycloak Dev

APISIX

• APISIX docs: Deployment modes
• APISIX docs: SSL Protocol
• APISIX docs: Certificate
• APISIX docs: Plugins - OpenID Connect

Open Policy Agent

• Open Policy Agent docs: Introduction
• Styra docs: Rego Style Guide
• GitHub: Awesome OPA - A curated list of awesome OPA-related tools, frameworks and articles
• Open Policy Agent: Playground
• Styra Academy courses: OPA Policy Authoring
• Open Policy Agent: Ecosystem

Provider Directory

• HAPI FHIR: Website
• HAPI FHIR: Documentation
• Google Group: HAPI FHIR

Introduction

In the Australian context, a healthcare provider can be defined as an individual or organisation involved in the delivery of healthcare services.

This broad definition encompasses a range of individuals, including doctors, nurses, and other health professionals, as well as organisations like hospitals, clinics, and aged care facilities.

Individual Healthcare Providers

These are individuals who provide, have provided, or are intending to provide healthcare services. This includes registered health professionals such as medical practitioners, nurses, dentists, pharmacists, and allied health professionals.

Note: Individual healthcare providers are also referred to as healthcare practitioners.

Organisational Healthcare Providers

These are organisations that deliver healthcare services. Examples include hospitals, day procedure centers, aged care facilities, and pathology or radiology services.

Healthcare Identifiers

Healthcare Provider Identifiers (HPI-I and HPI-O) are used to uniquely identify individuals and organisations involved in the delivery of healthcare services.

Healthcare Provider Directory

A healthcare provider directory is a repository of information (where data is stored and maintained) about healthcare providers.

FHIR Resources

There are a number of provider-related FHIR resources.

For example:

• Practitioner
• Practitioner Role
• Organization
• Healthcare Service
• Location

Note: As per the FHIR specifcation, the spelling of FHIR resource names (like "Organization") follows the American English standard.

FHIR Operations

FHIR operations are interactions defined by the FHIR standard for manipulating healthcare data. They follow a RESTful paradigm, allowing for Create, Read, Update, Delete (CRUD) and Search actions on FHIR resources.

For example, to read Organisation information:

GET /Organization/{id}

SMART on FHIR

SMART on FHIR defines OAuth 2.0 scopes that allow applications to request a specific set of access rights. The OAuth 2.0 client conveys this information to the authorization server in the form of a 'scope' request parameter.

The SMART on FHIR specification defines the structure of scopes, for example:

system/Organization.read
system/Organization.write

To enable an OAuth 2.0 client to read all the values from the Organization resource the client would include the system/Organization.read scope in its request to the authorization server.

A resource context prefixes each SMART on FHIR scope:

user
patient
system

This value represents one of three possible scenarios: user access to the resource is constrained by the user's access permissions; patient access to the resource is restricted to the in-context patient; system access is confined to system-based authorization workflows (e.g., the Client Credentials grant).

The following modification rights are defined:

read
write

Where read includes "search" and "history”. And, write includes create", "update and "delete".

Note: Keycloak does not support wildcard scopes, clients must explicitly request each scope they require.

Access Control

How do we define coarse-grained access control?

Coarse-grained access control is when access to resources is granted or denied based on broad, general criteria, often at the role (RBAC) level.

For example:

• Responsible Officer (RO)
• Organisation Maintenance Officer (OMO)
• Authorised Employee
• Individual Health Care Provider
• Contracted Service Provider (CSP)
• General Supporting Organisation (GSO)

How do we define fine-grained access control?

Fine-grained access control is when access to resources is granted or denied based on multiple conditions and may combine different access control mechanisms (ABAC, RBAC, ReBAC, UBAC).

In the Australian Healthcare context, support for fine-grained access control is often required.

For example, a Practitioner must be granted the Organisation Maintenance Officer (OMO) role and have a membership relationship with an Organisation in order to maintain Healthcare Service information on an Organisation's behalf.

We need an Authorisation Service that can provide fine-grained access control for FHIR resources in a Healthcare Provider Directory.

Authorisation Service

The Authorisation Service is comprised of the following components:

• OAuth 2.0 Authorization Server that supports the Client Credentials grant and the Token Exchange grant
• Policy Engine

Keycloak supports the Client Credentials grant and the Token Exchange grant.

Policy decisions (evaluation) are performed by the general purpose Policy Engine (i.e., Open Policy Agent).

Policies are enforced by the API Gateway (APISIX).

Policies are authored in Rego.

Reference data (e.g., Roles, Permissions, Relationships) is loaded when the Policy Engine is healthy.

Policies are loaded when the Policy Engine is healthy and all reference data has been loaded.

Source Code

• GitHub: Australian Healthcare Provider Directory Starter Project

What's Next

In the next post, we'll take a look at Open Policy Agent. A general-purpose policy engine that you can use for policy decisions (evaluation) in API gateways, microservices and more.

References

OAuth 2.0

• IETF: The OAuth 2.0 Authorization Framework
• IETF: OAuth 2.0 Token Exchange
• IETF: The OAuth 2.0 Authorization Framework: Bearer Token Usage
• IETF: Resource Indicators for OAuth 2.0
• IETF: JSON Web Token (JWT)
• IETF: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
• IETF: OAuth 2.0 Dynamic Client Registration Protocol
• IETF: OAuth 2.0 for Browser-Based Applications
• Spring docs: Implementation Guidelines for Browser-Based Applications

HL7

• HL7: Implementation Guide
• HL7: FHIR NPM Packages
• AU Core: Publication (Version) History
• AU Core FHIR Implementation Guide: AU Core - 1.0.0-preview
• AU Core FHIR Implementation Guide: Testing FAQs
• Sparked AU Core Test Data: Postman collection
• HL7 AU: Australian Provider Directory Implementation Guide

Keycloak

• Keycloak docs: Configuring Keycloak for production
• Keycloak docs: Configuring TLS
• Keycloak docs: Configuring trusted certificates
• Keycloak docs: Configuring the hostname
• Keycloak docs: Using a reverse proxy
• Keycloak docs: Running Keycloak in a container
• Keycloak docs: Migrating to the Quarkus distribution
• Keycloak docs: Upgrading Guide - 26.1.0
• Keycloak docs: Authorization Services Guide

Keycloak-based Development

• GitHub: Keycloak Project Example
• GitHub: Awesome Keycloak

Keycloak Support

• Google Group: Keycloak User
• Google Group: Keycloak Dev

APISIX

• APISIX docs: Deployment modes
• APISIX docs: SSL Protocol
• APISIX docs: Certificate
• APISIX docs: Plugins - OpenID Connect

Provider Directory

• HAPI FHIR: Website
• HAPI FHIR: Documentation
• Google Group: HAPI FHIR

Introduction

HAPI FHIR is an open source implementation of the HL7 FHIR standard for healthcare interoperability.

The easiest way to get started with HAPI FHIR is to use the HAPI FHIR JPA Server Starter Project.

In previous posts, we have worked to augment the HAPI FHIR JPA Server Starter Project in order to demonstrate secure access to FHIR resources.

Including:

• Support for OpenID Connect and OAuth 2.0 (e.g., SMART on FHIR)
• Secure HAPI FHIR data in transit

See: HAPI FHIR AU Starter Project

In this post, we'll use the Docker image of the Percona Distribution for PostgreSQL to encrypt data at rest.

Percona Distribution for PostgreSQL

The pg_tde extension enables encryption at the table level. The encryption is transparent and does not require any changes to applications.

Secure data at rest

Enable encryption

The Docker image of the Percona Distribution for PostgreSQL includes the pg_tde extension that provides data encryption:

  postgres:
    container_name: postgres  
    image: percona/percona-distribution-postgresql:17.5
    
    ...

    environment:
      ENABLE_PG_TDE: 1
      
      ...

See: docker-compose.yml

ENABLE_PG_TDE: 1 adds pg_tde to the shared_preload_libraries entry in the postgresql.conf file and enables the custom storage manager.

Connect to the container:

docker exec -it postgres bash

Start an interactive psql session:

psql -U admin -d hapi-fhir

Create the pg_tde extension in the database you want to encrypt:

\c hapi-fhir;
CREATE EXTENSION pg_tde;

Check the list of installed extensions:

hapi-fhir=# \dx
                 List of installed extensions
  Name   | Version |   Schema   |         Description          
---------+---------+------------+------------------------------
 pg_tde  | 1.0-rc  | public     | pg_tde access method
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
(2 rows)

Configure a key provider:

SELECT pg_tde_add_database_key_provider_file('file-vault', '/tmp/pg_tde_test_001_basic.per');

You should see something like:

 pg_tde_add_database_key_provider_file 
---------------------------------------
                                     1
(1 row)

Note: This sample key provider configuration is meant for development and testing purposes only, not production.

Set a principal key:

SELECT pg_tde_set_key_using_database_key_provider('test-db-key', 'file-vault');

You should see something like:

 pg_tde_set_key_using_database_key_provider 
--------------------------------------------
 
(1 row)

Alter a HAPI FHIR table to enable encryption:

ALTER TABLE hfj_resource SET ACCESS METHOD tde_heap;

You should see something like:

ALTER TABLE

Check to see if the table is encrypted:

select pg_tde_is_encrypted('hfj_resource');

You should see something like:

 pg_tde_is_encrypted 
---------------------
 t
(1 row)

End your interactive psql session:

\q

Source Code

• GitHub: HAPI FHIR AU Starter Project

Resources

• Percona Distribution for PostgreSQL: Docker
• Percona Community Forum: pg_tde
• GitHub: Percona PostgreSQL - Test Case 001

Introduction

HAPI FHIR is an open source implementation of the HL7 FHIR standard for healthcare interoperability.

The easiest way to get started with HAPI FHIR is to use the HAPI FHIR JPA Server Starter Project.

In previous posts, we have worked to augment the HAPI FHIR JPA Server Starter Project in order to demonstrate secure access to FHIR resources.

Including:

• Support for OpenID Connect and OAuth 2.0 (e.g., SMART on FHIR)

See: HAPI FHIR AU Starter Project

In this post, we'll enable TLS in HAPI FHIR's embedded web server and ensure that all PostgreSQL clients use encrypted connections.

HAPI FHIR

Enable TLS

HAPI FHIR relies on the underlying web server for TLS encryption.

All embedded web servers supported by Spring Boot can be configured to secure connections with TLS (SSL) by using the server.ssl.* properties.

For example:

services:

  hapi-fhir:
    container_name: hapi-fhir
    build:
      context: ./services/hapi-fhir
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - 6443:8443      
    environment:
      SERVER_SSL_ENABLED: true
      SERVER_SSL_KEY_STORE_TYPE: PKCS12
      SERVER_SSL_KEY_STORE: file:/keystore/keystore.p12
      SERVER_SSL_KEY_STORE_PASSWORD: secret
      SERVER_SSL_KEY_ALIAS: tomcat
      SERVER_PORT: 8443
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/${HAPI_FHIR_DB}
      SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER}
      SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
      SPRING_DATASOURCE_DRIVER_CLASS_NAME: org.postgresql.Driver
      SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgresDialect
      SPRING_JPA_PROPERTIES_SEARCH_ENABLED: false
    env_file:
      - ./.env
    volumes:
      - '${PWD}/certs/keystore.p12:/keystore/keystore.p12'
    configs:
      - source: hapi
        target: /app/config/application.yaml
    depends_on:
      postgres:
        condition: service_healthy
      keycloak.au.localhost:
        condition: service_healthy
    networks:
      - hapi_fhir_network

  ...

configs:
  hapi:
    file: ./hapi.application-enable-tls.yaml

See: docker-compose.yml

Access to a keystore file containing the server certificate and private key is also required. You can use openssl to create a PKCS12 keystore.

For example:

openssl pkcs12 -export -in cert.pem -inkey key.pem -out keystore.p12 -name tomcat -password pass:secret

PostgreSQL

Enable TLS

Support for encrypted connections is enabled by setting the ssl parameter to on. The server will listen for both normal and secure connections on the same port.

Connecting clients can be required to use encrypted connections by setting the environment variable PGSSLMODE to require.

For example:

services:

  postgres:
    container_name: postgres
    
    ...
    
    command: >
      -c ssl=on 
      -c ssl_cert_file=/var/lib/postgresql/server.crt 
      -c ssl_key_file=/var/lib/postgresql/server.key
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PGSSLMODE: require
    env_file:
      - ./.env      
    volumes:
      - '${PWD}/certs/cert.pem:/var/lib/postgresql/server.crt'
      - '${PWD}/certs/key.pem:/var/lib/postgresql/server.key'
      - postgres_data:/var/lib/postgresql/data
      
    ...

PostgreSQL also requires access to the files containing the server certificate and private key.

Note: On Unix and macOS systems the cert and key file permissions must disallow any access to world or group.

For example:

sudo chmod 600 *.pem

We can check that the connections to PostgreSQL are secure by running the following query:

select pg_ssl.pid, pg_ssl.ssl, pg_ssl.version,
       pg_sa.backend_type, pg_sa.usename, pg_sa.client_addr
       from pg_stat_ssl pg_ssl
       join pg_stat_activity pg_sa
       on pg_ssl.pid = pg_sa.pid;

In pgAdmin:

We can obtain HAPI FHIR's IP Address using the following command:

docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' hapi-fhir

You should see something like:

172.18.0.6

Source Code

• GitHub: HAPI FHIR AU Starter Project

Resources

• HAPI FHIR: Website
• HAPI FHIR: Documentation
• HAPI FHIR AU docs: Working with mkcert
• PostgreSQL: Documentation

Introduction

In a previous post, I wrote about how to use Keycloak and the APISIX openid_connect plugin to add support for SMART on FHIR to HAPI FHIR.

In this post we are going to look at how to use Keycloak and the APISIX authz-keycloak plugin to add support for SMART on FHIR to HAPI FHIR.

Keycloak Authorization Services

Fine-grained Authorisation

You must allow the 'Authorization' capability config setting in order to enable support for fine-grained authorisation.

APISIX

AuthZ Keycloak plugin

The authz-keycloak plugin enables APISIX to leverage the fine-grained authorisation policies and access control mechanisms supported by Keycloak.

See: Keycloak - Authorization Services Guide

Static permissions

The authz-keycloak plugin can be configured to support different authorisation scenarios.

For example, you can configure Keycloak to use scope-based permissions associated with a client scope policy and configure the authz-keycloak plugin to use static permissions:

• Resource: Patient
• Authorisation Scope: Patient.read
• Client Scope: system/Patient.read
• Client Scope Policy: patient-read-client-scope-policy
• Scope-based Permission: patient-read-scope-permission

  permissions: [ "Patient#Patient.read" ]

Create an Authorisation Scope in Keycloak

Create an Authorisation Scope (Patient.read) in Keycloak:

Create a Resource in Keycloak

Create a Resource (Patient) in Keycloak:

Create a Client Scope in Keycloak

Create a Client Scope (system/Patient.read) in Keycloak:

Create a Client Scope Policy in Keycloak

Create a Client Scope Policy (patient-read-client-scope-policy) in Keycloak:

Create a Scope-based Permission in Keycloak

Create a Scope-based Permission (patient-read-scope-permission) in Keycloak:

Configure APISIX

Create a route as follows:

  ...

  - name: hapi-fhir-api
    host: hapi-fhir.au.localhost
    uri: /fhir/Patient*
    methods: [ "GET" ]
    upstream_id: 1
    plugins:
      authz-keycloak:
        lazy_load_paths: false
        ssl_verify: true
        client_id: ${{CLIENT_ID}}
        client_secret: ${{CLIENT_SECRET}}
        discovery: ${{PROTOCOL}}://${{KEYCLOAK_HOSTNAME}}:${{KEYCLOAK_PORT}}/realms/${{KEYCLOAK_REALM}}/.well-known/openid-configuration
        permissions: [ "Patient#Patient.read" ]

See: apisix-standalone.yml

Each entry in the 'permissions' attribute must be formatted as expected by the token endpoint's permission parameter.

For example: "Resource#Authorisation Scope".

See: Keycloak - Authorization Services Guide: Obtaining permissions

Call the HAPI FHIR API

Request a token

To access the API, you must request an access token. You will need to POST to the token URL.

For example (scope=system/Patient.read):

ACCESS_TOKEN=$(curl -s -X POST https://keycloak.au.localhost:8443/realms/hapi-fhir-dev/protocol/openid-connect/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_id=oauth2-proxy \
  -d client_secret=aHkRec1BYkfaKgMg164JmvKu8u9iWNHM \
  -d scope=system/Patient.read | (jq -r '.access_token'))
                 
# echo "$ACCESS_TOKEN"                 

Note: You can use jwt.io to decode the access token.

Introspect a token

To introspect an Access Token you will need to POST to the introspect URL.

For example:

curl -X POST "https://keycloak.au.localhost:8443/realms/hapi-fhir-dev/protocol/openid-connect/token/introspect" \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d client_id=oauth2-proxy \
  -d client_secret=aHkRec1BYkfaKgMg164JmvKu8u9iWNHM \
  -d "token_type_hint=access_token&token=$ACCESS_TOKEN"

Call the API

To call the HAPI FHIR API, an application must pass the access token as a Bearer token in the Authorization header of the HTTP request.

For example:

curl -X GET https://hapi-fhir.au.localhost/fhir/Patient?_id=baratz-toni \
  -H 'Content-Type: application/fhir+json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

You should see something like:

{
  "resourceType": "Bundle",
  "id": "9d80c83a-0b06-4b78-bce2-21e6666348d8",
  "meta": {
    "lastUpdated": "2025-05-23T05:43:01.959+00:00"
  },
  "type": "searchset",
  "total": 1,
  "link": [ {
    "relation": "self",
    "url": "https://hapi-fhir.au.localhost/fhir/Patient?_id=baratz-toni"
  } ],
  "entry": [ {
    "fullUrl": "https://hapi-fhir.au.localhost/fhir/Patient/baratz-toni",
    "resource": {
      "resourceType": "Patient",
      "id": "baratz-toni",
      "meta": {
        "versionId": "1",
        "lastUpdated": "2025-05-23T05:42:36.551+00:00",
        "source": "#rKTCeZfmnReSjm8X",
        "profile": [ "http://hl7.org.au/fhir/core/StructureDefinition/au-core-patient" ]
      },
      "extension": [ {
        "url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
        "valueCoding": {
          "system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
          "code": "1",
          "display": "Aboriginal but not Torres Strait Islander origin"
        }
      }, {
        "url": "http://hl7.org/fhir/StructureDefinition/individual-genderIdentity",
        "extension": [ {
          "url": "value",
          "valueCodeableConcept": {
            "coding": [ {
              "system": "http://snomed.info/sct",
              "code": "446141000124107",
              "display": "Identifies as female gender"
            } ]
          }
        } ]
      }, {
        "url": "http://hl7.org/fhir/StructureDefinition/individual-pronouns",
        "extension": [ {
          "url": "value",
          "valueCodeableConcept": {
            "coding": [ {
              "system": "http://loinc.org",
              "code": "LA29519-8",
              "display": "she/her/her/hers/herself"
            } ]
          }
        } ]
      }, {
        "url": "http://hl7.org/fhir/StructureDefinition/individual-recordedSexOrGender",
        "extension": [ {
          "url": "type",
          "valueCodeableConcept": {
            "coding": [ {
              "system": "http://snomed.info/sct",
              "code": "1515311000168102",
              "display": "Biological sex at birth"
            } ]
          }
        }, {
          "url": "value",
          "valueCodeableConcept": {
            "coding": [ {
              "system": "http://snomed.info/sct",
              "code": "248152002",
              "display": "Female"
            } ]
          }
        } ]
      } ],
      "identifier": [ {
        "extension": [ {
          "url": "http://hl7.org.au/fhir/StructureDefinition/ihi-status",
          "valueCoding": {
            "system": "https://healthterminologies.gov.au/fhir/CodeSystem/ihi-status-1",
            "code": "active"
          }
        }, {
          "url": "http://hl7.org.au/fhir/StructureDefinition/ihi-record-status",
          "valueCoding": {
            "system": "https://healthterminologies.gov.au/fhir/CodeSystem/ihi-record-status-1",
            "code": "verified",
            "display": "verified"
          }
        } ],
        "type": {
          "coding": [ {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "NI"
          } ],
          "text": "IHI"
        },
        "system": "http://ns.electronichealth.net.au/id/hi/ihi/1.0",
        "value": "8003608000311662"
      }, {
        "type": {
          "coding": [ {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MC"
          } ],
          "text": "Medicare Number"
        },
        "system": "http://ns.electronichealth.net.au/id/medicare-number",
        "value": "69518252411"
      } ],
      "name": [ {
        "use": "official",
        "family": "BARATZ",
        "given": [ "Toni" ]
      } ],
      "telecom": [ {
        "system": "phone",
        "value": "0870101270",
        "use": "home"
      }, {
        "system": "phone",
        "value": "0491570156",
        "use": "mobile"
      }, {
        "system": "phone",
        "value": "0870108006",
        "use": "work"
      } ],
      "gender": "female",
      "birthDate": "1978-06-16",
      "address": [ {
        "line": [ "24 Law Cir" ],
        "city": "Bassendean",
        "state": "WA",
        "postalCode": "6054",
        "country": "AU"
      } ]
    },
    "search": {
      "mode": "match"
    }
  } ]
}             

Test Data

See: HAPI FHIR and AU Core Test Data

Source Code

• GitHub: HAPI FHIR AU with Auth Starter Project

References

System Hardening

• Australian Signals Directorate: Implementing Certificates, TLS, HTTPS and Opportunistic TLS
• Cloudflare docs: Cipher suites recommendations

HL7

• HL7: Implementation Guide
• HL7: FHIR NPM Packages
• AU Core: Publication (Version) History
• AU Core FHIR Implementation Guide: AU Core - 1.0.0-preview
• AU Core FHIR Implementation Guide: Testing FAQs
• Sparked AU Core Test Data: Postman collection

SMART on FHIR

• HL7: SMART App Launch
• SMART Health IT: SMART on FHIR

SMART on FHIR - Standalone Launch

• Project Alvearie: SMART App Launch
• Project Alvearie: Keycloak extensions for FHIR
• Keycloak extensions for FHIR: Upgrade to the Quarkus-based distribution
• Keycloak discussion: Fine grained scope consent management

SMART on FHIR - EHR Launch

• GitHub: Zedwerks - Keycloak extensions for FHIR

Keycloak

• Keycloak docs: Configuring Keycloak for production
• Keycloak docs: Configuring TLS
• Keycloak docs: Configuring trusted certificates
• Keycloak docs: Configuring the hostname
• Keycloak docs: Using a reverse proxy
• Keycloak docs: Running Keycloak in a container
• Keycloak docs: Migrating to the Quarkus distribution
• Keycloak docs: Upgrading Guide - 26.1.0
• Keycloak docs: Authorization Services Guide

Keycloak-based Development

• GitHub: Keycloak Project Example
• GitHub: Awesome Keycloak

Keycloak Support

• Google Group: Keycloak User
• Google Group: Keycloak Dev

APISIX

• APISIX docs: Deployment modes
• APISIX docs: SSL Protocol
• APISIX docs: Certificate
• APISIX docs: Plugins - OpenID Connect

HAPI FHIR

• HAPI FHIR: Website
• HAPI FHIR: Documentation
• Google Group: HAPI FHIR

Introduction

This is the second post, in a series of posts about adding support for (fine grained) Authorization (AuthZ) in HAPI FHIR.

• Add AuthZ to HAPI FHIR - Part 1
• Add AuthZ to HAPI FHIR - Part 2

In the first post, we identified some options to enable Authorization in HAPI FHIR.

In this post we are going to look at Option 1 in more detail.

Option 1

There are three components to this solution: an Identity Provider that authenticates the user; an Authorization Server that decides what a given user can access; and an Access Gateway which enforces those permissions.

• Identity Provider: Keycloak
• Authorization Server: Keycloak
• Access Gateway: FHIR Info Gateway

Keycloak

SMART on FHIR Scopes

SMART on FHIR defines OAuth 2.0 scopes that allow client applications to request a specific set of access rights. The client conveys this information to the authorization server in the form of a 'scope' request parameter.

The SMART on FHIR specification defines the structure of scopes, for example:

• user/CarePlan.read
• patient/MedicationOrder.read
• system/Observation.write

To enable a user to read all the values from the CarePlan resource the client would include the user/CarePlan.read scope in its request to the authorization server.

A resource context prefixes each SMART on FHIR scope:

• user
• patient
• system

This value represents one of three possible scenarios: user access to the resource is constrained by the user's access permissions; patient access to the resource is restricted to the in-context patient; system access is confined to system-based authorization workflows.

The following modification rights are defined:

• read
• write

Where read includes "search" and "history”. And, write includes create", "update and "delete".

Keycloak does not support wildcard scopes, clients must explicitly request each scope they require.

Also see:

• Oracle Health Millennium Platform: Scopes
• okta forum: SMART on FHIR wildcard scopes

Client Scopes

In Keycloak, an OAuth 2.0 scope is mapped to a client scope.

Navigate to the Keycloak Admin Console:

https://keycloak.au.localhost:8443

In the hapi-fhir-dev realm, select 'Client scopes', then click the 'Create client scope' button:

Enter the details for the patient/AllergyIntolerance.read scope:

Then click the 'Save' button.

Select 'Clients' and oauth2-proxy and then choose the 'Client scopes' tab, click the 'Add client scope' button:

Add the patient/AllergyIntolerance.read client scope to the client:

Note: The patient/AllergyIntolerance.read scope is an optional scope.

If we enable the 'Consent required' setting:

An add the patient/AllergyIntolerance.read client scope to the scope request parameter (via the project's .env file):

...

SCOPE="openid patient/AllergyIntolerance.read"

See: .env

Then we can check that we have successfully configured the patient/AllergyIntolerance.read client scope:

Call the FHIR API

OAuth 2.0 Client Credentials Grant

You must allow the 'Service account roles' capability config setting in order to enable support for the OAuth 2.0 Client Credentials Grant:

Request a token

To access the API, you must request an access token. You will need to POST to the token URL.

For example (scope=system/Patient.read):

ACCESS_TOKEN=$(curl -s -X POST https://keycloak.au.localhost:8443/realms/hapi-fhir-dev/protocol/openid-connect/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_id=oauth2-proxy \
  -d client_secret=aHkRec1BYkfaKgMg164JmvKu8u9iWNHM \
  -d scope=system/Patient.read | (jq -r '.access_token'))
                 
# echo "$ACCESS_TOKEN"                 

If you decode the access token you should see something like:

{
  "exp": 1737495977,
  "iat": 1737495677,
  "jti": "d6ba5750-c49a-419e-9d7a-80bb8eda8f5e",
  "iss": "https://keycloak.au.localhost:8443/realms/hapi-fhir-dev",
  "aud": [
    "oauth2-proxy",
    "account"
  ],
  "sub": "da4f0912-1cd9-432d-9c9d-a55db11093de",
  "typ": "Bearer",
  "azp": "oauth2-proxy",
  "acr": "1",
  "allowed-origins": [
    "*"
  ],
  "realm_access": {
    "roles": [
      "default-roles-hapi-fhir-dev",
      "offline_access",
      "uma_authorization"
    ]
  },
  "resource_access": {
    "oauth2-proxy": {
      "roles": [
        "uma_protection"
      ]
    },
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "system/Patient.read profile email",
  "email_verified": false,
  "clientHost": "172.18.0.1",
  "preferred_username": "service-account-oauth2-proxy",
  "clientAddress": "172.18.0.1",
  "client_id": "oauth2-proxy"
}

Call the API

To call the API, an application must pass the access token as a Bearer token in the Authorization header of your HTTP request.

For example:

curl -X GET https://hapi-fhir.au.localhost/fhir/Patient?_id=baratz-toni \
  -H 'Content-Type: application/fhir+json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Source Code

• GitHub: HAPI FHIR AU with Auth Starter Project

References

OAuth 2.0

• IETF: OAuth 2.0 for Browser-Based Applications
• Spring docs: Implementation Guidelines for Browser-Based Applications

SMART on FHIR

• HL7: SMART App Launch
• HL7: Backend Services
• SMART Health IT: SMART on FHIR

Keycloak

• Keycloak docs: Migrating to the Quarkus distribution
• Keycloak docs: Upgrading Guide - 26.1.0
• Keycloak docs: Server Administration Guide
• Google Group: Keycloak Dev
• Google Group: Keycloak User

FHIR Info Gateway

• GitHub: FHIR Info Gateway

Clinical Information Systems

• Oracle Health Millennium Platform: Authorization Framework

Introduction

In previous posts, I wrote about adding support for Authentication (AuthN) to HAPI FHIR.

In this post, we will take a look at some options to enable (fine grained) Authorization (AuthZ) in HAPI FHIR.

Option 1

There are three components to this solution: an Identity Provider that authenticates the user; an Authorization Server that decides what a given user can access; and an Access Gateway which enforces those permissions.

• Identity Provider: Keycloak
• Authorization Server: Keycloak
• Access Gateway: FHIR Info Gateway

Authorization Server

The HAPI FHIR AU with Auth Starter Project already uses Keycloak for Authentication (AuthN).

We will need to extend Keycloak and add support for SMART on FHIR.

Standalone Launch

See:

• Project Alvearie: SMART App Launch
• Project Alvearie: Keycloak extensions for FHIR
• Keycloak extensions for FHIR: Upgrade to the Quarkus-based distribution
• Keycloak discussion: Fine grained scope consent management

EHR Launch

See:

• GitHub: Zedwerks - Keycloak extensions for FHIR

Access Gateway

The FHIR Information Gateway sits in front of a FHIR store (e.g., a HAPI FHIR server) and controls access to FHIR resources.

See:

• FHIR Info Gateway: Introduction

Option 2

Three components as per option 1.

AuthN and AuthZ: Keycloak

Access Gateway

A severless implementation of an Access Gateway.

Knative and OpenFaaS are open-source environments for creating and hosting serverless functions.

See:

• GitHub: Okta SMART on FHIR docs
• GitHub: Okta SMART on FHIR demo

Option 3

Three components as per option 1.

AuthN and AuthZ: Keycloak

Access Gateway

An Access Gateway implementation with support for Relationship-Based
Access Control (ReBAC).

See:

• GitHub: Secured FHIR Proxy
• OpenFGA: Relationship-based access control

Option 4

Three components as per option 1.

AuthN and AuthZ: Keycloak

Access Gateway

An Access Gateway implementation based on Spring Cloud Gateway.

See:

• Spring blog: Embracing Virtual Threads
• Spring blog: Spring Tips: Spring Cloud Gateway for Spring MVC
• Spring docs: Spring Cloud Gateway Server MVC

What's Next

In the next post, we'll take a look Option 1 in more detail.

Source Code

• GitHub: HAPI FHIR AU with Auth Starter Project

References

OAuth 2.0

• IETF: OAuth 2.0 for Browser-Based Applications
• Spring docs: Implementation Guidelines for Browser-Based Applications

SMART on FHIR

• HL7: SMART App Launch
• HL7: Backend Services
• SMART Health IT: SMART on FHIR

Keycloak

• Keycloak docs: Migrating to the Quarkus distribution
• Keycloak docs: Upgrading Guide - 26.1.0
• Keycloak docs: Authorization Services Guide

FHIR Info Gateway

• GitHub: FHIR Info Gateway