The Admin SDK is a set of server libraries that lets you interact with
Firebase from privileged environments to perform actions like:
- Read and write Realtime Database data with full admin privileges.
- Programmatically send Firebase Cloud Messaging messages using a simple,
alternative approach to the Firebase Cloud Messaging server protocols.
- Generate and verify Firebase auth tokens.
- Access Google Cloud resources like Cloud Storage buckets and
Cloud Firestore databases associated with your Firebase projects.
- Create your own simplified admin console to do things like look up user data
or change a user's email address for authentication.
If you are interested in using the Node.js SDK as a client for end-user access
(for example, in a Node.js desktop or IoT application), as opposed to admin
access from a privileged environment (like a server), you should instead follow
the
instructions for setting up the client JavaScript SDK
.
Here is a feature matrix showing what Firebase features are supported in each
language:
To learn more about Admin SDK integration for these uses, see the corresponding
Realtime Database
,
FCM
,
Authentication
,
Remote Config
,
and
Cloud Storage
documentation.
The rest of this page focuses on basic setup for the Admin SDK.
Prerequisites
Set up a Firebase project and service account
To use the Firebase Admin SDK, you'll need the following:
- A Firebase project.
- A Firebase Admin SDK service account to communicate with Firebase. This
service account is created automatically when you create a Firebase project
or add Firebase to a Google Cloud project.
- A configuration file with your service account's credentials.
If you don't already have a Firebase project, you need to create one in the
Firebase console
. Visit
Understand Firebase Projects
to learn more about
Firebase projects.
Create a Firebase project
-
In the
Firebase console
, click
Add project
.
-
To add Firebase resources to an
existing
Google Cloud project, enter its
project name or select it from the dropdown menu.
-
To create a new project, enter the desired project name. You can also optionally
edit the project ID displayed below the project name.
-
If prompted, review and accept the
Firebase terms
.
-
Click
Continue
.
-
(Optional)
Set up Google Analytics for your project, which enables you
to have an optimal experience using any of the following Firebase products:
Either select an existing
Google Analytics account
or to create a new account.
If you create a new account, select your
Analytics reporting location
, then accept
the data sharing settings and Google Analytics terms for your project.
-
Click
Create project
(or
Add Firebase
, if you're using an
existing Google Cloud project).
Firebase automatically provisions resources for your Firebase project. When
the process completes, you'll be taken to the overview page for your Firebase
project in the Firebase console.
Add the SDK
If you are setting up a new project, you need to install the SDK for the
language of your choice.
Node.js
The Firebase Admin Node.js SDK is available on npm. If you don't already
have a
package.json
file, create one via
npm init
. Next, install the
firebase-admin
npm package and save it to your
package.json
:
npm install firebase-admin --save
To use the module in your application,
require
it from any JavaScript
file:
const { initializeApp } = require('firebase-admin/app');
If you are using ES2015, you can
import
the module:
import { initializeApp } from 'firebase-admin/app';
Java
The Firebase Admin Java SDK is published to the Maven central repository.
To install the library, declare it as a dependency in your
build.gradle
file:
dependencies {
implementation 'com.google.firebase:firebase-admin:9.2.0'
}
If you use Maven to build your application, you can add the following
dependency to your
pom.xml
:
<dependency>
<groupId>com.google.firebase</groupId>
<artifactId>firebase-admin</artifactId>
<version>9.2.0</version>
</dependency>
Python
The Firebase Admin Python SDK is available via
pip
.
You can install the library for all users via
sudo
:
sudo pip install firebase-admin
Or, you can install the library for just the current user by passing the
--user
flag:
pip install --user firebase-admin
Go
The Go Admin SDK can be installed using the
go get
utility:
# Install the latest version:
go get firebase.google.com/go/v4@latest
# Or install a specific version:
go get firebase.google.com/go/v4@4.14.0
C#
The .NET Admin SDK can be installed using the .NET package manager:
Install-Package FirebaseAdmin -Version 2.4.1
Alternatively, install it using the
dotnet
command-line utility:
dotnet add package FirebaseAdmin --version 2.4.1
Or, you can install it by adding the following package reference entry to
your
.csproj
file:
<ItemGroup>
<PackageReference Include="FirebaseAdmin" Version="2.4.1" />
</ItemGroup>
Initialize the SDK
Once you have created a Firebase project, you can initialize the SDK with
Google Application Default Credentials
.
Because default credentials lookup is fully automated in Google environments,
with no need to supply environment variables or other configuration, this way of
initializing the SDK is strongly recommended for applications running in Google
environments such as Cloud Run, App Engine, and Cloud Functions.
To optionally specify initialization options for services such as Realtime Database,
Cloud Storage, or Cloud Functions, use the
FIREBASE_CONFIG
environment variable. If the content of the
FIREBASE_CONFIG
variable begins
with a
{
it will be parsed as a JSON object. Otherwise the SDK assumes that
the string is the path of a JSON file containing the options.
Node.js
const app = initializeApp();
Java
FirebaseApp.initializeApp();
Python
default_app = firebase_admin.initialize_app()
Go
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
Once it is initialized, you can use the Admin SDK to accomplish
the following types of tasks:
Using an OAuth 2.0 refresh token
The Admin SDK also provides a credential which allows you to authenticate
with a
Google OAuth2
refresh token:
Node.js
const myRefreshToken = '...'; // Get refresh token from OAuth2 flow
initializeApp({
credential: refreshToken(myRefreshToken),
databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});
Java
FileInputStream refreshToken = new FileInputStream("path/to/refreshToken.json");
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.fromStream(refreshToken))
.setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
.build();
FirebaseApp.initializeApp(options);
Python
cred = credentials.RefreshToken('path/to/refreshToken.json')
default_app = firebase_admin.initialize_app(cred)
Go
opt := option.WithCredentialsFile("path/to/refreshToken.json")
config := &firebase.Config{ProjectID: "my-project-id"}
app, err := firebase.NewApp(context.Background(), config, opt)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
C#
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.FromFile("path/to/refreshToken.json"),
});
Initialize the SDK in non-Google environments
If you are working in a non-Google server environment in which default
credentials lookup can't be fully automated, you can initialize the SDK
with an exported service account key file.
Firebase projects support Google
service accounts
,
which you can use to call Firebase
server APIs from your app server or trusted environment. If you're developing
code locally or deploying your application on-premises,
you can use credentials obtained
via this service account to authorize server requests.
To authenticate a service account and authorize it
to access Firebase services, you must generate a private key file in JSON
format.
To generate a private key file for your service account:
In the Firebase console, open
Settings >
Service Accounts
.
Click
Generate New Private Key
, then confirm by clicking
Generate Key
.
Securely store the JSON file containing the key.
When authorizing via a service account, you have two choices for providing the
credentials to your application. You can either set the
GOOGLE_APPLICATION_CREDENTIALS
environment variable, or you can
explicitly pass the path to the service account key in code.
The first option is more secure and is strongly recommended.
To set the environment variable:
Set the environment variable
GOOGLE_APPLICATION_CREDENTIALS
to the file path of the JSON file that contains your service account key.
This variable only applies to your current shell session, so if you open
a new session, set the variable again.
Linux or macOS
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Windows
With PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
After you've completed the above steps, Application Default Credentials (ADC)
is able to implicitly determine your credentials, allowing you to use service
account credentials when testing or running in non-Google environments.
Initialize the SDK as shown:
Node.js
initializeApp({
credential: applicationDefault(),
databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});
Java
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.getApplicationDefault())
.setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
.build();
FirebaseApp.initializeApp(options);
Python
default_app = firebase_admin.initialize_app()
Go
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
C#
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
ProjectId = "my-project-id",
});
Initialize multiple apps
In most cases, you only have to initialize a single, default app. You can
access services off of that app in two equivalent ways:
Node.js
// Initialize the default app
const defaultApp = initializeApp(defaultAppConfig);
console.log(defaultApp.name); // '[DEFAULT]'
// Retrieve services via the defaultApp variable...
let defaultAuth = getAuth(defaultApp);
let defaultDatabase = getDatabase(defaultApp);
// ... or use the equivalent shorthand notation
defaultAuth = getAuth();
defaultDatabase = getDatabase();
Java
// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);
System.out.println(defaultApp.getName()); // "[DEFAULT]"
// Retrieve services by passing the defaultApp variable...
FirebaseAuth defaultAuth = FirebaseAuth.getInstance(defaultApp);
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance(defaultApp);
// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.getInstance();
defaultDatabase = FirebaseDatabase.getInstance();
Python
# Import the Firebase service
from firebase_admin import auth
# Initialize the default app
default_app = firebase_admin.initialize_app(cred)
print(default_app.name) # "[DEFAULT]"
# Retrieve services via the auth package...
# auth.create_custom_token(...)
Go
// Initialize default app
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
// Access auth service from the default app
client, err := app.Auth(context.Background())
if err != nil {
log.Fatalf("error getting Auth client: %v\n", err)
}
C#
// Initialize the default app
var defaultApp = FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
});
Console.WriteLine(defaultApp.Name); // "[DEFAULT]"
// Retrieve services by passing the defaultApp variable...
var defaultAuth = FirebaseAuth.GetAuth(defaultApp);
// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.DefaultInstance;
Some use cases require you to create multiple apps at the same time. For
example, you might want to read data from the Realtime Database of one Firebase
project and mint custom tokens for another project. Or you might want to
authenticate two apps with separate credentials. The Firebase SDK allows you
create multiple apps at the same time, each with their own configuration
information.
Node.js
// Initialize the default app
initializeApp(defaultAppConfig);
// Initialize another app with a different config
var otherApp = initializeApp(otherAppConfig, 'other');
console.log(getApp().name); // '[DEFAULT]'
console.log(otherApp.name); // 'other'
// Use the shorthand notation to retrieve the default app's services
const defaultAuth = getAuth();
const defaultDatabase = getDatabase();
// Use the otherApp variable to retrieve the other app's services
const otherAuth = getAuth(otherApp);
const otherDatabase = getDatabase(otherApp);
Java
// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);
// Initialize another app with a different config
FirebaseApp otherApp = FirebaseApp.initializeApp(otherAppConfig, "other");
System.out.println(defaultApp.getName()); // "[DEFAULT]"
System.out.println(otherApp.getName()); // "other"
// Use the shorthand notation to retrieve the default app's services
FirebaseAuth defaultAuth = FirebaseAuth.getInstance();
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance();
// Use the otherApp variable to retrieve the other app's services
FirebaseAuth otherAuth = FirebaseAuth.getInstance(otherApp);
FirebaseDatabase otherDatabase = FirebaseDatabase.getInstance(otherApp);
Python
# Initialize the default app
default_app = firebase_admin.initialize_app(cred)
# Initialize another app with a different config
other_app = firebase_admin.initialize_app(cred, name='other')
print(default_app.name) # "[DEFAULT]"
print(other_app.name) # "other"
# Retrieve default services via the auth package...
# auth.create_custom_token(...)
# Use the `app` argument to retrieve the other app's services
# auth.create_custom_token(..., app=other_app)
Go
// Initialize the default app
defaultApp, err := firebase.NewApp(context.Background(), nil)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
// Initialize another app with a different config
opt := option.WithCredentialsFile("service-account-other.json")
otherApp, err := firebase.NewApp(context.Background(), nil, opt)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
// Access Auth service from default app
defaultClient, err := defaultApp.Auth(context.Background())
if err != nil {
log.Fatalf("error getting Auth client: %v\n", err)
}
// Access auth service from other app
otherClient, err := otherApp.Auth(context.Background())
if err != nil {
log.Fatalf("error getting Auth client: %v\n", err)
}
C#
// Initialize the default app
var defaultApp = FirebaseApp.Create(defaultOptions);
// Initialize another app with a different config
var otherApp = FirebaseApp.Create(otherAppConfig, "other");
Console.WriteLine(defaultApp.Name); // "[DEFAULT]"
Console.WriteLine(otherApp.Name); // "other"
// Use the shorthand notation to retrieve the default app's services
var defaultAuth = FirebaseAuth.DefaultInstance;
// Use the otherApp variable to retrieve the other app's services
var otherAuth = FirebaseAuth.GetAuth(otherApp);
Set scopes for Realtime Database and Authentication
If you're using a Google Compute Engine VM with Google Application Default
Credentials for Realtime Database or Authentication, make sure to also set the right
access scopes
.
For Realtime Database and Authentication, you need scopes ending in
userinfo.email
and
either
cloud-platform
or
firebase.database
. To check the existing access
scopes and change them, run the following commands using
gcloud
.
gcloud
# Check the existing access scopes
gcloud compute instances describe [INSTANCE_NAME] --format json
# The above command returns the service account information. For example:
"serviceAccounts": [
{
"email": "your.gserviceaccount.com",
"scopes": [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/userinfo.email"
]
}
],
# Stop the VM, then run the following command, using the service account
# that gcloud returned when you checked the scopes.
gcloud compute instances set-service-account [INSTANCE_NAME] --service-account "your.gserviceaccount.com" --scopes "https://www.googleapis.com/auth/firebase.database,https://www.googleapis.com/auth/userinfo.email"
Testing with gcloud end user credentials
When testing the Admin SDK locally with
Google Application Default Credentials
obtained by running
gcloud auth application-default login
, additional
changes are needed to use Firebase Authentication due to the following:
- Firebase Authentication does not accept gcloud end user credentials generated using
the gcloud OAuth client ID.
- Firebase Authentication requires the project ID to be provided on initialization for
these type of end user credentials.
As a workaround, you can generate Google Application Default Credentials in
gcloud
using your own
OAuth 2.0 client ID
.
The OAuth client ID has to be a
Desktop app
application type.
gcloud
gcloud auth application-default login --client-id-file=[/path/to/client/id/file]
You can specify the project ID explicitly on app initialization or just use the
GOOGLE_CLOUD_PROJECT
environment variable. The latter avoids the need to make
any additional changes to test your code.
To explicitly specify the project ID:
Node.js
import { initializeApp, applicationDefault } from 'firebase-admin/app';
initializeApp({
credential: applicationDefault(),
projectId: '<FIREBASE_PROJECT_ID>',
});
Java
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.getApplicationDefault())
.setProjectId("<FIREBASE_PROJECT_ID>")
.build();
FirebaseApp.initializeApp(options);
Python
app_options = {'projectId': '<FIREBASE_PROJECT_ID>'}
default_app = firebase_admin.initialize_app(options=app_options)
Go
config := &firebase.Config{ProjectID: "<FIREBASE_PROJECT_ID>"}
app, err := firebase.NewApp(context.Background(), config)
if err != nil {
log.Fatalf("error initializing app: %v\n", err)
}
C#
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
ProjectId = "<FIREBASE_PROJECT_ID>",
});
Next steps
Learn about Firebase:
Add Firebase features to your app: