Configure field-level access

This document describes field-level access controls and how to set them on a Logging bucket. Field-level access controls let you hide individual LogEntry fields from users of a Google Cloud project, providing you a more granular way to control the logs data a user can access.

Overview

Logging uses field-level access control to hide LogEntry fields from users of a Google Cloud project who don't have the required permissions to view the fields. Compared to logs views, which hide the entire LogEntry, field-level access controls hide individual fields of the LogEntry. You can set both field-level access controls and log views permissions on a Logging bucket. You restrict and manage field-level access control using the Google Cloud CLI.

To restrict access to log fields, you do the following:

• Configure the restricted LogEntry fields on a log bucket.
• Give only those users who need to view the restricted fields the logging.fieldAccessor IAM role for that field path, or a role that contains similar permissions.

Logging checks IAM permissions when a user queries logs from a bucket that has restricted fields set. Any fields with ACLs configured are denied to users without the corresponding logging.FieldAccessor for that field, meaning:

• The user receives a permission-denied error if they attempt to directly query the restricted fields.
• Global searches don't consider the contents of the denied fields.
• Any returned LogEntry results omit the restricted fields.

Restricted fields

You can restrict access to any combination of the following LogEntry fields:

LogEntry field	Nested fields of the parent LogEntry field
jsonPayload	user-defined
textPayload	None
protoPayload	service-specific
httpRequest	httpRequest nested fields
labels	user-defined
sourceLocation	sourceLocation nested fields

Restricting access to a field with nested fields (like jsonPayload, or specific jsonPayload sub-paths) also restricts access to any of their nested paths.

Before you begin

Before you get started with setting field-level access controls, do the following:

• Verify that gcloud --version reports the version of the Google Cloud CLI as version 362.0.0 or higher.

  To install the latest version of the gcloud CLI, run the following update command:

  gcloud components update

  For instructions on how to install the gcloud CLI, see Installing Google Cloud CLI.

• Verify that you have one of the following IAM roles for the Google Cloud project that contains the bucket:

  • roles/logging.configWriter
  • roles/logging.admin
  • roles/owner

  For information on setting IAM roles, see the Logging Access control guide.

Setting field-level access control

Field-level restrictions are configured at the bucket level, and can be applied to an existing bucket or when creating a new bucket.

Note: If you configure field-level access controls and upgrade a log bucket to use Log Analytics, then you must have access to all fields to query a view by using the Log Analytics interface. However, you can query the logs by using the Logs Explorer even when you don't have access to all fields. BigQuery doesn't honor field-level access controls. Therefore, if you create a linked BigQuery dataset, then you can query all fields in the logs.

Note: Live tailing isn't supported for buckets with field-level access controls.

Restricting fields on a new bucket

To restrict log fields when creating a new log bucket, run the following gcloud CLI command:

gcloud logging buckets create BUCKET_NAME --location=LOCATION \
--description=DESCRIPTION --restricted-fields=RESTRICTED_FIELDS

Example command:

gcloud logging buckets create new-log-bucket --location=global \
--description="New bucket with restricted fields" --restricted-fields="jsonPayload.data.ssn,httpRequest.status"

Restricting fields on an existing bucket

To restrict log fields on an existing log bucket, run the following gcloud CLI command:

gcloud logging buckets update BUCKET_NAME --location=LOCATION \
--restricted-fields=RESTRICTED_FIELDS

Example command:

gcloud logging buckets update my-existing-log-bucket --location=global \
--restricted-fields="jsonPayload.data.ssn,httpRequest.status"

If you want to add fields to your existing restrictions, your update command must relist the entire set of restricted fields. Building on the previous example, if you wanted to restrict access to the field jsonPayload.data.entryDate in addition to the already-restricted fields jsonPayload.data.ssn and httpRequest.status, your command would look like this:

gcloud logging buckets update my-existing-log-bucket --location=global \
--restricted-fields="jsonPayload.data.ssn,jsonPayload.data.entryDate,httpRequest.status"

If you didn't relist the already-restricted fields, and just listed jsonPayload.data.entryDate, then both jsonPayload.data.ssn and httpRequest.status would be removed as restricted fields.

Managing access to restricted fields

By default, Logging hides all restricted fields from users who don't have the logging.fieldAccessor role or a role with similar permissions. Logging exposes the restricted fields to users who have both the permission to view logs in the bucket and the logging.fieldAccessor role.

You can modify the default behavior to limit subsets of restricted fields to specific users.

Granting permission on all restricted fields

To grant users permission to all restricted fields, give users the logging.fieldAccessor role or a custom role that contains the logging.fieldAccessor role.

Console

To give users the logging.fieldAccessor role using the Google Cloud console, complete the following steps:

1. In the Edit permissions pane, select Log Field Accessor.

2. Select Add condition.

   

3. Enter a title and description in the Title and Description fields.

4. Select the Condition editor tab and enter the following expression:

   resource.name.extract("locations/global/buckets/{bucket}/") == "BUCKET_NAME"
   

   

5. Select Save.

The Identity and Access Management permissions are updated immediately.

gcloud

To give users the logging.fieldAccessor role using the gcloud CLI, complete the following steps:

1. Edit the policy.json file:

   gcloud projects get-iam-policy PROJECT_ID --format=json > policy.json
   

2. Update the policy.json file with additional bindings:

   "bindings": [
       {
         "condition": {
           "description": "DESCRIPTION",
           "expression": "resource.name.extract(\"locations/global/buckets/{bucket}/\") == 'BUCKET_NAME'",
           "title": "TITLE"
         },
         "members": [
           "user":"[e-mail]"
         ],
         "role": "roles/logging.fieldAccessor"
       }
   ]
   

   Example binding:

   "bindings": [
     {
       "condition": {
         "description": "Grants access to all restricted fields in a log bucket",
         "expression": "resource.name.extract(\"locations/global/buckets/{bucket}/\") == 'log-bucket-with-sensitive-data'",
         "title": "Log bucket condition for restricted fields"
       },
       "members": [
         "user":"[e-mail]"
       ],
       "role": "roles/logging.fieldAccessor"
     }
   ]
   

The Identity and Access Management permissions are updated immediately.

Granting permissions on a subset of restricted fields

To grant users permissions on a subset of the restricted fields, set the fields users can access when granting them the logging.fieldAccessor role or when setting a custom role that contains the logging.fieldAccessor.

Note the following:

• The spelling and capitalization of the restricted field as it appears in the bucket configuration must match the spelling and capitalization of the restricted field in the IAM permission name. For example, if you set the restricted field as jsonPayload, you must grant permission on the jsonPayload field, not the Jsonpayload field.

• Field paths, including map-key strings, are case-sensitive, but protobuf field paths can be expressed either as case-insensitive snake case (snake_case) or case-sensitive camel case (camelCase).

  For example, logName is a field in the LogEntry protobuf; log_name refers to the same field. The field jsonPayload.fooBar refers to a different field than jsonPayload.foo_bar, since field names beneath jsonPayload are map string keys; however, it does refer to json_payload.fooBar.

  Even if field paths are valid references to the same field, you must match the spelling, capitalization, and case when you configure restrictions and IAM permissions. If, for instance, you specify a restriction on jsonPayload.foo, you must configure IAM permissions for jsonPayload.foo and not for json_payload.foo.

For further information on valid log field types, see Logging query launguage: values and conversions.

Console

To give users access to a restricted field using the Google Cloud console, complete the following steps:

1. In the Edit permissions pane, select Log Field Accessor.

2. Select Add condition.

   

3. Enter a title and description in the Title and Description fields.

4. Select the Condition editor tab and enter the following expression:

   resource.name.extract("locations/global/buckets/BUCKET_ID /fields/{field}") == "RESTRICTED_FIELD"
   

   

5. Select Save.

The Identity and Access Management permissions are updated immediately.

gcloud

To give users access to a restricted field using the gcloud CLI, complete the following steps:

1. Edit the policy.json file:

   gcloud projects get-iam-policy PROJECT_ID --format=json > policy.json
   

2. Update the policy.json file with additional bindings:

   "bindings": [
       {
         "condition": {
           "description": "DESCRIPTION",
           "expression": "resource.name.extract(\"locations/global/buckets/BUCKET_NAME/fields/{field}\") == 'RESTRICTED_FIELD'",
           "title": "TITLE"
         },
         "members": [
           "user":"[e-mail]"
         ],
         "role": "roles/logging.fieldAccessor"
       }
   ]
   

   Example binding:

   "bindings": [
     {
       "condition": {
         "description": "Give access to one restricted field that contains sensitive information",
         "expression": "resource.name.extract(\"locations/global/buckets/my-log-bucket/fields/{field}\") == 'jsonPyaload.data.ssn'",
         "title": "Access to restricted field"
       },
       "members": [
         "user":"[e-mail]"
       ],
       "role": "roles/logging.fieldAccessor"
     }
   ]
   

The Identity and Access Management permissions are updated immediately.

Example output

The following examples show how a LogEntry appears for users who have been restricted from accessing a subset of the LogEntry fields.

Assume a bucket has had the following fields restricted:

• jsonPayload
• httpRequest
• labels

For users with permission to access all the restricted fields, the LogEntry looks like the following:

For users with permission to access only the restricted jsonPayload LogEntry field, the LogEntry looks like the following:

For users without permission to view any of the restricted fields, the LogEntry looks like the following:

If a user enters a global restriction that would return a LogEntry with a restricted field, Logging hides the entire LogEntry instead of only the field.

Listing restricted fields

To list the restricted fields on a log bucket, run the following gcloud CLI command:

gcloud logging buckets describe  BUCKET_ID  --location=LOCATION

Example command:

gcloud logging buckets describe my-log-bucket --location=global

Quotas and limits

When setting up and using field-level access control, note the following:

• Number of restricted fields: You can restrict up to 20 fields for each log bucket.
• Size of restricted fields: The restricted field path must be smaller than 800 B in length.

For more information on the limits that might apply to your usage of Cloud Logging, see Quotas and limits.