FHIR access data model and control system

This page describes how to use the Cloud Healthcare API FHIR access control system to manage and secure your healthcare data. You can use FHIR access control to define consent policies, control data access based on user roles and context, and enforce these policies in a FHIR store.

Data model overview

The data model for access control is represented by Consent resources. They define the rules that apply and which data the rules apply to.

FHIR Consent

The access rules are expressed through FHIR Consent resources. FHIR Consent is a type of FHIR Resource that captures a healthcare consumer's choices. It permits or denies a set of actors to perform actions affecting the consumer for a specific purpose from a specified environment over a period of time. For example, a consumer could be a healthcare patient, anyone acting on behalf of a healthcare patient, or another individual who enters into a consent agreement.

The actions recorded in a FHIR Consent may be broad and deal with more than just the consumer's electronic health record (EHR) data, however for the purposes of consent within the Cloud Healthcare API, the focus is on actions related to data access and the enforcement of those actions is limited to reading FHIR data from a FHIR store.

A Consent resource has a status that indicates the current state of the consent. Although a FHIR store may contain many consents in different states, the Cloud Healthcare API only enforces consents that are in the active state. Consents in any other state have no effect on enforcement. If a consent is given on behalf of a patient, the consent is recorded as being granted by a performer.

Policy type

Cloud Healthcare API supports the following consent policy types:

• Patient consent: is associated with a Patient using Consent.patient (STU3, R4) and binds as many data as defined by the patient compartment (STU3, R4).

• Admin policy: is not associated with any Patient and must have an extension URL https://g.co/fhir/medicalrecords/ConsentAdminPolicy. This policy type could bind to a subset or all resources in the store specified by the resource criteria. Admin policy sets the default policy for all binding resources in the store.

• Admin cascading policy: a type of Admin policy that requires the extension URL https://g.co/fhir/medicalrecords/CascadingPolicy and the Admin policy extension URL. You can bind this policy type to a compartment of resources that match the resource criteria. Has the following limitations:

  • Only supports Patient (STU3, R4) or Encounter (STU3, R4) as compartment base.
  • The FHIR store where the policy is enforced must have disableReferentialIntegrity set to false. Contact Cloud Support to use this feature for non-referential integrity FHIR store.

You can combine policy types at the same resource level to permit or deny access to a resource. If a patient's consent is missing, the Admin policy can approve access to a resource.

Consent directive

Consent directives are instructions that are encoded within a FHIR Consent that permit or deny data access to an authorized entity such as a grantee or an accessor. A single FHIR Consent may encode multiple consent directives. Each directive provides the following:

• Enforcement type: a permit or deny instruction.

• Action: the permission(s) covered by this directive. Only access is supported to provide read-only access.

• Accessor criteria: a set of attributes that identify the API requester covered by the directive.

• Resource criteria: a set of attributes that identify the resources covered by the directive.

Accessor criteria

The Cloud Healthcare API supports three properties of an accessor for use within a consent directive and to match against an accessor making a data access request. There must be a case-sensitive exact match to have a directive enforced on the accessor as part of access determination offered by the FHIR server.

These properties are encoded as follows:

• Actor: represents an individual, group, or access role that identifies the accessor or a characteristic of the accessor.

• Purpose: represents the intent of use of the data.

• Environment: represents an abstract identifier that describes the environment or conditions under which the accessor is acting.

For example, an accessor may be represented by the following properties:

• Actor: Practitioner/123

• Purpose: ETREAT or access for emergency treatment purposes

• Environment: Application/abc

In this example, these properties represent a doctor who is accessing data when performing emergency treatment using a software application called abc.

provision.actor and provision.purpose are defined as part of the FHIR standard, whereas Environment is https://g.co/fhir/medicalrecords/Environment. Note that this link is not resolvable.

All consent directives must specify an actor to be enforced but need not always specify a purpose or an environment. For example, if no environment is specified in the consent directive, then the directive matches any environment that is not already covered by other consent directives.

Resource criteria

The Cloud Healthcare API supports the following elements as part of the consent resource:

• Resource type (STU3, R4): represents the type that the consent policy binds to, for example, Encounter, Observation, or Immunization.

• Resource ID (STU3, R4): represents the ID that the consent policy binds to.

• Data source: represents the origin of the resource as identified by the resource meta.source (only available in R4).

• Data tag: represents the custom label of the resource as described in the resource meta.tag (STU3, R4).

• Security label: represents security labels that define affected resources as identified in the meta.security field (STU3, R4). The following code systems are supported:

  • Confidentiality: hierarchical values ranked from unrestricted to most restricted: U, L, M, N, R, V. If a consent permits a security label of R then it applies to all resources that are labeled R or lower. If a consent denies a security label R then it applies to all resources that are at least as sensitive as R.

  • ActCode: exact string matching on security code.

Note: Examples of how different policies can be represented through Consent resource can be found in How-To Docs.

Access workflow

This figure illustrates the end-to-end journey of a request to a FHIR access control enabled store. An external token with the consent scope (left) is used by application (#3) when making a request to the FHIR store with access control enabled (right).

Consent scope

When making a data access request, an accessor operates within a particular Consent Scope that represents their actor, purpose, and environment properties related to any FHIR HTTP request. The values for these properties must be a case-sensitive match with those provided within a consent for them to affect the enforcement's access determination.

An accessor can have multiple actor identifiers that are relevant for making an access determination. Likewise, there can be multiple purposes or environments that are relevant within a particular consent context. Therefore, all relevant accessor properties should be provided as part of a FHIR HTTP request to properly represent that accessor for consent purposes.

For example, the consent scope for a given data request may be the following:

actor/Practitioner/444 actor/Group/999 purp/v3/TREAT purp/v3/ETREAT env/App/abc

This represents a nurse or a doctor known as practitioner 444 who is a member of group 999 which represents practitioners from a department within a specific hospital. The practitioner is there to provide regular treatment, but possibly also deal with emergency treatment as part of these actions. The practitioner is using a software application called abc.

The consent scope is provided as a Request consent scope as part of an accessor's data request.

Request consent scope

FHIR requests use FHIR HTTP request headers to receive the accessor's consent scope. This consent scope contains a set of actor, purpose, and environment values to reflect the accessor's current identity, qualifications, intent of use, and environmental constraints in which the accessor operates. There may be more than one of each of these properties that represent an accessor's consent scope at any one time.

Consent consent scope entries are defined as follows:

• actor/{type}/{ID}: an actor property where the resource type is provided along with the ID. Examples of type include the following:

  • Practitioner
  • Group
  • Patient

  For example, if a store of the format projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID/fhirStores/STORE_ID calls the API, a local reference to a Practitioner/123 actor resolves to projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID/fhirStores/STORE_ID/fhir/Practitioner/123.

• purp/v3/{value}: a purpose property where value is a member of the FHIR Purpose of Use (v3) value set or its extension. Examples of value include:

  • TREAT
  • ETREAT
  • HRESCH

• env/{type}/{value}: an environment property where type and value are custom strings with no predefined taxonomy. Examples of type and value include:

  • App/my_app_1
  • Net/VPN

In addition, FHIR HTTP request headers can also receive special scopes, such as btg and bypass which are defined as follows:

• btg: Break the glass (or BTG) lets you, as a human user, skip consent checks in case of emergencies. It should be used in emergencies only and is subject to post-audit review. As a result, btg requires at least one actor.
• bypass: Allows trusted users (such as an administrator) or trusted applications (such as a ML-training pipeline) to operate on the FHIR store without consent authorization. Hence, bypass requires at least one actor and one env.

Note: Requests using btg or bypass are annotated differently in the consentMode of the audit logs. To facilitate data governance checks, these two special privileges should only be used for their intended purposes.

Access enforcement and access determination

In a complex healthcare environment where multiple policies and consents coexist, enforcing access and determining access permissions can be a daunting task. Various stakeholders may have different expectations and requirements regarding the use and disclosure of patient information. Navigating this intricate landscape necessitates a clear understanding of how access is enforced and the underlying logic that governs access determination.

Aggregated consent policy

A healthcare consumer, such as a patient or an administrator, may have multiple consent directives contained within a single Consent resource. Consent resources may contain a mix of permit and deny provision.type directives. By default, a user may have any number of Consent resources but up to 200 active Consent resources are enforced at a time. See Constraints and limitations for more details.

All the consent directives are extracted from active Consent resources for a given user to make a set of aggregated consent rules.

Consent directive properties

Consent enforcement is limited to at most one purpose and at most one environment per provision entry.

The following rules describe the principles for the joint access control of patient consent, admin policy and admin cascading policy:

• All resources are denied access by default if there is no matching directive.

• If the requested resource does not exist, only resource type and resource ID are identifiable. All other resource criteria and the resource owner are unknown, the following rule applies in the listing order:

  • If the resource type belongs to the patient-compartment or encounter-compartment: the access is denied.

  • Otherwise:

    • If there is an admin policy denying the accessor criteria regardless of the other resource criteria, the access is denied.

    • If there is an admin policy permitting the accessor criteria for the identifiable resource criteria (i.e. resource type and resource id), a "resource not found" error is returned.

    • All other cases, the access is denied.

• Admin policies are the default policies used for matching resources in the store.

• Resources that don't belong to any patient are determined by only the admin policies.

• Resources that are in the patient compartment (STU3, R4) or encounter compartment (STU3, R4) need at least one permit consent directive per patient or admin policy or admin cascading policy and no deny consent directive from patient and admin policy and admin cascading policy. This condition is needed from all the patients named on the resources to be accessed by the requestor.

  • Some resources may support multiple patient participants. For example, Appointment provides a list of participants which may be patients. All patients named on such resources must permit access to the accessor using consent directives, otherwise the resources aren't returned. If a resource has a permission from an encounter cascading policy, where this encounter references a patient through the subject field (STU3, R4), then the resource is considered to be permitted by the patient.

The described rules are summarized by the following pseudo-code:

Joint access control

if resource does not exist
  if resource is a patient-compartment or encounter-compartment resource:
    return "deny"
  else:
    if there is any admin policy denies access for accessor criteria regardless of resource criteria other than resource type and resource ID:
      return "deny"
    else if there is any admin policy permits access for accessor criteria based on the identifiable resource criteria:
      return "resource not found"
    else:
      return "deny"
else:
  let patients = list of patient references named in the patient compartment eligible fields of the requested resource
  if there is any matching deny from either patients's consents or admin policy or admin cascading policy:
    return "deny"
  if there is matching admin policy permits access:
    return "permit"
  if all patients have matching patient consents or admin cascading consent that permit access or are subject of encounters which permit the access through encounter cascading policy:
    return "permit"
  else:
    return "deny"
end

The FHIR store checks consent permission at the per resource level. Any reference in a resource is not resolved and cascaded for consent access check purposes. For example, consider a patient identified by Patient/f001 that allows a Practitioner to access their entire MedicationRequest resource, but not the Patient/f001 resource itself due to the patient privacy. In this scenario, the Practitioner can see the entire MedicationRequest resource which includes a subject field referring to the Patient/f001 resource, but cannot see the contents of the Patient/f001 resource even, for example, when performing a FHIR search using _include.

Conflict resolution

Conflicts are possible between various permit and deny directives. If two conflicting directives match a resource, the conflict is resolved using the deny wins over permit model.

Only active consents are included for consent enforcement.

Resource access enforcement logic

When making a consent-aware request to a FHIR store, access control occurs in the following order:

1. The Cloud Healthcare API checks the permissions on the Google Cloud service account (or the principal) configured in the proxy. If the service account has the correct IAM permissions to perform the requested FHIR method on the FHIR store, the request proceeds.

2. If consent enforcement is enabled in the FHIR store configuration and the consent-aware HTTP headers are present, then the Cloud Healthcare API enforces consent access policies for Patient Compartment resources. The enforcement of consent access policies is based on the consent scopes provided in the request, according to the consent directives captured by the most recent execution of ApplyConsents and ApplyAdminConsents.

   Note: If the FHIR store configuration defines the consent header handling as REQUIRED_ON_READ, consent access control is enforced (and rejected) even without the consent aware headers.

The following rules apply when making a consent-aware request to a FHIR store:

• Provide at least one actor consent scope relevant for the consenting actions taken.

• Provide any additional purpose and environment scopes relevant for the consenting actions taken.

• If the number of consent scope entries exceeds the supported limits, an error is returned.

• If you call a method that accesses multiple resources (for example, the fhir.Patient-everything, fhir.Encounter-everything, fhir.executeBundle, or fhir.search method), consent enforcement applies to each individual resource. However, there is a subtle difference between these multi-resource access methods:

  • fhir.executeBundle reading multiple resources receives "Consent access denied or the resource being accessed does not exist" for individual resource without consent permissions (see examples in the Get FHIR resources with consent scope).

  • fhir.search skips resources without consent permissions and does not return consent access denied error, even for searching by _id (see examples in the Search FHIR resources with consent scope).

  • fhir.Patient-everything and fhir.Encounter-everything behave similarly to fhir.search, except that they return "Consent access denied or the resource being accessed does not exist" if the caller does not have consent permission on the requested Patient or Encounter resource, respectively.

Consent access determination

A consent directive has at most one actor, at most one purpose, and at most one environment whereas consent scope may have multiple of each. Some consent directives don't specify all three accessor properties, in which case any consent scope property value may match depending on conflict resolution rules. As result, a consent scope may match more than one consent directive.

If the consent scope of a request includes two or more entries of the same consent scope type (actor, purpose, or environment), then the consent scope possibly matches multiple consent directives. Some consent directives don't specify a purpose or an environment. Therefore the consent scope must be also matched against consent directives that don't specify these scope types.

For example, setting the consent scope to actor/Practitioner/123 actor/Group/999 purp/v3/TREAT env/App/abc matches against any of the following permit or deny consent directives:

• actor/Practitioner/123 purp/v3/TREAT env/App/abc
• actor/Practitioner/123 purp/v3/TREAT
• actor/Practitioner/123 env/App/abc
• actor/Practitioner/123
• actor/Group/999 purp/v3/TREAT env/App/abc
• actor/Group/999 purp/v3/TREAT
• actor/Group/999 env/App/abc
• actor/Group/999

What's next

• Learn how to enforce access on a FHIR store.