Security for server client libraries

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.

Note: Some Firestore permissions differ from the standard IAM model permissions. For example, in the IAM model, the datastore.databases.get permission lets you return a database object while, in Firestore, datastore.databases.get lets you begin or roll back a transaction. To retrieve a database object's information, use the datastore.databases.getMetadata permission.

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:

• Learn about custom roles.
• Create and manage custom roles.

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:[e-mail]"
  ],
  "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
[e-mail]	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:[e-mail] \
--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

• Learn more about IAM.
• Grant IAM roles.
• Learn about authentication.