Jump to Content

Introducing fine-grained access control for Cloud Spanner: A new way to protect your data in Spanner

September 15, 2022
Mark Donsky

Product Manager, Cloud Spanner

As Google Cloud’s fully managed relational database that offers unlimited scale, strong consistency, and availability up to 99.999%, Cloud Spanner powers applications of all sizes in industries such financial services, gaming, retail, and healthcare. Today, we’re excited to announce the preview of fine-grained access control for Spanner that lets you authorize access to Spanner data at the table and column level. With fine-grained access control, it’s now easier than ever to protect your transactional data in Spanner and ensure appropriate controls are in place when granting access to data. 

In this post, we’ll take a look at Spanner’s current access control model, examine the use cases of fine-grained access control, and look at how to use this new capability in your Spanner applications.

Spanner’s access control model today
Spanner provides access control with Identity and Access Management (IAM). IAM provides a simple and consistent access control interface for all Google Cloud services. With capabilities such as a built-in audit trail and context-aware access, IAM makes it easy to grant permissions at the instance and database level to Spanner users.

The model for IAM has three main parts:

  • Role. A role is a collection of permissions. In Spanner, these permissions allow you to perform specific actions on Spanner projects, instances, or databases. For example, spanner.instances.create lets you create a new instance, and spanner.databases.select lets you execute a SQL select statement on a database. For convenience, Spanner comes with a set of predefined roles such as roles/spanner.databaseUser, which contains the permissions spanner.databases.read and spanner.databases.write, but you can define your own custom roles, too. 

  • IAM principal. A principal can be a Google Account (for end users), a service account (for applications and compute workloads), a Google group, or a Google Workspace account that can access a resource. Each principal has its own identifier, which is typically an email address.

  • Policy. The allow policy is the collection of role bindings that bind one or more principals to individual roles. For example, you can bind roles/spanner.databaseReader to IAM principal user@abc.xyz.

The need for more robust access controls
There are a number of use cases where you may need to define roles at a level that is more granular than the database-level. Let’s look at a few of these use cases below.

Ledger applications
Ledgers, which are useful for inventory management, cryptocurrency, and banking applications, let you look at inventory levels and apply updates such as credits or debits to existing balances. In a ledger application, you can look at balances, add inventory, and remove inventory. You can’t go back and adjust last week’s inventory level to 500 widgets. This corresponds to having SELECT privileges (to look at balances) and INSERT privileges (to add or remove inventory), but not UPDATE or DELETE privileges. 

Analytics users
Analytics users often need SELECT access to a few tables in Spanner database, but should not not have access to all tables in the database. Nor should they have INSERT, UPDATE, or DELETE access to anything in the database. This corresponds to having SELECT privileges on a set of tables – but not all tables – in the database.

Service accounts
A service account is a special type of Google account intended to represent a non-human user that needs to authenticate and be authorized to access data from Google Cloud. Each Spanner service account likely needs to have its own set of privileges on specific tables in the database. For example, consider a ride-sharing application that has service accounts for drivers and passengers. Likely the driver service account needs SELECT privileges on specific columns of the passenger’s profile table (e.g., user’s first name, profile picture, etc.), but should not be allowed to update the passenger’s email address or other personal information.

The basics of fine-grained access control in Spanner
If you’re familiar with role-based access control in other relational databases, you already are familiar with the important concepts of fine-grained access control in Spanner. Let’s review the model for fine-grained access control in Spanner:

  • Database Privilege. Spanner now supports four types of privileges: SELECT, INSERT, UPDATE, and DELETE. SELECT, INSERT, UPDATE and DELETE privileges can be assigned to tables, and SELECT, INSERT, and UPDATE can be applied to tables or columns.

  • Database Role. Database roles are collections of privileges. For example, you can have a role called inventory_admin that has SELECT and INSERT privileges on the Inventory_Transactions table and SELECT, INSERT, UPDATE, and DELETE privileges on the Products table.

Because Spanner relies on IAM for identity and access management, you need to assign database roles to the appropriate IAM principals by managing conditional role bindings

Let’s look at an example. Suppose we want to set up IAM principal user@abc.xyz with fine-grained access to two tables: Inventory_Transactions and Products. To do this, we’ll create a database role called inventory_admin and grant this role to user@abc.xyz.

Step 1: Set up the IAM principal as a Cloud Spanner fine-grained access user
Until today, if you wanted to grant database-level access to an IAM principal, you’d grant them either the roles/spanner.databaseUser role, or some privileges that are bundled in that role. Now, with fine-grained access control, you can instead grant IAM principals the Cloud Spanner Fine-grained Access User role (roles/spanner.fineGrainedAccessUser).


Cloud Spanner Fine-grained Access User allows the user to make API calls to the database, but does not confer any data access privileges other than those conferred to the public role. By default, the public role does not have any privileges, and this role only grants access to make API calls to the database. To access data, a fine grained access user must specify the database role that they want to act as.

Step 2: Create the database role
To create a role, run the standard SQL CREATE ROLE command:
CREATE ROLE inventory_admin;

The newly created database role can be referenced in IAM policies via the resource URI: projects/<project_name>/instances/<instance_name>/databases/<database_name>/databaseRoles/inventory_admin. Later on, we’ll show how to configure an IAM policy that allows a specific IAM principal permission to act as this database role.

Step 3: Assign privileges to the database role
Next, assign the appropriate privileges to this role:


While you can run these statement individually, we recommend that you issue Cloud Spanner DDL statements in a single batch


Step 4: Assign the role to an IAM principal
Finally, to allow user@abc.xyz to act as the database role inventory_admin, grant Cloud Spanner Database Role User to user@abc.xyz with the database role as a condition. To do this, open the database’s IAM Info Panel and add the following conditions using the IAM condition editor:

  • resource.type == “spanner.googleapis.com/DatabaseRole” &&

  • You can also add any other conditions to further restrict access to this database role, such as scheduling access by time of day, day of week, or with an expiration date.


Transitioning to fine-grained access control
When you’re transitioning to fine-grained access control, you might want to assign both  roles/spanner.databaseUser and roles/spanner.fineGrainedAccessUser to an IAM principal. When you’re ready to switch that IAM principal over to fine-grained permissions, simply revoke the databaseUser role from that IAM principal.

Using the role as an end user
When an end user logs into Spanner, they can access the database using the role they’ve been granted, through the Google Cloud console or gcloud commands. Go, Java, Node.js and Python client libraries are also supported, with support for more client libraries coming soon.

Learn more
With fine-grained access control, you can set up varying degrees of access to your Spanner databases based on the user, their role, or the organization to which they belong. In preview today, fine-grained access control is available to all Spanner customers at no additional charge. 

Posted in