Firebase: The Server-side Story
As most developers would know, many web and mobile apps do not exist in a vacuum. Instead they are part of a larger software ecosystem with other apps, backend services, databases, APIs and even legacy systems. Therefore the success of an app often depends on its ability to seamlessly integrate with various other software. For a Firebase app developer, this means being able to integrate a number of heterogeneous systems with Firebase, and share data across them as needed.
Firebase Admin SDKs were designed with this critical requirement in mind. Simply put, Admin SDKs facilitate accessing Firebase services from trusted environments. The term trusted environment here represents any programming or runtime environment that is trusted by the developers and administrators of a Firebase app. Consequently, the Admin SDKs are usually initialized with a credential that belongs to the Firebase project itself. Furthermore, Admin SDKs are never deployed on end-user devices, which are untrusted from the app developer’s point of view.
Who are the stakeholders?
Before we continue this discussion further, we need to clearly establish the two types of users that are associated with a Firebase app.
- App Developers — refers to those who implement, release and maintain a Firebase app. This is a small but diverse group consisting of programmers, system administrators and various other DevOps personnel.
- End-users — refers to those who download, install and use a Firebase app via their mobile devices and/or web browsers. An app that has gone viral may have millions of end-users.
The app developers use the Firebase client SDKs to build an app. Firebase provides client SDKs for iOS, Android and Web (JS) platforms. Once such an app has been released, the end-users consume it via their mobile devices and web browsers. When necessary, they log in to the app using their own credentials (e.g. username+password, Google account, Facebook account).
On the other hand, software built using the Firebase Admin SDKs are deployed and run by the app developers themselves. They decide what to use such software for, and how to expose them to the end-users — if at all. Software based on Admin SDKs typically complement a Firebase app, providing some backend functionality or enabling integration with other systems.
Where can you deploy Admin SDKs?
Firebase Admin SDKs can be deployed in any environment that the app developers have control over. Typical examples include:
- An application server that is run and managed by the app developers, possibly in their own data center.
- A cloud platform environment that the developers are using (e.g. a Google App Engine or Compute Engine instance started by the developers).
- A serverless framework the developers are programming with (e.g. Google Cloud Functions).
Note that in all the above cases, the app developers control the environment, as well as how the software is deployed in each environment. For instance, the app developers have the freedom to change, redeploy or terminate their software at anytime. The app developers also decide how their code and the associated interactions are secured when deploying in such environments. Therefore, they can trust the environments to be free of mangling by the end-users. This is what makes these environments suitable for Admin SDK.
In contrast, end-user mobile devices and web browsers are not under the control of the Firebase app developers, and should not be considered for Admin SDK deployments. In extreme cases, the end-users may even modify the code running in these environments, and therefore the app developers cannot rely on the code to always operate within acceptable parameters. However, it is perfectly normal and expected that end-user devices and apps interact with Admin SDK code remotely. Admin SDKs provide a means to securely authorize such remote client interactions. After all, integrating different systems is what Admin SDKs are for.
I intend to co-author a more detailed article on this subject in the near future along with a colleague. Therefore I’ll avoid going into a detailed discussion right now, and kindly request you to stay tuned.
What can you do with Admin SDKs?
Admin SDKs relax some of the security measures present in Firebase client SDKs, while providing APIs that are useful for implementing developer and administrator use cases. Some popular Admin SDK use cases are:
- Developing an administrative dashboard for a Firebase app.
- Building a critical backend service for a Firebase app.
- Provisioning user accounts, managing user roles and setting up permissions.
- Integrating with third-party user authentication systems.
- Sending out notifications to the users of an app.
- Archiving or summarizing the data managed by the app.
- Migrating data across systems.
Use cases such as these may be implemented in many different forms, including web apps, batch jobs, serverless event handlers and command line tools. Therefore Firebase Admin SDKs often get used to develop a wide range of software. Also as of this writing the Firebase Admin SDKs are available in four programming languages — Node.js, Java, Python and Go. This enables integrating a variety of systems with Firebase.
Initializing the Firebase Admin SDK
Firebase Admin SDKs are usually initialized with one of two types of credentials.
- Service account credentials — A credential that can be used to authorize server-to-server interactions. Each service account credential belongs to a specific Google Cloud Platform (GCP) project, and can only be obtained by the developers and administrators of a project. Since Firebase projects are just GCP projects in disguise, service account credentials can also be used to authorize Firebase interactions made by the Admin SDK. Service account credentials for a Firebase project can be downloaded as JSON files from the Firebase console or the GCP console.
- Google application default credentials (ADC)— A credential that is readily available for code deployed in managed environments such as Google App Engine, Google Compute Engine and Google Cloud Functions. With ADC, app developers do not have to explicitly package any credentials with their code. Rather, they would simply indicate in the code that the application should use ADC, and the application will discover the appropriate credentials by examining its runtime environment. Under the hood, ADC are usually just service account credentials that GCP implicitly provisions for the runtime environment.
Admin SDKs also support a third type of credentials, which enables initializing the SDK with an OAuth2 refresh token. While the previous two types of credentials belong to the Firebase project, refresh token credentials typically belong to an individual developer. But this is rarely used in practice, except perhaps for locally testing an application.
If your code is deployed in an environment managed by Google, it is highly recommended that you initialize the Admin SDK with application default credentials. For all other environments (local virtual machine, AWS, Azure and others), use service account credentials. However, there are few scenarios where you must use service account credentials, even when deploying to GCP. This is usually when the Admin SDK is used to cryptographically sign some data. Typical examples include:
- Creating custom JWT tokens
- Creating signed URLs for Google Cloud Storage objects
These use cases require a private key to sign data with. Currently the Admin SDK can only obtain a private key from an explicitly specified service account credential. This is somewhat of a limitation of the Admin SDK, and is likely to get addressed in a future release.
On a related note, please do keep in mind that service account credentials should never be shared with somebody who is not a developer or an administrator of your Firebase project. Service accounts open up access to many resources associated with a Firebase project. In the wrong hands they can lead to serious problems ranging from mild resource abuse to full-scale DoS attacks. Handle those JSON files with care, and never ever check them into public version control. The lack of an explicit credentials file that may accidentally get leaked is a major advantage ADC have over service accounts.
What’s “Admin” about it?
Firebase Admin SDKs provide unregulated administrative access to Firebase services and associated project resources. Think of it as operating in the superuser mode. Therefore it can execute certain privileged operations in a Firebase project, such as removing a user account or resetting the password of a user. Firebase client SDKs on the other hand operate in the context of end-users, and therefore can only access the services and resources a given end-user is entitled to access.
This distinction is most apparent when accessing the Firebase Realtime Database (RTDB) service. RTDB supports specifying security rules that govern which users are allowed to access a particular portion of the database. Take the following rules configuration for example:
This rule grants write access on theusers/<uid> database node to authenticated users with matching user IDs. For example, user alice is authorized to write to users/alice, butusers/bob is off limits to her. Once put into operation, RTDB evaluates all write requests originating from the Firebase client SDKs against this rule, and approves or denies them accordingly. However, an application written using the Admin SDK gains unrestricted access to the full database. Since the Admin SDK operates with higher privileges, and it is not executing as any individual end-user, the security rules do not apply to the Admin SDK. This is one of the main reasons why the Admin SDK should not be deployed in untrusted environments.
In some situations, however, this agnostic behavior is not desirable, and even outright dangerous. There are many use cases where we want the Admin SDK to play by the rules we have put into place. For example, imagine a situation where you rely on the rules to maintain the integrity of saved data. In a scenario such as this, leaving room for the Admin SDK to accidentally modify or wipe out a portion of the database can be disastrous. Fortunately, we can easily configure the Firebase Admin SDK to operate with limited privileges, and therefore honor the RTDB security rules. This is done by specifying the databaseAuthVariableOverride option when initializing the Admin SDK.
In the above example, any RTDB invocations made by the Admin SDK will be treated as if they were made by an authenticated end-user named my-service-worker, and the rules will be enforced as usual.
Next steps…
Hopefully, this helped paint a clearer picture of what Firebase Admin SDKs offer, and what kind of use cases they are good for. More importantly, I hope it helped you understand the importance of server-side integration for mobile and web apps, and how the Firebase platform is poised to facilitate it. What I would recommend next is to try to actually build something with Firebase Admin SDKs. You can start with the official setup guide, pick the programming language of your choice, and continue experimenting. Also note that Firebase Admin SDKs are open source. So please feel free to report any issues you come across, log new feature requests, and also help out with suggestions and pull requests whenever you can.
