Security for server client libraries

When you use the server client libraries for Firestore, you can manage access to your resources with Identity and Access Management (IAM). IAM lets you give more granular access to specific Google Cloud Platform resources and prevents unwanted access to other resources. This page describes the IAM permissions and roles for Firestore. For a detailed description of IAM, read the IAM documentation.

IAM lets you adopt the security principle of least privilege, so you grant only the necessary access to your resources.

IAM lets you control who (user) has what (role) permission for which resources by setting IAM policies. IAM policies grant one or more roles to a user, giving the user certain permissions. For example, you can grant the datastore.indexAdmin role to a user, which allows the user to create, modify, delete, list, or view indexes.

Permissions and roles

This section summarizes the permissions and roles that Firestore supports.

Required permissions for API methods

The following table lists the permissions that the caller must have to perform each action:

Method Required permissions
projects.databases.documents
batchGet datastore.entities.get
batchWrite update or transform with exists precondition set to false datastore.entities.create
batchWrite update or transform with exists precondition set to true datastore.entities.create
batchWrite update or transform with no precondition datastore.entities.create
datastore.entities.update
beginTransaction datastore.databases.get
commit update or transform with exists precondition set to false datastore.entities.create
commit update or transform with exists precondition set to true datastore.entities.update
commit update or transform with no precondition datastore.entities.create
datastore.entities.update
commit delete datastore.entities.delete
createDocument datastore.entities.create
delete datastore.entities.delete
get datastore.entities.get
list datastore.entities.get
datastore.entities.list
listCollectionIds datastore.entities.list
partitionQuery datastore.entities.get
datastore.entities.list
patch datastore.entities.update
rollback datastore.databases.get
runAggregationQuery datastore.entities.get
datastore.entities.list
runQuery datastore.entities.get
datastore.entities.list
write (RPC) update or transform with exists precondition set to false datastore.entities.create
write (RPC) update or transform with exists precondition set to true datastore.entities.update
write (RPC) update or transform with no precondition datastore.entities.create
datastore.entities.update
write (RPC) delete datastore.entities.delete
projects.databases.indexes
create datastore.indexes.create
delete datastore.indexes.delete
get datastore.indexes.get
list datastore.indexes.list
projects.databases
create datastore.databases.create
delete datastore.databases.delete
get datastore.databases.getMetadata
list datastore.databases.list
patch datastore.databases.update
restore datastore.backups.restoreDatabase
projects.locations
get datastore.locations.get
list datastore.locations.list
projects.databases.backupschedules
get datastore.backupSchedules.get
list datastore.backupSchedules.list
create datastore.backupSchedules.create
update datastore.backupSchedules.update
delete datastore.backupSchedules.delete
projects.locations.backups
get datastore.backups.get
list datastore.backups.list
delete datastore.backups.delete

Predefined roles

With IAM, every API method in Firestore requires that the account making the API request has the appropriate permissions to use the resource. Permissions are granted by setting policies that grant roles to a user, group, or service account. In addition to the primitive roles, owner, editor, and viewer, you can grant Firestore roles to the users of your project.

The following table lists the Firestore IAM roles. You can grant multiple roles to a user, group, or service account.

Role Permissions Description
roles/datastore.owner appengine.applications.get

datastore.*

resourcemanager.projects.get
resourcemanager.projects.list
Full access to Firestore.
roles/datastore.user appengine.applications.get

datastore.databases.get
datastore.databases.getMetadata
datastore.databases.list
datastore.entities.*
datastore.indexes.list
datastore.namespaces.get
datastore.namespaces.list
datastore.statistics.get
datastore.statistics.list

resourcemanager.projects.get
resourcemanager.projects.list
Read/write access to data in a Firestore database. Intended for application developers and service accounts.
roles/datastore.viewer appengine.applications.get

datastore.databases.get
datastore.databases.getMetadata
datastore.databases.list
datastore.entities.get
datastore.entities.list
datastore.indexes.get
datastore.indexes.list
datastore.namespaces.get
datastore.namespaces.list
datastore.statistics.get
datastore.statistics.list

resourcemanager.projects.get
resourcemanager.projects.list
Read access to all Firestore resources.
roles/datastore.importExportAdmin appengine.applications.get
datastore.databases.export
datastore.databases.getMetadata
datastore.databases.import
datastore.operations.cancel
datastore.operations.get
datastore.operations.list
resourcemanager.projects.get
resourcemanager.projects.list
Full access to manage imports and exports.
roles/datastore.indexAdmin appengine.applications.get

datastore.databases.getMetadata

datastore.indexes.*

resourcemanager.projects.get
resourcemanager.projects.list
Full access to manage index definitions.
roles/datastore.keyVisualizerViewer datastore.databases.getMetadata
datastore.keyVisualizerScans.get
datastore.keyVisualizerScans.list
resourcemanager.projects.get
resourcemanager.projects.list
Full access to Key Visualizer scans.
roles/datastore.backupSchedulesViewer datastore.backupSchedules.get
datastore.backupSchedules.list
Read access to backup schedules in a Firestore database.
roles/datastore.backupSchedulesAdmin datastore.backupSchedules.get
datastore.backupSchedules.list
datastore.backupSchedules.create
datastore.backupSchedules.update
datastore.backupSchedules.delete
datastore.databases.list
datastore.databases.getMetadata
Full access to backup schedules in a Firestore database.
roles/datastore.backupsViewer datastore.backups.get
datastore.backups.list
Read access to backup information in a Firestore location.
roles/datastore.backupsAdmin datastore.backups.get
datastore.backups.list
datastore.backups.delete
Full access to backups in a Firestore location.
roles/datastore.restoreAdmin datastore.backups.get
datastore.backups.list
datastore.backups.restoreDatabase
datastore.databases.list
datastore.databases.create
datastore.databases.getMetadata
datastore.operations.list
datastore.operations.get
Ability to restore a Firestore backup into a new database. This role also gives the ability to create new databases, not necessarily by restoring from a backup.

Custom roles

If the predefined roles do not address your business requirements, you can define your own custom roles with permissions that you specify:

Permissions

The following table lists the permissions that Firestore supports.

Database permission name Description
datastore.databases.get Begin or rollback a transaction.
datastore.databases.import Import entities into a database.
datastore.databases.export Export entities from a database.
datastore.databases.getMetadata Read metadata from a database.
datastore.databases.list List databases in a project.
datastore.databases.create Create a database.
datastore.databases.update Update a database.
datastore.databases.delete Delete a database.
datastore.databases.createTagBinding Create a tag binding for a database.
datastore.databases.deleteTagBinding Delete a tag binding for a database.
datastore.databases.listTagBindings List all tag bindings for a database.
datastore.databases.listEffectiveTagBindings List effective tag bindings for a database.
Entity permission name Description
datastore.entities.create Create a document.
datastore.entities.delete Delete a document.
datastore.entities.get Read a document.
datastore.entities.list List the names of documents in a project.
(datastore.entities.get is required to access the document data.)
datastore.entities.update Update a document.
Index permission name Description
datastore.indexes.create Create an index.
datastore.indexes.delete Delete an index.
datastore.indexes.get Read metadata from an index.
datastore.indexes.list List the indexes in a project.
datastore.indexes.update Update an index.
Operation permission name Description
datastore.operations.cancel Cancel a long-running operation.
datastore.operations.delete Delete a long-running operation.
datastore.operations.get Gets the latest state of a long-running operation.
datastore.operations.list List long-running operations.
Project permission name Description
resourcemanager.projects.get Browse resources in the project.
resourcemanager.projects.list List owned projects.
Location permission name Description
datastore.locations.get Get details about a database location. Required to create a new database.
datastore.locations.list List available database locations. Required to create a new database.
Key Visualizer permission name Description
datastore.keyVisualizerScans.get Get details about Key Visualizer scans.
datastore.keyVisualizerScans.list List available Key Visualizer scans.
Backup Schedule permission name Description
datastore.backupSchedules.get Get details about a backup schedule.
datastore.backupSchedules.list List available backup schedules.
datastore.backupSchedules.create Create a backup schedule.
datastore.backupSchedules.update Update a backup schedule.
datastore.backupSchedules.delete Delete a backup schedule.
Backup permission name Description
datastore.backups.get Get details about a backup.
datastore.backups.list List available backups.
datastore.backups.delete Delete a backup.
datastore.backups.restoreDatabase Restore a database from a backup.

Role change latency

Firestore caches IAM permissions for 5 minutes, so it takes up to 5 minutes for a role change to become effective.

Managing Firestore IAM

You can get and set IAM policies using the Google Cloud console, the IAM API, or the gcloud command-line tool. See Granting, Changing, and Revoking Access to Project Members for details.

Configure conditional access permissions

You can use IAM Conditions to define and enforce conditional access control.

For example, the following condition assigns a principal the datastore.user role up until a specified date:

{
  "role": "roles/datastore.user",
  "members": [
    "user:travis@example.com"
  ],
  "condition": {
    "title": "Expires_December_1_2023",
    "description": "Expires on December 1, 2023",
    "expression":
      "request.time < timestamp('2023-12-01T00:00:00.000Z')"
  }
}

To learn how to define IAM Conditions for temporary access, see Configure temporary access.

To learn how to configure IAM Conditions for access to one or more databases, see Configure database access conditions.

Security rule dependency on IAM

Firestore Security Rules for mobile/web clients depend on the following service account and IAM binding:

Service account IAM role
service-project_number@firebase-rules.iam.gserviceaccount.com roles/firebaserules.system

Firebase automatically sets up this service account for you. If you remove the firebaserules.system role from this service account, your security rules will deny all requests. To restore this IAM binding, use the following gcloud CLI command:

gcloud projects add-iam-policy-binding project_id \
--member=serviceAccount:service-project_number@firebase-rules.iam.gserviceaccount.com \
--role=roles/firebaserules.system

To determine your project_id and project_number, see Identifying projects.

Use the Google Cloud CLI instead of the Google Cloud console, because thefirebaserules.system role is hidden in the console by default.

What's next