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 the jsonPayload
field, which
also restricts access to its nested paths.
You can also restrict access to the leaf fields of the following:
For example, you can restrict access to the labels.check_id
field.
Before you begin
Before you get started with setting field-level access controls, do the following:
Verify that
gcloud --version
reports version 362.0.0 or later.To install the latest version of the gcloud CLI, run the
gcloud components update
command:gcloud components update
For instructions on how to install the gcloud CLI, see Installing Google Cloud CLI.
Run the
gcloud config set
to configure the default Google Cloud project for your Google Cloud CLI commands. Before running the command, make the following replacement:- PROJECT_ID: The identifier of the project.
Command:
gcloud config set project PROJECT_ID
Verify that you have one of the following IAM roles for the Google Cloud project that contains the bucket:
For information on setting IAM roles, see the Logging Access control guide.
Set 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.
Restrict fields on a new bucket
To restrict log fields when creating a new log bucket, run the
gcloud logging buckets create
command.
Before running the command, make the following replacements:
- BUCKET_ID: The name or ID of the log bucket.
- LOCATION: The location of the log bucket.
- DESCRIPTION: The description of the log bucket.
- RESTRICTED_FIELDS: The comma-separated list of fields being restricted.
Command:
gcloud logging buckets create BUCKET_ID --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
gcloud logging buckets update
command:
gcloud logging buckets update BUCKET_ID --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:
-
In the Google Cloud console, go to the IAM page:
If you use the search bar to find this page, then select the result whose subheading is IAM & Admin.
- Select the principal, and click Edit.
- In the Edit permissions pane, select Log Field Accessor for the role.
- Select Add IAM Condition.
- Enter a title and description in the Title and Description fields.
Select the Condition editor tab and enter the following expression:
resource.name.extract("locations/global/buckets/{bucket}/") == "BUCKET_ID"
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:
To save the current IAM policy information in a file, run the
gcloud projects get-iam-policy
command and save the output in a file:gcloud projects get-iam-policy PROJECT_ID --format=json > policy.json
The previous command saves the information in a file called
policy.json
.Update the
policy.json
file with additional bindings.In the following, the
expression
field only lists a log bucket. Therefore, all fields for log entries stored in that log bucket are accessible to principals listed in themembers
section."bindings": [ { "condition": { "description": "DESCRIPTION", "expression": "resource.name.extract(\"locations/global/buckets/{bucket}/\") == 'BUCKET_ID'", "title": "TITLE" }, "members": [ PRINCIPAL ], "role": "roles/logging.fieldAccessor" } ]
In the previous sample, the fields have the following meanings:
- PRINCIPAL: An identifier for the principal that you want to
grant the role to. Principal identifiers usually have the following form:
PRINCIPAL-TYPE:ID
. For example,user:my-user@example.com
. For a full list of the formats thatPRINCIPAL
can have, see Principal identifiers. In themembers
field of thepolicy.json
file, use the format"PRINCIPAL-TYPE":"ID"
. - DESCRIPTION: A description of the condition.
- TITLE: A title for the condition.
- PRINCIPAL: An identifier for the principal that you want to
grant the role to. Principal identifiers usually have the following form:
To apply the updated
policy.json
file, run thegcloud projects set-iam-policy
command:gcloud projects set-iam-policy PROJECT_ID policy.json
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 thejsonPayload
field, not theJsonpayload
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 theLogEntry
protobuf;log_name
refers to the same field. The fieldjsonPayload.fooBar
refers to a different field thanjsonPayload.foo_bar
, since field names beneathjsonPayload
are map string keys; however, it does refer tojson_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 example, you specify a restriction on
jsonPayload.foo
, then you must configure IAM permissions forjsonPayload.foo
and not forjson_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:
-
In the Google Cloud console, go to the IAM page:
If you use the search bar to find this page, then select the result whose subheading is IAM & Admin.
- Select the principal, and click Edit.
- In the Edit permissions pane, select Log Field Accessor for the role.
- Select Add IAM Condition.
- Enter a title and description in the Title and Description fields.
Select the Condition editor tab and enter the following expression:
resource.name.extract("locations/global/buckets/BUCKET_ID/fields/{field}") == "RESTRICTED_FIELDS"
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:
To save the IAM information in a file, run the
gcloud projects get-iam-policy
command and save the output in a file:gcloud projects get-iam-policy PROJECT_ID --format=json > policy.json
The previous command saves the information in a file called
policy.json
.Update the
policy.json
file with additional bindings.In the following, the
expression
field lists specific fields. Therefore, only principals listed in themembers
section have access to those fields of the log entries that are stored in the specified log bucket."bindings": [ { "condition": { "description": "DESCRIPTION", "expression": "resource.name.extract(\"locations/global/buckets/BUCKET_ID/fields/{field}\") == 'RESTRICTED_FIELDS'", "title": "TITLE" }, "members": [ PRINCIPAL ], "role": "roles/logging.fieldAccessor" } ]
In the previous sample, the fields have the following meanings:
- PRINCIPAL: An identifier for the principal that you want to
grant the role to. Principal identifiers usually have the following form:
PRINCIPAL-TYPE:ID
. For example,user:my-user@example.com
. For a full list of the formats thatPRINCIPAL
can have, see Principal identifiers. In themembers
field of thepolicy.json
file, use the format"PRINCIPAL-TYPE":"ID"
. - DESCRIPTION: A description of the condition.
- TITLE: A title for the condition.
- PRINCIPAL: An identifier for the principal that you want to
grant the role to. Principal identifiers usually have the following form:
To apply the updated
policy.json
file, run thegcloud projects set-iam-policy
command:gcloud projects set-iam-policy PROJECT_ID policy.json
The Identity and Access Management permissions are updated immediately.
Example
Assume a log bucket restricts the jsonPayload
field, a specific label,
and a specific httpRequest
subfield. The following occurs when a user
is examining their log entries
For users with permission to access all the restricted fields, all fields in a log entry are visible.
For users with permission to access only the restricted
jsonPayload
LogEntry
field, all unrestricted fields are visible, and thejsonPayload
field is visible.For users without permission to view any of the restricted fields, only the unrestricted fields are visible.
If a user writes a query with a global restriction, then log entries that contain a restricted field are omitted from the response.
Listing restricted fields
To list the restricted fields on a log bucket, run the following
gcloud logging buckets describe
:
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.