Access control with IAM

Stay organized with collections Save and categorize content based on your preferences.

This document describes how you use Identity and Access Management (IAM) roles and permissions to control access to logs data in the Logging API, the Logs Explorer, and the Google Cloud CLI.

Overview

IAM permissions and roles determine your ability to access logs data in the Logging API, the Logs Explorer, and the Google Cloud CLI.

A role is a collection of permissions. You can't grant a principal permissions directly; instead, you grant them a role. When you grant a role to a principal, you grant them all the permissions that the role contains. You can grant multiple roles to the same principal.

To use Logging within a Google Cloud resource, such as a Google Cloud project, folder, bucket, or organization, a principal must have an IAM role that contains the appropriate permissions.

Predefined roles

IAM provides predefined roles to grant granular access to specific Google Cloud resources and prevent unwanted access to other resources. Google Cloud creates and maintains these roles and automatically updates their permissions as necessary, such as when Logging adds new features.

The following table lists the predefined roles for Logging. For each role, the table displays the role title, description, contained permissions, and the lowest-level resource type where the roles can be granted. You can grant the predefined roles at the Cloud project level or, in most cases, any type higher in the Google Cloud hierarchy. To scope the Logs Buckets Writer or Logs View Accessor roles more tightly to the bucket level, you use resource attributes for IAM Conditions.

To get a list of each individual permission contained in a role, see Getting the role metadata.

Role Permissions

(roles/logging.admin)

Provides all permissions necessary to use all features of Cloud Logging.

Lowest-level resources where you can grant this role:

  • Project

Contains 15 owner permissions

logging.buckets.copyLogEntries

logging.buckets.create

logging.buckets.delete

logging.buckets.get

logging.buckets.list

logging.buckets.undelete

logging.buckets.update

logging.cmekSettings.*

  • logging.cmekSettings.get
  • logging.cmekSettings.update

logging.exclusions.*

  • logging.exclusions.create
  • logging.exclusions.delete
  • logging.exclusions.get
  • logging.exclusions.list
  • logging.exclusions.update

logging.fields.access

logging.links.*

  • logging.links.create
  • logging.links.delete
  • logging.links.get
  • logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logEntries.*

  • logging.logEntries.create
  • logging.logEntries.download
  • logging.logEntries.list

logging.logMetrics.*

  • logging.logMetrics.create
  • logging.logMetrics.delete
  • logging.logMetrics.get
  • logging.logMetrics.list
  • logging.logMetrics.update

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.*

  • logging.logs.delete
  • logging.logs.list

logging.notificationRules.*

  • logging.notificationRules.create
  • logging.notificationRules.delete
  • logging.notificationRules.get
  • logging.notificationRules.list
  • logging.notificationRules.update

logging.operations.*

  • logging.operations.cancel
  • logging.operations.get
  • logging.operations.list

logging.privateLogEntries.list

logging.queries.*

  • logging.queries.create
  • logging.queries.delete
  • logging.queries.get
  • logging.queries.list
  • logging.queries.listShared
  • logging.queries.share
  • logging.queries.update
  • logging.queries.updateShared

logging.sinks.*

  • logging.sinks.create
  • logging.sinks.delete
  • logging.sinks.get
  • logging.sinks.list
  • logging.sinks.update

logging.usage.get

logging.views.*

  • logging.views.access
  • logging.views.create
  • logging.views.delete
  • logging.views.get
  • logging.views.list
  • logging.views.listLogs
  • logging.views.listResourceKeys
  • logging.views.listResourceValues
  • logging.views.update

resourcemanager.projects.get

resourcemanager.projects.list

(roles/logging.bucketWriter)

Ability to write logs to a log bucket.

Lowest-level resources where you can grant this role:

  • Project

logging.buckets.write

(roles/logging.configWriter)

Provides permissions to read and write the configurations of logs-based metrics and sinks for exporting logs.

Lowest-level resources where you can grant this role:

  • Project

Contains 10 owner permissions

logging.buckets.create

logging.buckets.delete

logging.buckets.get

logging.buckets.list

logging.buckets.undelete

logging.buckets.update

logging.cmekSettings.*

  • logging.cmekSettings.get
  • logging.cmekSettings.update

logging.exclusions.*

  • logging.exclusions.create
  • logging.exclusions.delete
  • logging.exclusions.get
  • logging.exclusions.list
  • logging.exclusions.update

logging.links.*

  • logging.links.create
  • logging.links.delete
  • logging.links.get
  • logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logMetrics.*

  • logging.logMetrics.create
  • logging.logMetrics.delete
  • logging.logMetrics.get
  • logging.logMetrics.list
  • logging.logMetrics.update

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.list

logging.notificationRules.*

  • logging.notificationRules.create
  • logging.notificationRules.delete
  • logging.notificationRules.get
  • logging.notificationRules.list
  • logging.notificationRules.update

logging.operations.*

  • logging.operations.cancel
  • logging.operations.get
  • logging.operations.list

logging.sinks.*

  • logging.sinks.create
  • logging.sinks.delete
  • logging.sinks.get
  • logging.sinks.list
  • logging.sinks.update

logging.views.create

logging.views.delete

logging.views.get

logging.views.list

logging.views.update

resourcemanager.projects.get

resourcemanager.projects.list

(roles/logging.fieldAccessor)

Ability to read restricted fields in a log bucket.

Lowest-level resources where you can grant this role:

  • Project

Contains 1 owner permission

logging.fields.access

(roles/logging.linkViewer)

Ability to see links for a bucket.

logging.links.get

logging.links.list

(roles/logging.logWriter)

Provides the permissions to write log entries.

Lowest-level resources where you can grant this role:

  • Project

logging.logEntries.create

(roles/logging.privateLogViewer)

Provides permissions of the Logs Viewer role and in addition, provides read-only access to log entries in private logs.

Lowest-level resources where you can grant this role:

  • Project

Contains 2 owner permissions

logging.buckets.get

logging.buckets.list

logging.exclusions.get

logging.exclusions.list

logging.links.get

logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logEntries.list

logging.logMetrics.get

logging.logMetrics.list

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.list

logging.privateLogEntries.list

logging.queries.create

logging.queries.delete

logging.queries.get

logging.queries.list

logging.queries.listShared

logging.queries.update

logging.sinks.get

logging.sinks.list

logging.usage.get

logging.views.access

logging.views.get

logging.views.list

resourcemanager.projects.get

(roles/logging.viewAccessor)

Ability to read logs in a view.

Lowest-level resources where you can grant this role:

  • Project

Contains 1 owner permission

logging.logEntries.download

logging.views.access

logging.views.listLogs

logging.views.listResourceKeys

logging.views.listResourceValues

(roles/logging.viewer)

Provides access to view logs.

Lowest-level resources where you can grant this role:

  • Project

logging.buckets.get

logging.buckets.list

logging.exclusions.get

logging.exclusions.list

logging.links.get

logging.links.list

logging.locations.*

  • logging.locations.get
  • logging.locations.list

logging.logEntries.list

logging.logMetrics.get

logging.logMetrics.list

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.list

logging.operations.get

logging.operations.list

logging.queries.create

logging.queries.delete

logging.queries.get

logging.queries.list

logging.queries.listShared

logging.queries.update

logging.sinks.get

logging.sinks.list

logging.usage.get

logging.views.get

logging.views.list

resourcemanager.projects.get

The following sections provide additional information to help you decide which roles apply to your principals' use cases.

Logging roles

  • To let a user perform all actions in Logging, grant the Logging Admin (roles/logging.admin) role.

  • To let a user create and modify logging configurations, such as sinks, buckets, views, links, log-based metrics, or exclusions, grant the Logs Configuration Writer (roles/logging.configWriter) role.

  • To let a user read logs in the _Required and _Default buckets, use the Logs Explorer, and use the Log Analytics page, grant one of the following roles:

    • For access to all logs in the _Required bucket, and access to the _Default view on the _Default bucket, grant the Logs Viewer (roles/logging.viewer) role.
    • For access to all logs in the _Required and _Default buckets, including data access logs, grant the Private Logs Viewer (roles/logging.privateLogViewer) role.
  • To let a user read logs by using a log view on a user-defined bucket, grant the Logs View Accessor (roles/logging.viewAccessor) role. You can restrict authorization to a specific view on a specific bucket by using an IAM condition; see Reading logs from a bucket for an example.

  • To give a user access to restricted LogEntry fields, if any, in a given bucket, grant the Logs Field Accessor (roles/logging.fieldAccessor) role. For more information, see Field-level access control.

  • To let a user write logs by using the Logging API, grant the Logs Writer (roles/logging.logWriter) role. This role doesn't grant viewing permissions.

  • To let the service account of a sink route logs to a bucket in a different Google Cloud project, grant the service account the Logs Buckets Writer (roles/logging.bucketWriter) role. For instructions about granting permissions to a service account, see Set destination permissions.

Project-level roles

  • To give view access to most Google Cloud services, grant the Viewer (roles/viewer) role.

    This role includes all permissions granted by the Logs Viewer (roles/logging.viewer) role.

  • To give editor access to most Google Cloud services, grant the Editor (roles/editor) role.

    This role includes all permissions granted by the Logs Viewer (roles/logging.viewer) role, and the permissions to write log entries, delete logs, and create log-based metrics. However, this role doesn't let users create sinks or read Data Access audit logs that are in the _Default bucket.

  • To give full access to most Google Cloud services, grant the Owner (roles/owner) role.

Granting roles

To learn how to grant a role to a principal, see Granting, changing, and revoking access.

You can grant multiple roles to the same user. To get a list of the permissions contained in a role, see Getting the role metadata.

If you're trying to access a Google Cloud resource and lack the necessary permissions, then contact the principal who is listed as the Owner for the resource.

Custom roles

To create a custom role with Logging permissions, do the following:

For more information on custom roles, see Understanding IAM custom roles.

API permissions

Logging API methods require specific IAM permissions. The following table lists the permissions needed by the API methods.

If you're interested in logs held in Google Cloud organizations, billing accounts, and folders, then note that those resources have their own API methods for logs and sinks. Rather than repeating all the methods in the table, only the projects methods are shown individually.

Logging method Required permission Resource type
billingAccounts.logs.* logging.logs.* (See projects.logs.*) billing accounts
billingAccounts.sinks.* logging.sinks.* (See projects.sinks.*.) billing accounts
billingAccounts.locations.buckets.* logging.buckets.* (See projects.locations.buckets.*.) billing accounts
entries.list logging.logEntries.list or
logging.privateLogEntries.list
projects, organizations,
folders, billing accounts
entries.tail logging.logEntries.list or
logging.privateLogEntries.list
projects, organizations,
folders, billing accounts
entries.write logging.logEntries.create projects, organizations,
folders, billing accounts
folders.logs.* logging.logs.* (See projects.logs.*) folders
folders.sinks.* logging.sinks.* (See projects.sinks.*) folders
folders.locations.buckets.* logging.buckets.* (See projects.locations.buckets.*) folders
monitoredResourceDescriptors.list (none) (none)
organizations.logs.* logging.logs.* (See projects.logs.*) organizations
organizations.sinks.* logging.sinks.* (See projects.sinks.*) organizations
organizations.locations.buckets.* logging.buckets.* (See projects.locations.buckets.*) organizations
projects.exclusions.create logging.exclusions.create projects
projects.exclusions.delete logging.exclusions.delete projects
projects.exclusions.get logging.exclusions.get projects
projects.exclusions.list logging.exclusions.list projects
projects.exclusions.patch logging.exclusions.update projects
projects.logs.list logging.logs.list projects
projects.logs.delete logging.logs.delete projects
projects.sinks.list logging.sinks.list projects
projects.sinks.get logging.sinks.get projects
projects.sinks.create logging.sinks.create projects
projects.sinks.update logging.sinks.update projects
projects.sinks.delete logging.sinks.delete projects
projects.locations.buckets.list logging.buckets.list projects
projects.locations.buckets.get logging.buckets.get projects
projects.locations.buckets.patch logging.buckets.update projects
projects.locations.buckets.create logging.buckets.create projects
projects.locations.buckets.delete logging.buckets.delete projects
projects.locations.buckets.undelete logging.buckets.undelete projects
projects.metrics.list logging.logMetrics.list projects
projects.metrics.get logging.logMetrics.get projects
projects.metrics.create logging.logMetrics.create projects
projects.metrics.update logging.logMetrics.update projects
projects.metrics.delete logging.logMetrics.delete projects

Google Cloud console permissions

The following table lists the permissions needed to use the Logs Explorer.

In the table, a.b.{x,y} means a.b.x and a.b.y.

Console activity Required permissions
Minimal read-only access logging.logEntries.list
logging.logs.list
logging.logServiceIndexes.list
logging.logServices.list
resourcemanager.projects.get
Add ability to view Data Access audit logs Add logging.privateLogEntries.list
Add ability to view log-based metrics Add logging.logMetrics.{list, get}
Add ability to view sinks Add logging.sinks.{list, get}
Add ability to view logs usage Add logging.usage.get
Add ability to exclude logs Add logging.exclusions.{list, create, get, update, delete}
Add ability to use sinks Add logging.sinks.{list, create, get, update, delete}
Add ability to create log-based metrics Add logging.logMetrics.{list, create, get, update, delete}
Add ability to save queries Add logging.queries.{list, create, get, update, delete}
Add ability to share queries Add logging.queries.share
Add ability to use recent queries Add logging.queries.{create, list}

Command-line permissions

gcloud logging commands are controlled by IAM permissions.

To use any of the gcloud logging commands, principals must have the serviceusage.services.use permission.

A principal must also have the IAM role that corresponds to the log's resource, and to the use case. For details, see command-line interface permissions.

The following list describes the predefined roles and corresponding permissions for managing your linked BigQuery datasets:

The previously listed roles and permissions only apply to Logging pages, such as the Log Analytics page. If you use the BigQuery interface to manage your datasets, you might need separate BigQuery roles and permissions. See Access control with IAM for BigQuery for more information.

Log-routing permissions

For information about setting access controls when creating and managing sinks to route logs, see Configure sinks: Set destination permissions.

Note that managing exclusion filters is integrated with configuring sinks. All permissions related to managing sinks, including setting exclusion filters, are included in the logging.sinks.* permissions. When creating a custom role that includes permissions to manage exclusion filters, add the logging.sinks.* permissions to the role instead of adding the logging.exclusions.* permissions.

After your log entries have been routed to a supported destination, access to the log copies is controlled entirely by IAM permissions and roles on the destinations: Cloud Storage, BigQuery, or Pub/Sub.

Log-based metrics permissions

Following is a summary of the common roles and permissions that a principal needs to access log-based metrics:

  • Logs Configuration Writer (roles/logging.configWriter) lets principals list, create, get, update, and delete log-based metrics.

  • Logs Viewer (roles/logging.viewer) lets principals view existing metrics. You can also add the logging.logMetrics.get and logging.logMetrics.list permissions to a custom role.

  • Monitoring Viewer (roles/monitoring.viewer) lets principals read TimeSeries data. You can also add the monitoring.timeSeries.list permission to a custom role.

  • Logging Admin (roles/logging.admin), Project Editor (roles/editor), and Project Owner (roles/owner) let principals create log-based metrics (logging.logMetrics.create).

Log-based alerts permissions

Following is a summary of the common roles and permissions that a principal needs to create and manage log-based alerts:

  • Logging Admin (roles/logging.admin). Specifically, a principal needs the following permissions to read logs and to manage Logging notification rules:

    • logging.logs.list
    • logging.logEntries.list
    • logging.notificationRules.create
    • logging.notificationRules.update

    These permissions are included in the Logging Admin role. If you don't want to grant this role, then do the following:

  • Monitoring AlertPolicy Editor (roles/monitoring.alertPolicyEditor) and Monitoring NotificationChannel Editor (roles/monitoring.notificationChannelEditor) include the permissions necessary to manage the alerting policies and notification channels used by log-based alerts:

    • monitoring.alertPolicies.{create, delete, get, list, update}
    • monitoring.notificationChannelDescriptors.{get, list}
    • monitoring.notificationChannels.{create, delete, get, list, sendVerificationCode, update, verify}

    The necessary permissions are also included in the Monitoring Editor (roles/monitoring.editor) and Monitoring Admin (roles/monitoring.admin) roles.

    If you don't want to grant any of these roles, then create a custom role and include the permissions in the Monitoring AlertPolicy Editor and Monitoring NotificationChannel Editor roles.

Logging access scopes

Access scopes are the legacy method of specifying permissions for the service accounts on your Compute Engine VM instances.

The following access scopes apply to the Logging API:

Access scope Permissions granted
https://www.googleapis.com/auth/logging.read roles/logging.viewer
https://www.googleapis.com/auth/logging.write roles/logging.logWriter
https://www.googleapis.com/auth/logging.admin Full access to the Logging API.
https://www.googleapis.com/auth/cloud-platform Full access to the Logging API and to all other enabled Google Cloud APIs.

For information on using this legacy method to set your service accounts' levels of access, see Service account permissions.