Notes

A user only requires write permission to a resource to add security labels, and does not need read or write permission for the labels they are adding. So a user may add foo.read without having read access to the foo category themselves. This enables those with write access to resources to grant permissions to categories they may not themselves have rights to.

This does mean that users are able to modify security labels on a resource such that they no longer have read and/or write access themselves. This may be intentional, however if this occurs accidentally the grouping/*.write scope (PERM_WRITE authority) will allow a user to write to any resource regardless of its other security labels. Typically this scope is given to highly trusted users or administrators and allows them to correct security labels in this scenario.

When creating a resource only the system/*.write scope (FHIR_WRITE authority) is required - no security labels are in play on the server as the resource does not yet exist on the server. Similar to a resource update scenario, a user creating a resource can specify security labels in the resource meta on creation and need not have permission for these labels themselves in order to add these labels in resource creation.

If a resource is created with no security labels on a server with resource-level access control enabled, any user with the system/*.read (FHIR_READ authority) and/or system/*.write scope (FHIR_WRITE authority) will be able to read and/or modify the resource. I.e. no security labels on a resource implies no resource-level authority is necessary and only API-level authority is required for that resource until a security label is added.

Write permissions do not imply read permissions - i.e. adding the label foo.write does not imply foo.read which must additionally be explicitly added if the foo category requires both read and write permission.

Configuration

Set ontoserver.security.audience on each Ontoserver instance to a unique value, typically its base FHIR URL:

How audience-prefixed permissions work

To grant a permission to a specific Ontoserver instance, prepend the instance's ontoserver.security.audience value directly to the permission value in the JWT token. No additional separator character is inserted; the resulting authority is exactly the audience value followed immediately by the permission value.

Each Ontoserver instance recognises permissions that are either:

• Unprefixed — applies to all Ontoserver instances that accept the token
• Prefixed with this instance's audience — applies only to this instance

Permissions prefixed with a different instance's audience are ignored.

For example, if ontoserver.security.audience=https://author.example.com/fhir, then the authority value https://author.example.com/fhirFHIR_WRITE is recognised as FHIR_WRITE by that instance only.

Which permissions support audience prefixing?

The following authorities claim values support audience prefixing across all endpoints:

The scope claim values for /api and /synd endpoints (onto/api.read, onto/api.write, onto/synd.read, onto/synd.write) also support audience prefixing.

Note: The SMART-style scope values system/*.read, system/*.write, and system/CodeSystem.x-upload-external do not support audience prefixing. When audience disambiguation is needed for FHIR endpoint permissions, use the equivalent authorities values (FHIR_READ, FHIR_WRITE, FHIR_CS_X_UE).

Resource-level permissions (grouping/ scopes and PERM_ authorities) do not support audience prefixing.

Example

Given an authoring server with audience https://author.example.com/fhir and a production server with audience https://tx.example.com/fhir, a token with:

{
  "authorities": [
    "https://author.example.com/fhirFHIR_WRITE",
    "https://author.example.com/fhirFHIR_READ",
    "https://tx.example.com/fhirFHIR_READ",
    "SYND_READ"
  ]
}

Would grant:

• FHIR_WRITE is only granted to the authoring server because it is prefixed with the authoring server's audience.
• FHIR_READ is granted to both because each has its own audience-prefixed grant.
• SYND_READ is granted to both because it is unprefixed — unprefixed permissions apply everywhere.

Alternative: single-audience tokens

If the authorization server can issue tokens for a single audience at a time (based on the requested audience), then audience-prefixing permissions is not necessary. The authorization server issues each token containing only the permissions relevant to the requested Ontoserver instance, and standard unprefixed permission values are used.

This approach is simpler but requires the client to obtain a separate token for each Ontoserver instance.

User

1. A user U has a maximum level of permission that cannot be increased through granting of category permissions. e.g., They only have READ access and this cannot be changed.

   User U would have permission system/*.read but NOT system/*.write. If the user also has permissions grouping/X.write then this will not allow them WRITE access to any resources because they lack the base system/*.write permission.

2. User U belongs to communities X and Y.

   This would be managed in the Authorization server. Ontoserver knows nothing about group membership and it does not need to be included in the JWT Token.

3. Members of X can write some resources but only read others; need to be able to specify read/write permissions for a community separately.

   This is supported by the separate .read and .write forms of the security labels.

4. You must have write permissions on an existing resource in order to set / update its permissions.

   For any WRITE action there are either one or two resource instances involved, the latest (active) instance in the the server at the time of the action, and the desired instance in the server following successful execution of the action.

   Permissions are checked against the existing instance only, not the new instance.

Actions

1. I want to make the foo Resource available for reading to community X

   * foo.meta.security.label = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|X.read
   

2. I want to make the foo Resource available for reading to all (both authenticated and non-authenticated)

   * foo.meta.security.label = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|*.read
   

3. I want to make the foo Resource available for reading only to authenticated entities (regardless of community membership)

   This can be achieved by running Ontoserver NOT in “anonymous read” mode (i.e., ontoserver.security.readOnly.fhir=false) and not specifying any security labels on the resource.

   If security labels must be used on the resource (for example to control write access) then a default.read (any term can be used, default is simply an example) security label can be added to the resource and configured into the authorisation server to be added by default to all authenticated users. This second approach with work with ontoserver.security.readOnly.fhir set to true or false.

4. I want to make the foo Resource available in the syndication feed to community Y

   FHIR Resources in the syndication feed use the normal FHIR read instance URL and are thus subject to normal authorisation constraints.

   * foo.meta.security.label = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|Y.read
   
   /synd/setSyndicationStatus?resource=[Resource]/foo&status=true
   

5. I want to make the foo Resource available for reading to community X and for writing to community Y

   Note that community Y is also given READ permission in the following as would normally be expected

   * foo.meta.security.label[0] = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|X.read
   * foo.meta.security.label[1] = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|Y.write
   * foo.meta.security.label[2] = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|Y.read
   

6. I want to make the foo Resource available for reading to all and for writing to community Y only

   * foo.meta.security.label[0] = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|*.read
   * foo.meta.security.label[1] = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|Y.write
   * foo.meta.security.label[2] = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|Y.read
   

7. I want to create a Resource only visible to community X

   * foo.meta.security.label = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|X.read
   

8. My CodeSystem resource requires agreement to licence X (for read access) here and in all downstream Terminology Solutions

   Create and apply category permissions for licence X products.

   * foo.meta.security.label = http://ontoserver.csiro.au/CodeSystem/ontoserver-permissions|X.read