The IBM FHIR Server supports many different persistence stores – Apache Derby, Postgres, and IBM Db2. The IBM Db2 offering includes a multi-tenancy feature with row-level permissions. Each tenant is assigned a unique internal id for the tenantName and tenantKey. The tenantKey on each JDBC connection is verified using a one-way hash, and supports allocating a tenant, adding a key to an existing tenant, revoking a key and revoking all tenant keys.

Recipe

1. Once you have created the schema on your database via the --update-schema, you can allocate a tenant.

java -jar fhir-persistence-schema-*-cli.jar \
    --prop db.host=db \
    --prop db.port=50000 \
    --prop db.database=fhirdb \
    --prop user=db2inst1 \
    --prop password=change-password \
    --db-type db2 \
    --allocate-tenant acme32

2021-06-22 11:19:13.226 00000001    INFO .common.JdbcConnectionProvider Opening connection to database: jdbc:db2://db:50000/fhirdb
2021-06-22 11:19:14.346 00000001 WARNING ls.pool.PoolConnectionProvider Get connection took 1.120 seconds
...
2021-06-22 11:22:59.846 00000001    INFO   com.ibm.fhir.schema.app.Main tenantId [29] is being pre-populated with lookup table data.
2021-06-22 11:22:59.930 00000001    INFO   com.ibm.fhir.schema.app.Main Finished prepopulating the resource type and search parameter code/name tables tables
2021-06-22 11:22:59.948 00000001    INFO   com.ibm.fhir.schema.app.Main Allocated tenant: acme32 [key=UsBglbyMJpSi/RjXwrkp0Bj2bAljUI+MixfAikdrcN0=] with Id = 29
2021-06-22 11:22:59.949 00000001    INFO   com.ibm.fhir.schema.app.Main The tenantKey JSON follows:
{"tenantKey": "UsBglbyMJpSi/RjXwrkp0Bj2bAljUI+MixfAikdrcN0="}
2021-06-22 11:22:59.949 00000001    INFO   com.ibm.fhir.schema.app.Main Processing took: 226.765 s
2021-06-22 11:22:59.950 00000001    INFO   com.ibm.fhir.schema.app.Main SCHEMA CHANGE: OK

2. You can add a tenant key to an existing tenant.

java -jar fhir-persistence-schema-*-cli.jar \
    --prop db.host=db \
    --prop db.port=50000 \
    --prop db.database=fhirdb \
    --prop user=db2inst1 \
    --prop password=change-password \
    --db-type db2 \
    --add-tenant-key acme32

2021-06-22 11:25:53.254 00000001    INFO .common.JdbcConnectionProvider Opening connection to database: jdbc:db2://db:50000/fhirdb
2021-06-22 11:25:54.197 00000001    INFO   com.ibm.fhir.schema.app.Main New tenant key: acme32 [key=UVFuDqD/V3v8d9S/XRjRQNu9eFTniksvxgIBbI6mEkg=]
2021-06-22 11:25:54.201 00000001    INFO   com.ibm.fhir.schema.app.Main Processing took:   0.975 s
2021-06-22 11:25:54.202 00000001    INFO   com.ibm.fhir.schema.app.Main SCHEMA CHANGE: OK

3. List tenant to see allocated

java -jar fhir-persistence-schema-*-cli.jar \
    --prop db.host=db \
    --prop db.port=50000 \
    --prop db.database=fhirdb \
    --prop user=db2inst1 \
    --prop password=change-password \
    --db-type db2 \
    --list-tenants

2021-06-22 11:28:43.566 00000001    INFO .common.JdbcConnectionProvider Opening connection to database: jdbc:db2://db:50000/fhirdb
 TenantId     Status       TenantName Schema
       29  ALLOCATED           acme32 FHIRDATA
2021-06-22 11:28:44.395 00000001    INFO   com.ibm.fhir.schema.app.Main Processing took:   0.854 s
2021-06-22 11:28:44.396 00000001    INFO   com.ibm.fhir.schema.app.Main SCHEMA CHANGE: OK

4. Revoking tenant key

java -jar fhir-persistence-schema-*-cli.jar \
    --prop db.host=db \
    --prop db.port=50000 \
    --prop db.database=fhirdb \
    --prop user=db2inst1 \
    --prop password=change-password \
    --db-type db2 \
    --revoke-tenant-key acme32 \
    --tenant-key UVFuDqD/V3v8d9S/XRjRQNu9eFTniksvxgIBbI6mEkg=

2021-06-22 11:27:17.280 00000001    INFO .common.JdbcConnectionProvider Opening connection to database: jdbc:db2://db:50000/fhirdb
2021-06-22 11:27:18.112 00000001    INFO   com.ibm.fhir.schema.app.Main Tenant Key revoked for 'acme32' total removed=[1]
2021-06-22 11:27:18.119 00000001    INFO   com.ibm.fhir.schema.app.Main Processing took:   0.867 s
2021-06-22 11:27:18.120 00000001    INFO   com.ibm.fhir.schema.app.Main SCHEMA CHANGE: OK

You’ll see one was removed.

5. We’ll add a new key.

java -jar fhir-persistence-schema-*-cli.jar \
    --prop db.host=db \
    --prop db.port=50000 \
    --prop db.database=fhirdb \
    --prop user=db2inst1 \
    --prop password=change-password \
    --db-type db2 \
    --add-tenant-key acme32

2021-06-22 11:25:53.254 00000001    INFO .common.JdbcConnectionProvider Opening connection to database: jdbc:db2://db:50000/fhirdb
2021-06-22 11:25:54.197 00000001    INFO   com.ibm.fhir.schema.app.Main New tenant key: acme32 [key=UVFuDqD/V3v8d9S/XRjRQNu9eFTniksvxgIBbI6mEkg=]
2021-06-22 11:25:54.201 00000001    INFO   com.ibm.fhir.schema.app.Main Processing took:   0.975 s
2021-06-22 11:25:54.202 00000001    INFO   com.ibm.fhir.schema.app.Main SCHEMA CHANGE: OK

6. Revoking tenant key

java -jar fhir-persistence-schema-*-cli.jar \
    --prop db.host=db \
    --prop db.port=50000 \
    --prop db.database=fhirdb \
    --prop user=db2inst1 \
    --prop password=change-password \
    --db-type db2 \
    --revoke-all-tenant-keys acme32

2021-06-22 11:32:34.061 00000001    INFO .common.JdbcConnectionProvider Opening connection to database: jdbc:db2://db:50000/fhirdb
2021-06-22 11:32:35.112 00000001    INFO   com.ibm.fhir.schema.app.Main Tenant Key revoked for 'acme32' total removed=[2]
2021-06-22 11:32:35.144 00000001    INFO   com.ibm.fhir.schema.app.Main Processing took:   1.116 s
2021-06-22 11:32:35.146 00000001    INFO   com.ibm.fhir.schema.app.Main SCHEMA CHANGE: OK

You’ll see that two are removed.

You now know the lifecycle for the IBM FHIR Server tenantKey – allocate, add and revoke.

Reference

• fhir-persistence-schema: README