API-level policies

Ontoserver can be configured to enforce role-based access control (RBAC) permissions with ontoserver.security.enabled equal to either true or fine.

Ontoserver provides three endpoint API families: /api (Admin), /fhir (FHIR), and /synd (Syndication). Within each of these familes there are two role types: READ and WRITE, corresponding to whether the operation can change the state of the server (WRITE) or not (READ).

Additionally, there is one operation-specific permission for [base]/CodeSystem/$x-upload-external.

These authorizations are managed by the scope field of the JWT Token that is provided by the Authorization server. Ontoserver understands the following scopes:

• system/*.read
• system/*.write
• system/CodeSystem.x-upload-external
• onto/api.read
• onto/api.write
• onto/synd.read
• onto/synd.write

Equivalently the authorities field can be used with the following corresponding values:

• FHIR_READ
• FHIR_WRITE
• FHIR_CS_X_UE
• API_READ
• API_WRITE
• SYND_READ
• SYND_WRITE

If the Ontoserver is operating in “anonymous read” mode (i.e., ontoserver.security.readOnly.fhir=true), then all entities, whether authenticated or not, are deemed to have system/*.read (equivalently, FHIR_READ) authorization.

Resource-level policies

Ontoserver can be configured to enforce Resource-level access control with ontoserver.security.enabled equal to fine.

Resource instance level authorizations are also managed by the scope field of the JWT Token that is provided by the Authorization server (or mapped-equivalent values in the authorities field). These authorizations are layered over the API (/fhir) authorizations and further restrict what an entity may do.

This means an entity’s API-level authorizations cannot be increased via this mechanism, but only reduced.

Resource-level authorizations are managed through FHIR’s security labels model. Security labels are attached to a Resource’s meta element.

Ontoserver uses codes from the CodeSystem http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions to manage access to resources. This CodeSystem is open-ended and has codes of the form: [category].read and [category].write, where [category] names an authorization category, and is a non-empty sequence of the characters conforming to the regular expression [_a-zA-Z0-9].

Ontoserver understands the following scopes (where [category] is a placeholder described below):

• grouping/*.read
• grouping/*.write
• grouping/[category].read
• grouping/[category].write

or equivalent authorities values:

• PERM_READ
• PERM_WRITE
• PERM_[category]_READ
• PERM_[category]_WRITE

If a resource has any security labels from this CodeSystem then the following rules are applied:

1. For READ access to any given Resource with a security label from the above CodeSystem and of the form [category].read, Ontoserver will check that the entity’s JWT Token contains a matching scope value grouping/[category].read (or contains grouping/*.read).

2. For READ access to any given Resource with a security label from the above CodeSystem and of the form *.read, the entity must have API (/fhir) READ authorization, but no additional checks are made.

3. For WRITE access to any given Resource with a security label from the above CodeSystem and of the form [category].write, Ontoserver will check that the entity’s JWT Token contains a matching scope value grouping/[category].write (or contains grouping/*.write).

4. For WRITE access to any given Resource with a security label from the above CodeSystem and of the form *.write, the entity must have API (/fhir) WRITE authorization, but no additional checks are made.

Authorization process

When an entity requests authorization, it can ask for grouping/*.read and grouping/*.write. The authorization server will either return a set of scopes specific to appropriate permissions categories of the entity, or the all categories scopes grouping/*.read and grouping/*.write, if appropriately authorised.

Note that these all categories scopes grouping/*.read (grouping/*.write) convey READ (WRITE) access to all resources, regardless of their security label(s).

Note, a scope conveying WRITE permissions does not also convey READ permissions.

Clarifications / Discussion

1. Do you need write perms on the resource you’re creating?

   e.g., want to create a with label:Foo.read – need both system/*.write and grouping/Foo.read (or system/*.read), but not grouping/Foo.write?

2. Do you need read perms on the resource you’re creating? No.

3. If a resource only has a Foo.read label, then what are the WRITE permissions? (requires grouping/*.write)
4. Challenge of default permissions (what can someone do if no labels attached) and explicitly allowing all and only allowing “super entity”

Use Cases / Requirements