Set up appropriate access for an extension

For an extension to perform its specified actions, Firebase grants each instance of an installed extension limited access to the project and its data via a service account.

What's a service account?

A service account is a special type of Google user account. It represents a non-human user that can make authorized API calls to Google services.

During installation of an extension, Firebase creates a service account for the extension in the project. Each installed instance of an extension has its own service account. If an extension instance is uninstalled, Firebase deletes the extension's service account.

Service accounts created for extensions are in the format:

ext-extension-instance-id@project-id.iam.gserviceaccount.com

Firebase limits an extension's access to a project and its data by assigning specific roles (bundles of permissions) to the service account of the extension. When you build an extension, you determine which roles your extension requires to operate, then you list these roles and the reason your extension needs these roles in your extension.yaml file (see example at the bottom of this page).

Determine which roles your extension requires

When you build your extension, you determine the level of access that your extension requires to operate.

During installation, the Firebase CLI prompts for the user to accept the access level granted by each role. If your extension requests more roles than it actually needs, then users may be less likely to install it.

1. Determine if your extension interacts with a product:

   • If your extension interacts with a product, then you need to give your extension access to that product.

     For example, if your extension writes data to a Realtime Database instance, then your extension needs a Realtime Database role (specifically, firebasedatabase.admin).

   • If your extension just listens for a triggering event from a product, then your extension does not need a role associated with that product.

     For example, if your extension triggers upon a write to a Realtime Database instance (but doesn't write anything to the database), then your extension does not need a Realtime Database role.

2. After you've determined with which products your extension interacts, you need to decide which role is required for that specific interaction. Some products offer different roles depending on the action or set of actions performed.

   For example, say your extension interacts with a Cloud Storage bucket. The storage.objectCreator role would allow the extension to create an object in a Cloud Storage bucket, but that role wouldn't allow the extension to view, delete, or overwrite objects. To enable the extension to perform those additional actions, you need to assign the storage.objectAdmin role instead.

Refer to the section at the bottom of this page to view all the supported roles that you may assign your extension's service account. To learn about each role's description and permissions granted, visit the Firebase documentation or Google Cloud documentation. You can also look up roles in the Google Cloud console's IAM & Admin panel.

How to assign roles to an extension

List the IAM roles required for your extension to operate in the roles section of your extension.yaml file.

Here's an example for an extension that listens to a specified Firebase Realtime Database path. When triggered, the extension updates a user account email (interaction with Firebase Authentication) and sends a notification (interaction with Firebase Cloud Messaging). Notice the following:

• Even though the extension triggers from a Realtime Database event, the firebasedatabase.admin role isn't listed (listening isn't considered an interaction).
• Since the extension interacts with Authentication and Cloud Messaging, the extension requires roles to access those products (firebaseauth.admin and firebasenotifications.admin, respectively).

# extension.yaml
...

# Roles assigned to the extension's service account by Firebase during installation
roles:
  - role: firebaseauth.admin
    reason: Required to update the email address of the user account

  - role: firebasenotifications.admin
    reason: Required to send a notification that the email address has been updated

...

In your extension.yaml file, use the following fields to assign a role to an extension's service account:

Reduce the scope of roles

Extensions should follow the principle of least privilege and only request access to the resources they need. You can limit an extension's scope of access by using the role.resource field. For example, if your extension needs to write objects to a Cloud Storage bucket, you could use the following role:

roles:
  - role: storage.objectCreator
    reason: Needed in order to write
    resource: projects/${PROJECT_ID}/buckets/${STORAGE_BUCKET}

This lets the extension access only the bucket it needs, and not others on the same project.

This field supports projects (projects/{project_id}) and Storage buckets (projects/{project_id}/buckets/{bucket_id}).

Supported roles for extensions

The following table lists the supported IAM roles for interacting with Firebase products. Most of the roles in this table are Firebase product-level roles, but some are managed directly by Google Cloud (specifically, Cloud Firestore and Cloud Storage).

Firebase products

Google Cloud products

Learn about these roles in the Google Cloud documentation.