Field-level access control

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

Overview

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

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 log 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 will not 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:

Setting field-level access control

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

Restricting fields on a new log bucket

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

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

Example command:

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

Restricting fields on an existing log bucket

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

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

Example command:

gcloud alpha 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 alpha 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 log 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.

    Add Log Field Accessor permission.

  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"
    

    Add condition to permission.

  5. Select Save.

The Identity and Access Management permissions are updated immediately.

gcloud

To give users the logging.fieldAccessor role using the gcloud tool, 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":"USER_ID@DOMAIN.com"
          ],
          "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":"222larabrown@gmail.com"
        ],
        "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 log 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 Cloud Console, complete the following steps:

  1. In the Edit permissions pane, select Log Field Accessor.
  2. Select Add condition.

    Add Log Field Accessor permission.

  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"
    

    Add a subset of the restricted fields.

  5. Select Save.

The Identity and Access Management permissions are updated immediately.

gcloud

To give users access to a restricted field using the gcloud tool, 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":"USER_ID@DOMAIN.com"
          ],
          "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":"222larabrown@gmail.com"
        ],
        "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 log 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:

All log fields shown.

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

Only jsonPayload field shown.

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

All fields restricted.

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 tool command:

gcloud alpha logging buckets describe  BUCKET_ID  --location=LOCATION

Example command:

gcloud alpha 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.