Before you begin
Set up necessary FHIR store configurations and resources and enforce access control. For more information, see Control access to FHIR resources.
Overview
The
ExplainDataAccess
method lets you find out which actors have what access to which a given
resource based on the
enforced
policies and consents.
The
ExplainDataAccess
method can help you answer questions like these:
- Who can access a given resource?
- For what purpose can these actors access this resource?
- What are the Consent resources enforcing the said access?
Understand data access
To use
ExplainDataAccess,
pass in identifier of the resource of interest. The response provides a list of
consent scopes
(actor, purpose, environment) that are permitted or denied to access the
provided resource. The exceptions to a consent
scopes are
listed in the
ExplainDataAccessConsentScope.exceptions
field. An exceptions can happen when one policy permit actor to access
Observation/ob1 for any purpose, while there exist a deny policy that denies
actor from accessing this resource with research purpose. Each consent
scopes
contains information about which consent resource enforced such access through
ExplainDataAccessConsentScope.enforcing_consents,
this helps you understand the details of the enforced and applicable consents on
this resource.
There is a limit of 1000 permit consent directives and 1000 deny consent directives. This limit constraints the number of consent scopes applied to a given resource. If the number of consent scopes exceed the limit, the ExplainDataAccessResponse.warning field contains relevant message.
The following is an example request that explain data access for a given resource:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:explainDataAccess?resource_id=Observation/7473784b-46a8-470c-b9a6-fe38a01025aa"
You should receive a JSON response similar to the following:
{
"consentScopes":[
{
"decision":"CONSENT_DECISION_TYPE_PERMIT",
"enforcingConsents":[
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/73c54e8d-2789-403b-9dee-13085c5d5e34",
"type":"CONSENT_POLICY_TYPE_PATIENT",
"enforcementTime":"2024-02-09T02:48:02.721589Z",
"patientConsentOwner":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2",
"matchingAccessorScopes":[
{
"actor":"Practitioner/12942879-f89f-41ae-aa80-0b911b649833",
"purpose":"v3/ETREAT",
"environment":"*"
}
]
}
],
"accessorScope":{
"actor":"Practitioner/12942879-f89f-41ae-aa80-0b911b649833",
"purpose":"v3/ETREAT",
"environment":"*"
}
},
{
"decision":"CONSENT_DECISION_TYPE_PERMIT",
"enforcingConsents":[
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/10998b60-a252-405f-aa47-0702554ddc8e",
"type":"CONSENT_POLICY_TYPE_PATIENT",
"enforcementTime":"2024-02-09T02:48:02.721589Z",
"patientConsentOwner":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2",
"matchingAccessorScopes":[
{
"actor":"Practitioner/12942879-f89f-41ae-aa80-0b911b649833",
"purpose":"*",
"environment":"App/123"
}
]
}
],
"accessorScope":{
"actor":"Practitioner/12942879-f89f-41ae-aa80-0b911b649833",
"purpose":"*",
"environment":"App/123"
}
},
{
"decision":"CONSENT_DECISION_TYPE_PERMIT",
"enforcingConsents":[
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/5c8e3f8a-9fd5-480d-a08e-f29b89feccde",
"type":"CONSENT_POLICY_TYPE_ADMIN",
"enforcementTime":"2024-02-09T02:50:03.973252Z",
"matchingAccessorScopes":[
{
"actor":"Practitioner/12942879-f89f-41ae-aa80-0b911b649833",
"purpose":"v3/BIORCH",
"environment":"App/golden"
}
]
}
],
"accessorScope":{
"actor":"Practitioner/12942879-f89f-41ae-aa80-0b911b649833",
"purpose":"v3/BIORCH",
"environment":"App/golden"
}
}
]
}
In this example, The following access were permitted:
Practitioner/12942879-f89f-41ae-aa80-0b911b649833withv3/ETREATpurpose in all environments, granted by patient consent.Practitioner/12942879-f89f-41ae-aa80-0b911b649833with all purpose inApp/123environment, granted by patient consent.Practitioner/12942879-f89f-41ae-aa80-0b911b649833withv3/BIORCHpurpose inApp/goldenenvironment, granted by admin consent.
Additional ExplainDataAccess Response Example
{
"consentScopes":[
{
"decision":"CONSENT_DECISION_TYPE_PERMIT",
"accessorScope":{
"actor":"Practitioner/doctor",
"purpose":"*",
"environment":"*"
},
"enforcingConsents":[
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/pc1",
"type":"CONSENT_POLICY_TYPE_PATIENT",
"enforcementTime":"2024-01-02T14:10:55.271144Z",
"patientConsentOwner":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/p1",
"matchingAccessorScopes":[
{
"actor":"Practitioner/doctor",
"purpose":"*",
"environment":"*"
}
]
}
],
"exceptions":[
{
"decision":"CONSENT_DECISION_TYPE_DENY",
"accessorScope":{
"actor":"Practitioner/doctor",
"purpose":"v3/TREAT",
"environment":"*"
},
"enforcingConsents":[
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/ac1",
"type":"CONSENT_POLICY_TYPE_ADMIN",
"enforcementTime":"2024-01-02T14:10:55.229196Z",
"matchingAccessorScopes":[
{
"actor":"Practitioner/doctor",
"purpose":"v3/TREAT",
"environment":"*"
}
]
},
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/ac1-dup",
"type":"CONSENT_POLICY_TYPE_ADMIN",
"variants":["CONSENT_VARIANT_CASCADE"],
"enforcementTime":"2024-01-02T14:10:55.229196Z",
"cascadeOrigins":[
"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/p1"
],
"matchingAccessorScopes":[
{
"actor":"Practitioner/doctor",
"purpose":"v3/TREAT",
"environment":"*"
}
]
}
]
}
]
},
{
"decision":"CONSENT_DECISION_TYPE_DENY",
"accessorScope":{
"actor":"Practitioner/doctor",
"purpose":"v3/TREAT",
"environment":"*"
},
"enforcingConsents":[
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/ac1",
"type":"CONSENT_POLICY_TYPE_ADMIN",
"enforcementTime":"2024-01-02T14:10:55.229196Z",
"matchingAccessorScopes":[
{
"actor":"Practitioner/doctor",
"purpose":"v3/TREAT",
"environment":"*"
}
]
},
{
"consentResource":"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/ac1-dup",
"type":"CONSENT_POLICY_TYPE_ADMIN",
"variants":["CONSENT_VARIANT_CASCADE"],
"enforcementTime":"2024-01-02T14:10:55.229196Z",
"cascadeOrigins":[
"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/p1"
],
"matchingAccessorScopes":[
{
"actor":"Practitioner/doctor",
"purpose":"v3/TREAT",
"environment":"*"
}
]
}
]
}
]
}
In this example, Practitioner/doctor is permitted to access the resource in
all environments and for all purposes except for v3/TREAT . The consent
enforcing policy is a patient consent Consent/pc1 , and the consent enforcing
policy are admin policies (Consent/ac1 and Consent/ac1-dup ).
Consent/ac1-dup is an admin cascading policy that matched resource's owner
Patient/p1 .