Access control guide

Stackdriver Logging uses Cloud Identity and Access Management to control access to logging data in projects, organizations, folders, and billing accounts.

Overview

Cloud IAM permissions and roles determine how you can use the Logging API, the Logs Viewer, and gcloud logging.

A Cloud IAM role is a collection of permissions. You assign these roles to members. You cannot assign a permission to a member directly; instead you grant them a role, which gives them all the permissions that the role contains.

Log data resides in these resource types: projects, organizations, folders, and billing accounts. Each of these resources can have its own set of members with their own sets of Logging roles.

To create or use log data from Stackdriver Logging within a resource, a member must have a Cloud IAM role that includes the appropriate permissions. A summary list of those Cloud IAM roles and permissions is shown below:

• roles/logging.viewer (Logs Viewer) gives members read-only access to all features of Logging, except the permission to read private logs.

• roles/logging.privateLogViewer (Private Logs Viewer) gives members the permissions found in roles/logging.viewer, plus the permission to read private logs.

• roles/logging.logWriter (Logs Writer) can be granted to members that are service accounts and gives members just enough permissions to write logs. This role does not grant access to the Logs Viewer.

• roles/logging.configWriter (Logs Configuration Writer) gives members the permissions to create logs-based metrics and export sinks. To use the Logs Viewer, add the roles/logging.viewer role.

• roles/logging.admin (Logging Admin) gives members all permissions related to Logging. For a full list of these permissions, see API Permissions.

• roles/viewer (Project Viewer) gives members the same permissions as roles/logging.viewer at the project level. Note that granting this role applies the permissions to most GCP services at the project level, and is not confined to usage of Logging.

• roles/editor (Project Editor) gives members the same permissions as roles/logging.viewer, plus permissions to write log entries, delete logs, and create logs-based metrics, at the project level. The role does not let you create export sinks or read private logs. Note that granting this role applies the permissions to most GCP services at the project level, and is not confined to usage of Logging.

• roles/owner (Project Owner) gives you full access to Logging, including private logs. Note that granting this role applies the permissions to most GCP services at the project level, and is not confined to usage of Logging.

Data Access audit logs, except BigQuery Data Access audit logs, are the only "private logs". To read them, members require certain permissions that are broader than read-only permissions.

For more details about Logging roles and permissions, see Permissions and roles on this page.

Permissions and roles

The following table lists the Cloud IAM roles that grant access to Stackdriver Logging. Each role has a specific set of logging permissions. Roles can be assigned to members of the listed resource types.

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

Role name	Role title	Logging permissions	Resource type
roles/ logging.viewer	Logs Viewer	logging.logEntries.list logging.logMetrics.{list, get} logging.logs.list logging.logServiceIndexes.list logging.logServices.list logging.sinks.{list, get} logging.usage.get resourcemanager.projects.get	project, organization, folder, billing account
roles/ logging.privateLogViewer	Private Logs Viewer	roles/logging.viewer permissions, plus: logging.privateLogEntries.list	project, organization, folder, billing account
roles/ logging.logWriter	Logs Writer	logging.logEntries.create	project, organization, folder, billing account
roles/ logging.configWriter	Logs Configuration Writer	logging.exclusions.{list, create, get, update, delete} logging.logMetrics.{list, create, get, update, delete} logging.logs.list logging.logServiceIndexes.list logging.logServices.list logging.sinks.{list, create, get, update, delete} resourcemanager.projects.get	project, organization, folder, billing account
roles/ logging.admin	Logging Admin	logging.exclusions.{list, create, get, update, delete} logging.logEntries.create logging.logEntries.list logging.logMetrics.{list, create, get, update, delete} logging.logs.delete logging.logs.list logging.logServiceIndexes.list logging.logServices.list logging.privateLogEntries.list logging.sinks.{list, create, get, update, delete} resourcemanager.projects.get	project, organization, folder, billing account
roles/viewer	Viewer	logging.logEntries.list logging.logMetrics.{list, get} logging.logs.list logging.logServiceIndexes.list logging.logServices.list logging.sinks.{list, get} resourcemanager.projects.get	project
roles/editor	Editor	roles/viewer Logging permissions, plus: logging.logEntries.create logging.logMetrics.{create, update, delete} logging.logs.delete	project
roles/owner	Owner	roles/editor Logging permissions, plus: logging.privateLogEntries.list logging.sinks.{create, update, delete}	project

Custom roles

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

• For a role granting permissions for the Logging API, choose from the permissions in API permissions.

• For a role granting permissions to use the Logs Viewer, choose from permission groups in Console permissions.

• For a role granting permissions to use gcloud logging, go to the overview of the Command-line interface.

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

API permissions

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

Note: If you are interested in logs held in organizations, billing accounts, and folders, 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
entries.list	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
monitoredResourceDescriptors.list	(none)	(none)
organizations.logs.*	logging.logs.* (See projects.logs.*)	organizations
organizations.sinks.*	logging.sinks.* (See projects.sinks.*)	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.<b>update<b>	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.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

Console permissions

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

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 logs-based metrics	Add logging.logMetrics.{list, get}
Add ability to view exports	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 export logs	Add logging.sinks.{list, create, get, update, delete}
Add ability to create logs-based metrics	Add logging.logMetrics.{list, create, get, update, delete}

Command-line permissions

gcloud logging commands are controlled by Cloud Identity and Access Management permissions.

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

You must also have the Cloud IAM role that corresponds to the log's location, and to your use case. For details, go to command-line interface permissions.

Access to exported logs

To create a sink, in order to export logs, you must have the permissions of roles/logging.configWriter or roles/logging.admin or roles/owner.

Once a sink begins exporting logs, it has full access to all incoming log entries. Sinks can export private log entries.

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

Logging access scopes

Access scopes are the legacy method of specifying permissions for 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	role/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.

Best practices

Now that Cloud IAM roles are available, a reasonable practice is to give all your VM instances the "Full access to all enabled Google Cloud APIs" scope:

https://www.googleapis.com/auth/cloud-platform

You can grant specific Cloud IAM roles in your VM instance's service account to restrict access to specific APIs. For details, see Service account permissions.