Label-based Access Control

This pages explains how security labels access control works in Aidbox

What are security labels?

A security label is a concept attached to a resource or bundle that provides specific security metadata about the information it is fixed to.

What is Label-based Access Control?

Label-based Access Control engine provides a mechanism to restrict access to bundles, resources, or resource elements depending on permissions associated with a request. When security labels are included in the request context, they allow the requester to access information in accordance with those labels.

Two security label code systems are currently supported:

Security Labels in the request context

There are two ways the security labels appear in the request context:

  1. From the scope claim of a JWT.

  2. From the Aidbox User’s property securityLabel.

scope claim in JWT

Aidbox parses the scope claim and fetches security labels. There can be multiple security labels on the scope.

A security label must be defined using the pattern system|code. For example, http://terminology.hl7.org/CodeSystem/v3-ActCode|PSY.

User.securityLabel

If the request context is associated with an Aidbox user, Aidbox tries to get security labels from the User.securityLabel.

For example, the user resource contains two security labels.

resourceType: User
id: some-user-id
securityLabel:
  - system: http://terminology.hl7.org/CodeSystem/v3-ActCode
    code: PSY
  - system: https://terminology.hl7.org/CodeSystem/v3-Confidentiality
    code: M

Expanding confidentiality security label

The security label for confidentiality is hierarchical. The code may contain several others.

For example, the R code expands to R, N, M, L, and U.

How access control works

Security Labels access control is done in two steps:

  1. Resource-level access control. Decides whether a resource itself is accessible to a requester.

  2. Resource-element level access (masking). Decides whether some elements of the resource should be hidden from the requester. Masking is applied only if the resource-level access control permits access to the resource.

Resource-level access control

If the security labels of the request context intersect with the security labels of the resource, the requester can access the resource. Otherwise, there is no access. Consider marking non-sensitive data with the security label U (unrestricted).

If a resource has no security labels, no one can access the resource.

Resource accessibility matrix

Resource security labelsRequest security labelsAccessibility

Confidentiality: V

Confidentiality: R

no access

Confidentiality: R

Confidentiality: R

available

Confidentiality: L

Confidentiality: R

available

Confidentiality: R Sensitivity: PSY

Confidentiality: R

available

Sensitivity: PSY

Confidentiality: R

no access

Sensitivity: HIV

Confidentiality: R

no access

no security labels

Confidentiality: R

no access

Confidentiality: V

Confidentiality: R Sensitivity: PSY

no access

Confidentiality: R

Confidentiality: R Sensitivity: PSY

available

Confidentiality: L

Confidentiality: R Sensitivity: PSY

available

Confidentiality: R Sensitivity: PSY

Confidentiality: R Sensitivity: PSY

available

Sensitivity: PSY

Confidentiality: R Sensitivity: PSY

available

Sensitivity: HIV

Confidentiality: R Sensitivity: PSY

no access

no security labels

Confidentiality: R Sensitivity: PSY

no access

Confidentiality: V

Sensitivity: PSY

no access

Confidentiality: R

Sensitivity: PSY

no access

Confidentiality: L

Sensitivity: PSY

no access

Confidentiality: R Sensitivity: PSY

Sensitivity: PSY

available

Sensitivity: PSY

Sensitivity: PSY

available

Sensitivity: HIV

Sensitivity: PSY

no access

no security labels

Sensitivity: PSY

no access

Resource-element level access (masking)

To perform masking:

  1. The resource itself should have the http://terminology.hl7.org/CodeSystem/v3-ActCode|PROCESSINLINELABEL security label in its meta.

  2. The resource properties should be tagged with the Inline Security Label extension.

Masking examples

The requestor has access to all Encounter fields but the subject.

resourceType: Encounter
id: enc-1
meta:
  security:
    - code: PROCESSINLINELABEL
      system: http://terminology.hl7.org/CodeSystem/v3-ActCode
    - code: L
      system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality
status: finished
class:
  system: http://terminology.hl7.org/CodeSystem/v3-ActCode
  code: IMP
subject:
  reference: "Patient/pt-1"
  extension:
    - url: http://hl7.org/fhir/uv/security-label-ds4p/StructureDefinition/extension-inline-sec-label
      valueCoding:
        code: CTCOMPT
        system: http://terminology.hl7.org/CodeSystem/v3-ActCode
        display: care teamcompartment

Remove security labels from the response

To prevent security labels from appearing in the outcome, set the strip labels env:

BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS=true

Stripping examples

The security labels from meta.security and _status fields have been removed from the outcome.

resourceType: Encounter
id: enc-1
meta:
  security:
    - code: PROCESSINLINELABEL
      system: http://terminology.hl7.org/CodeSystem/v3-ActCode
    - code: L
      system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality
status: finished
_status:
  extension:
    - url: http://hl7.org/fhir/uv/security-label-ds4p/StructureDefinition/extension-inline-sec-label
      valueCoding:
        code: FMCOMPT
        system: http://terminology.hl7.org/CodeSystem/v3-ActCode
        display: financial management compartment
class:
  system: http://terminology.hl7.org/CodeSystem/v3-ActCode
  code: IMP
subject:
  reference: "Patient/pt-1"
  extension:
    - url: http://hl7.org/fhir/uv/security-label-ds4p/StructureDefinition/extension-inline-sec-label
      valueCoding:
        code: CTCOMPT
        system: http://terminology.hl7.org/CodeSystem/v3-ActCode
        display: care teamcompartment

Superadmin Role with Label-based Access Control

As mentioned earlier, resources without security labels cannot be accessed. This can affect the functionality of the Aidbox UI console, making resources like User, Client, Access Policy, etc. inaccessible until they are labeled. To avoid the need to label all resources displayed in the UI console, use the superadmin Role. Create a Role resource with the name superadmin and reference to the User used to log in to the UI console before enabling Label-based Access Control.

POST /Role
content-type: text/yaml
accept: text/yaml

name: superadmin
user:
  id: <user-id>
  resourceType: User

Last updated