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`
`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`
`patch`	`datastore.entities.update`
`rollback`	`datastore.databases.get`
`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`
`get`	`datastore.databases.getMetadata`
`list`	`datastore.databases.list`
`patch`	`datastore.databases.update`
`projects.locations`
`get`	`datastore.locations.get`
`list`	`datastore.locations.list`

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

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

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.

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

Learn more about IAM.
Grant IAM roles.