The goal of this project is to demonstrate how an Authorisation Service can provide fine-grained access control for FHIR resources in a Healthcare Provider Directory.
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.
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.
These are organisations that deliver healthcare services. Examples include hospitals, day procedure centers, aged care facilities, and pathology or radiology services.
Healthcare Provider Identifiers (HPI-I and HPI-O) are used to uniquely identify individuals and organisations involved in the delivery of healthcare services.
A healthcare provider directory is a repository of information (where data is stored and maintained) about healthcare providers.
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 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 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.
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.
The Authorisation Service is comprised of the following components:
- OAuth 2.0 Authorization Server (that supports the Client Credentials grant)
- OAuth 2.0 Security Token Service (that supports the Token Exchange grant)
- Policy Enforcement Point
- Policy Decision Point
Keycloak supports the Client Credentials grant and the Token Exchange grant.
Policies are enforced by the API Gateway (APISIX).
Policy decisions (evaluation) are performed by the general purpose Policy Engine (Open Policy Agent).
Policies are authored in Rego.
Reference data (e.g., 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.
Note: Keycloak does not currently support Resource Indicators for OAuth 2.0.
- Developer Documentation
- Administrator Documentation
- Rob Ferguson's blog: Getting Started with HAPI FHIR
- Rob Ferguson's blog: HAPI FHIR and FHIR Implementation Guides
- Rob Ferguson's blog: HAPI FHIR and AU Core Test Data
- Rob Ferguson's blog: Add AuthN to HAPI FHIR with OAuth2 Proxy, Nginx and Keycloak - Part 1
- Rob Ferguson's blog: Add AuthN to HAPI FHIR with OAuth2 Proxy, Nginx and Keycloak - Part 2
- Rob Ferguson's blog: Add AuthN to HAPI FHIR with OAuth2 Proxy, Nginx and Keycloak - Part 3
- Rob Ferguson's blog: Add AuthN to HAPI FHIR with OAuth2 Proxy, Nginx and Keycloak - Part 4
- Rob Ferguson's blog: Add AuthZ to HAPI FHIR - Part 1
- Rob Ferguson's blog: Add AuthZ to HAPI FHIR - Part 2
- Rob Ferguson's blog: Add AuthN to HAPI FHIR with APISIX and Keycloak
- Rob Ferguson's blog: Add support for SMART on FHIR to HAPI FHIR with APISIX and Keycloak
- Rob Ferguson's blog: Getting started with the APISIX authz-keycloak plugin
- Rob Ferguson's blog: Secure HAPI FHIR data in transit
- Rob Ferguson's blog: Secure HAPI FHIR data at rest
- Rob Ferguson's blog: Healthcare Provider Directory Access Control
- Rob Ferguson's blog: Getting started with Open Policy Agent
- Rob Ferguson's blog: Use Open Policy Agent to enforce access control policies in SMART on FHIR applications
- Australian Signals Directorate: Implementing Certificates, TLS, HTTPS and Opportunistic TLS
- Cloudflare docs: Cipher suites recommendations
- 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: 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
- HL7: SMART App Launch
- SMART Health IT: SMART on FHIR
- 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
- 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
- GitHub: Keycloak Project Example
- GitHub: Awesome Keycloak
- Google Group: Keycloak User
- Google Group: Keycloak Dev
- APISIX: Documentation
- APISIX docs: Deployment modes
- APISIX docs: SSL Protocol
- APISIX docs: Certificate
- APISIX docs: openid-connect plugin
- APISIX docs: authz-keycloak plugin
- API7 docs: authz-keycloak plugin
- APISIX docs: Code Samples
- 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
- HAPI FHIR: Website
- HAPI FHIR: Documentation
- Google Group: HAPI FHIR
- HL7 Australia: Terminology
- ADHA: National Clinical Terminology Service
- ADHA: Strategies and plans
- ADHA: Digital Health Standards Catalogue
- Services Australia: About the Healthcare Provider Directory
- Services Australia: Register for Healthcare Identifiers (HI) Service
- Services Australia: Roles in the HI Service