Configuring consent policies using attributes

This page describes how to configure consent policies and attributes.

Consent policies are used by the Consent Management API to represent consent granted by an end-user or through an organizational guideline. Consent policies are the building blocks of consent resources. Each consent resource can contain up to 10 consent policies. A consent policy consists of RESOURCE attributes that describe what the policy applies to, and REQUEST attributes that define an authorization rule that determines under what conditions the policy is valid. For more information on consent policies, see Policy representation.

The Consent Management API uses attributes to define the consent and privacy taxonomy that a consent store can understand. Attributes are used to describe the consents being stored and the data that is being managed. Access determination requests also use attributes to describe the requests that are being made.

The attributeDefinition resources are the resources within a consent store that determine what consent attributes the Consent Management API can process. A consent store can contain up to 200 attribute definition resources. Each attribute definition has one of the following attribute types:

  • A RESOURCE attribute is an attribute whose value is determined by the properties of the data or action. For example, whether data is de-identified or identifiable. This type of attribute is used to describe what a consent policy applies to, to describe data registered with user data mappings, and to narrow the scope of some access determination requests to specific classes of resources.
  • A REQUEST attribute is an attribute whose value is determined by requester's identity or purpose. For example, professions that are consented for use, such as researchers or care providers. This type of attribute is used to write the authorization rule of a consent policy, and to specify the proposed use in an access determination request.

An attributeDefinition resource represents a single attribute with up to 500 attribute values. Attribute values represent the possible values that an attribute can have. For an example, see Policy representation.

Additional attribute values can be added to an attribute definition over time, but cannot be removed. Referential integrity of attribute definitions is enforced as related to consent resources. This means that some fields of an attribute definition cannot be changed or deleted while that attribute definition is being referenced by the latest revision of a consent resource.

The following diagram shows the process for creating consent attributes in a new consent store:

attribute definitions

To create all the attribute definitions that your consent and privacy taxonomy requires, repeat the process shown in Creating a RESOURCE attribute definition and Creating a REQUEST attribute definition.

Creating a RESOURCE attribute definition

To create a RESOURCE attribute definition, use the projects.locations.datasets.consentStores.attributeDefinitions.create method. Make a POST request and specify the following information in the request:

  • The name of the parent consent store.
  • A name for the attribute definition that's unique in the parent consent store. The name can be any lower or upper case letter, numbers, and underscores. It must not be a reserved keyword within the Common Expression Language (CEL).
  • The category of the attribute, in this case RESOURCE
  • The possible values that this attribute can represent
  • An access token

curl

The following sample shows a POST request using curl that creates a RESOURCE attribute named data_identifiable with values identifiable and de-identified:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
      'description': 'whether the data is identifiable',
      'category': 'RESOURCE',
      'allowed_values': [
        'identifiable',
        'de-identified'
      ],
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=data_identifiable"

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/data_identifiable",
    "description": "whether the data is identifiable",
    "category": "RESOURCE",
    "allowedValues": [
      "identifiable",
      "de-identified"
    ]
}

PowerShell

The following sample shows a POST request using Windows PowerShell that creates a RESOURCE attribute named data_identifiable with values identifiable and de-identified:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
      'description': 'whether the data is identifiable',
      'category': 'RESOURCE',
      'allowed_values': [
        'identifiable',
        'de-identified'
      ]
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=data_identifiable" | Select-Object -Expand Content

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/data_identifiable",
    "description": "whether the data is identifiable",
    "category": "RESOURCE",
    "allowedValues": [
      "identifiable",
      "de-identified"
    ]
}

Creating a REQUEST attribute definition

To create a REQUEST attribute definition, use the projects.locations.datasets.consentStores.attributeDefinitions.create method. Make a POST request and specify the following information in the request:

  • The name of the parent consent store.
  • A name for the attribute definition that's unique in the parent consent store. The name can be any Unicode string of 1 to 256 characters consisting of numbers, letters, underscores, dashes, and periods but it can't start with a number.
  • The category of the attribute, in this case REQUEST.
  • The possible values that this attribute can represent.
  • An optional set of default values that will be applied to consent policies. Setting a value for this field will configure your consent store to assume consent policies include this attribute and value if this attribute is not otherwise specified in that policy. This field should only be set if specifically required for your use-case.
  • An access token.

curl

The following sample shows a POST request using curl that creates a REQUEST attribute named requester_identity:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
      'description': 'what groups are consented for access',
      'category': 'REQUEST',
      'allowed_values': ['internal-researcher', 'external-researcher', 'clinical-admin'],
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=requester_identity"

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/requester_identity",
    "description": "what groups are consented for access",
    "category": "REQUEST",
    "allowedValues": [
      "internal-researcher",
      "external-researcher",
      "clinical-admin"
    ]
}

PowerShell

The following sample shows a POST request using Windows PowerShell that creates a REQUEST attribute named requester_identity:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
      'description': 'what groups are consented for access',
      'category': 'REQUEST',
      'allowed_values': ['internal-researcher', 'external-researcher', 'clinical-admin']
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=requester_identity" | Select-Object -Expand Content

If the request is successful, the server returns a response similar to the following sample in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/requester_identity",
    "description": "what groups are consented for access",
    "category": "REQUEST",
    "allowedValues": [
      "internal-researcher",
      "external-researcher",
      "clinical-admin"
    ]
}