How to enable hierarchical access control

This guide explains how multi-tenancy on the Organization resources can be enabled

Prerequisites

Docker and Docker Compose

You should have Docker and Docker Compose installed before go further. To get it installed follow the instructions.

Aidbox license

To get the Aidbox License:

1. Go the Aidbox user portal https://aidbox.app

2. Login to the portal

3. Create new self-hosted Aidbox License or use the license that you already have

Create Aidbox project

Aidbox is configured by the Aidbox Configuration Project. To create sample project run command below.

Note that to use hierarchical access control with the FHIR Schema validator, you need to clone the orgbac-with-fhir-schema branch, which has the FHIR Schema validator enabled and the Aidbox Configuration Project configured.

FHIR R4

git clone \
  --branch=main \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git

FHIR R5

git clone \
  --branch=fhir-r5 \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git

FHIR Schema R4

git clone \
  --branch=orgbac-with-fhir-schema \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git

FHIR Schema R5

git clone \
  --branch=orgbac-with-fhir-schema-r5 \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git

Apply the license

Populate the .env file with the Aidbox License.

.env

AIDBOX_LICENSE=YOUR_AIDBOX_LICENSE_KEY

...

Enable multi-tenancy

To enable hierarchical access control (multi-tenancy on Organization resources) ensure that necessary imports are present in zrc/main.edn file.

FHIR R4

Add aidbox.multitenancy.v1.fhir-r4 to the import section.

zrc/main.edn

{ns main
 import #{aidbox
          aidbox.multitenancy.v1.fhir-r4 ;; import multitenancy
          config}
 
 box
 {:zen/tags #{aidbox/system}
  :config   config/base-config
  :services {:admin-user-seed config/admin-user-seed
             :root-client-seed config/root-client-seed}}}

FHIR R5

Add aidbox.multitenancy.v1.fhir-r5 to the import section.

zrc/main.edn

{ns main
 import #{aidbox
          aidbox.multitenancy.v1.fhir-r5 ;; import multitenancy
          config}
 
 box
 {:zen/tags #{aidbox/system}
  :config   config/base-config
  :services {:admin-user-seed config/admin-user-seed
             :root-client-seed config/root-client-seed}}}

Start Aidbox with Docker Compose

To start Aidbox run the command in the aidbox-project directory.

docker compose up --force-recreate

When Aidbox starts, navigate to the http://localhost:8888 and sign in to the Aidbox UI using the credentials admin / password.

Ensure the hierarchical access control works

Create nested Organization resources

Use Aidbox UI Rest Console to create nested Organization resources.

Root organization

status: 201 (created)

PUT /fhir/Organization/org-a

name: Organization A

Child organization

status: 201 (created)

PUT /fhir/Organization/org-b

partOf:
  reference: Organization/org-a
name: Organization B

Grant-child organization

status: 201 (created)

PUT /fhir/Organization/org-c

partOf:
  reference: Organization/org-b
name: Organization C

You should have 3 nested organizations for now

org-a
└── org-b
   └── org-c

Create resource in the Organization B

Use Aidbox UI Rest Console to create Patient resource in the organization B.

status: 201 (created)

PUT /Organization/org-b/fhir/Patient/pt-1

Check access control works

Patient is visible from the Organization above (org-a)

status: 200

GET /Organization/org-a/fhir/Patient/pt-1

Patient is visible from its Organization (org-b)

status: 200

GET /Organization/org-b/fhir/Patient/pt-1

Patient is not visible from the nested Organization (org-c)

status: 403

GET /Organization/org-c/fhir/Patient/pt-1

Configuring AccessPolicies

To allow some user/client to interact with a organization-based resources, AccessPolicy should be configured to check organization id from the https://aidbox.app/tenant-organization-id extension of User/Client resource.

This example allows org-based user (created by PUT /Organization/<org-id>/fhir/User) to see patients that are also created by OrgBAC.

PUT /AccessPolicy/as-user-allow-org-patients

description: A user should be able to get every patient in their organization.
engine: matcho
matcho:
  params:
    resource/type: Patient
  request-method: get
  user:
    meta:
      extension:
        $contains:
          url: https://aidbox.app/tenant-organization-id
          value:
            Reference:
              id: .params.organization/id