Access control with IAM

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 Trusted Cloud resource, such as a Trusted 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 Trusted Cloud resources and prevent unwanted access to other resources. Trusted Cloud by S3NS 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 Trusted Cloud project level or, in most cases, any type higher in the resource hierarchy. To restrict the Logs View Accessor role to a log view on a bucket, use resource attributes for IAM Conditions.

To get a list of all individual permissions 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

logging.buckets.copyLogEntries

logging.buckets.create

logging.buckets.createTagBinding

logging.buckets.delete

logging.buckets.deleteTagBinding

logging.buckets.get

logging.buckets.list

logging.buckets.listEffectiveTags

logging.buckets.listTagBindings

logging.buckets.undelete

logging.buckets.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.logEntries.route

logging.logMetrics.*

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

logging.logScopes.*

  • logging.logScopes.create
  • logging.logScopes.delete
  • logging.logScopes.get
  • logging.logScopes.list
  • logging.logScopes.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.deleteShared
  • logging.queries.getShared
  • logging.queries.listShared
  • logging.queries.share
  • logging.queries.updateShared
  • logging.queries.usePrivate

logging.settings.*

  • logging.settings.get
  • logging.settings.update

logging.sinks.*

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

logging.sqlAlerts.*

  • logging.sqlAlerts.create
  • logging.sqlAlerts.update

logging.usage.get

logging.views.*

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

observability.scopes.get

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

logging.buckets.create

logging.buckets.createTagBinding

logging.buckets.delete

logging.buckets.deleteTagBinding

logging.buckets.get

logging.buckets.list

logging.buckets.listEffectiveTags

logging.buckets.listTagBindings

logging.buckets.undelete

logging.buckets.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.logScopes.*

  • logging.logScopes.create
  • logging.logScopes.delete
  • logging.logScopes.get
  • logging.logScopes.list
  • logging.logScopes.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.settings.*

  • logging.settings.get
  • logging.settings.update

logging.sinks.*

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

logging.sqlAlerts.*

  • logging.sqlAlerts.create
  • logging.sqlAlerts.update

logging.views.create

logging.views.delete

logging.views.get

logging.views.getIamPolicy

logging.views.list

logging.views.update

observability.scopes.get

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

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

logging.logEntries.route

(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

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.privateLogEntries.list

logging.queries.getShared

logging.queries.listShared

logging.queries.usePrivate

logging.sinks.get

logging.sinks.list

logging.usage.get

logging.views.access

logging.views.get

logging.views.list

observability.scopes.get

resourcemanager.projects.get

(roles/logging.serviceAgent)

Grants a Cloud Logging Service Account the ability to create and link datasets.

bigquery.datasets.create

bigquery.datasets.get

bigquery.datasets.link

(roles/logging.sqlAlertWriter)

Ability to write SQL Alerts.

logging.sqlAlerts.*

  • logging.sqlAlerts.create
  • logging.sqlAlerts.update

(roles/logging.viewAccessor)

Ability to read logs in a view.

Lowest-level resources where you can grant this role:

  • Project

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.logScopes.get

logging.logScopes.list

logging.logServiceIndexes.list

logging.logServices.list

logging.logs.list

logging.operations.get

logging.operations.list

logging.queries.getShared

logging.queries.listShared

logging.queries.usePrivate

logging.sinks.get

logging.sinks.list

logging.usage.get

logging.views.get

logging.views.list

observability.scopes.get

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, grant the Logs Configuration Writer (roles/logging.configWriter) role. This role lets you create or modify any of the following:

  • To let a user read logs in the _Required and _Default buckets or to use the Logs Explorer 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 in all log views that are in a project, grant them the IAM role of roles/logging.viewAccessor on the project.

  • To let a user only read logs in a specific log view, you have two options:

    • Create an IAM policy for the log view, and then add an IAM binding to that policy which grants the principal access to the log view.

    • Grant the principal the IAM role of roles/logging.viewAccessor on the project that contains the log view, but attach an IAM condition to restrict the grant to the specific log view.

    For information about creating log views and granting access, see Configure log views on a log bucket.

  • 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 Trusted Cloud project, grant the service account the Logs Bucket 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 Trusted Cloud by S3NS 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 Trusted Cloud by S3NS 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 and delete logs. However, this role doesn't let users create sinks, read Data Access audit logs that are in the _Default bucket, or read logs that are in user-defined log buckets.

  • To give full access to most Trusted Cloud by S3NS 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 Trusted 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 about custom roles, see Understanding IAM custom roles.

Cloud Logging permissions

The following table is a partial list of the permissions needed for specific features of Cloud Logging. This table can help you identify the permissions that you need to use pages like 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
View Data Access audit logs logging.privateLogEntries.list
View sinks logging.sinks.{list, get}
View logs usage logging.usage.get
Download logs logging.logEntries.{list, download}

Only one of these permissions is necessary to download logs. Roles containing the permissions to download logs must be granted at a project-level. You can't download logs if a role containing these permissions is granted in the IAM policy file of a log view.
List and view log scopes logging.logScopes.{get, list}
View the default log scope observability.scopes.get
Exclude logs logging.exclusions.{list, create, get, update, delete}

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.
Create and use sinks logging.sinks.{list, create, get, update, delete}

When creating a sink, you must also grant the service account an IAM role that lets it write log entries to the destination. For more information, see Set destination permissions.

After your log entries have been routed to a supported destination, access to the log entries is controlled entirely by IAM permissions and roles on the destination.
Save and use private queries logging.queries.usePrivate
logging.queries.{listShared,getShared}
Save and use shared queries logging.queries.{share, getShared, updateShared, deleteShared, listShared}
Use recent queries logging.queries.{create, list}
Create and manage log scopes logging.logScopes.{create, delete, get, list, update}
Set and manage the default log scope observability.scopes.{get, update}

Permissions for the command-line

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.