Label-based Access Control

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:

1. 1.
   http://terminology.hl7.org/CodeSystem/v3-Confidentiality
2. 2.
   http://terminology.hl7.org/CodeSystem/v3-ActCode

Security Labels in the request context

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

1. 1.
   From the scope claim of a JWT.
2. 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 in space-separated list format.

A security label must be defined using the pattern system|code.
Claim scope example: "http://terminology.hl7.org/CodeSystem/v3-ActCode|PSY https://terminology.hl7.org/CodeSystem/v3-Confidentiality|M"

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. 1.
   Resource-level access control. Decides whether a resource itself is accessible to a requester.
2. 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).

Resource accessibility matrix

Resource-element level access (masking)

To perform masking:

1. 1.
   The resource itself should have the http://terminology.hl7.org/CodeSystem/v3-ActCode|PROCESSINLINELABEL security label in its meta.
2. 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

request_method: GET
uri: /fhir/Encounter/enc-1
security_labels:
  - system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality
    code: R
    display: Restricted
  - system: http://terminology.hl7.org/CodeSystem/v3-ActCode
    code: FMCOMPT
    display: financial management compartment

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:
  extension:
    - url: http://terminology.hl7.org/CodeSystem/data-absent-reason
      valueCode: masked

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

request_method: GET
uri: /fhir/Encounter/enc-1
security_labels:
  - system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality
    code: R
    display: Restricted
  - system: http://terminology.hl7.org/CodeSystem/v3-ActCode
    code: FMCOMPT
    display: financial management compartment

resourceType: Encounter
id: enc-1
status: finished
class:
  system: http://terminology.hl7.org/CodeSystem/v3-ActCode
  code: IMP
subject:
  extension:
    - url: http://terminology.hl7.org/CodeSystem/data-absent-reason
      valueCode: masked

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

Postman Demo

Try Label-based Access Control in Postman. Please read the description in the Postman collection before running requests.
RUN in Postman

See also