This document shows you how to install the Identity Platform Admin SDK. The Admin SDK lets you manage Identity Platform from a server environment, and perform administrator actions such as migrating users, setting custom claims, and configuring identity providers.
Before you begin
To use the Admin SDK, you need a server app running one of the following:
Language | Minimum framework version |
---|---|
Node.js | Node.js 8.13.0+ |
Java | Java 7+ (Java 8+ recommended) |
Python | Python 2.7+ or 3.4+ (3.4+ recommended) |
Go | Go 1.9+ |
C# | .NET Framework 4.5+ or .NET Core 1.5+ |
The following table lists the features supported by each SDK language:
Feature | Node.js | Java | Python | Go | C# |
---|---|---|---|---|---|
Custom token minting | |||||
Verifying ID tokens | |||||
Managing users | |||||
Controlling access with custom claims | |||||
Revoking refresh tokens | |||||
Importing users | |||||
Managing session cookies | |||||
Generating email action links | |||||
Managing SAML and OIDC provider configurations | |||||
Multi-tenancy support |
Additionally, you'll need a service account and key for your project:
Cloud Console
Create a service account:
-
In the Cloud Console, go to the Create service account page.
Go to Create service account - Select a project.
-
In the Service account name field, enter a name. The Cloud Console fills in the Service account ID field based on this name.
In the Service account description field, enter a description. For example,
Service account for quickstart
. - Click Create.
-
Click the Select a role field.
Under Quick access, click Basic, then click Owner.
- Click Continue.
-
Click Done to finish creating the service account.
Do not close your browser window. You will use it in the next step.
Create a service account key:
- In the Cloud Console, click the email address for the service account that you created.
- Click Keys.
- Click Add key, then click Create new key.
- Click Create. A JSON key file is downloaded to your computer.
- Click Close.
Command line
You can run the following commands using the Cloud SDK on your local machine, or in Cloud Shell.
-
Create the service account. Replace NAME with a name for the service account.
gcloud iam service-accounts create NAME
-
Grant permissions to the service account. Replace PROJECT_ID with your project ID.
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/owner"
-
Generate the key file. Replace FILE_NAME with a name for the key file.
gcloud iam service-accounts keys create FILE_NAME.json --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com
Provide authentication credentials to your application code by
setting the environment variable GOOGLE_APPLICATION_CREDENTIALS
.
Replace [PATH] with 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="[PATH]"
For example:
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"
Windows
With PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
For example:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\my-key.json"
With command prompt:
set GOOGLE_APPLICATION_CREDENTIALS=[PATH]
Installing the SDK
Node.js
The Node.js Admin SDK is available on npm. If you don't already
have a package.json
file, create one using npm init
. Next, install the
npm package and save it to your package.json
:
npm install firebase-admin --save
To use the module in your app, require
it from any JavaScript file:
var admin = require('firebase-admin');
If you are using ES2015, you can import
the module instead:
import * as admin from 'firebase-admin';
Java
The Java Admin 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:6.11.0'
}
If you use Maven to build your app, you can add the following
dependency to your pom.xml
:
<dependency>
<groupId>com.google.firebase</groupId>
<artifactId>firebase-admin</artifactId>
<version>6.11.0</version>
</dependency>
Python
The Python Admin SDK is available using pip.
pip install --user firebase-admin
Go
Use the go get
utility to install the Go Admin SDK:
go get firebase.google.com/go
C#
Install the .NET Admin SDK using the .NET package manager:
Install-Package FirebaseAdmin -Version 1.9.1
Alternatively, install it using the dotnet
command-line utility:
dotnet add package FirebaseAdmin --version 1.9.1
Or, you can install it by adding the following package reference entry to
your .csproj
file:
<ItemGroup>
<PackageReference Include="FirebaseAdmin" Version="1.9.1" />
</ItemGroup>
Initializing the SDK using default credentials
Add the following code to your server app to initialize the Admin SDK using the default credentials:
Node.js
// Initialize the default app
var admin = require('firebase-admin');
var app = admin.initializeApp({
credential: admin.credential.applicationDefault()
});
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) }
C#
FirebaseApp.Create();
Initializing the SDK with a service account key file
You can also manually specify a service account key file:
Node.js
// Initialize the default app
var admin = require('firebase-admin');
var app = admin.initializeApp({
credential: admin.credential.cert('/path/to/serviceAccountKey.json')
});
Java
FileInputStream serviceAccount = new FileInputStream("path/to/serviceAccountKey.json"); FirebaseOptions options = FirebaseOptions.builder() .setCredentials(GoogleCredentials.fromStream(serviceAccount)) .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/") .build(); FirebaseApp.initializeApp(options);
Python
import firebase_admin from firebase_admin import credentials from firebase_admin import exceptions cred = credentials.Certificate('path/to/serviceAccountKey.json') default_app = firebase_admin.initialize_app(cred)
Go
opt := option.WithCredentialsFile("path/to/serviceAccountKey.json") app, err := firebase.NewApp(context.Background(), nil, opt) if err != nil { log.Fatalf("error initializing app: %v\n", err) }
C#
FirebaseApp.Create(new AppOptions() { Credential = GoogleCredential.FromFile("path/to/serviceAccountKey.json"), });
Initializing multiple apps
Typically, you'll only want to initialize a single, default app. However, you can also create multiple app instances, each with its own configuration options and authentication state.
Node.js
// Initialize the default app
admin.initializeApp(defaultAppConfig);
// Initialize another app with a different config
var otherApp = admin.initializeApp(otherAppConfig, 'other');
console.log(admin.app().name); // '[DEFAULT]'
console.log(otherApp.name); // 'other'
// Use the shorthand notation to retrieve the default app's services
var defaultAuth = admin.auth();
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);
Setting scopes
If you're using a Compute Engine VM with Google Application Default
Credentials for authentication, you''ll need to set the right
access scopes.
Identity Platform requires the userinfo.email
and cloud-platform
access scopes.
To check your existing access scopes, run the following:
gcloud compute instances describe [INSTANCE-NAME] --format json
The command will return information about the service account. For example:
"serviceAccounts": [
{
"email": "example.gserviceaccount.com",
"scopes": [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/userinfo.email"
]
}
]
To update access scopes, stop the VM, then run the following:
gcloud compute instances set-service-account [INSTANCE-NAME] \
--service-account "your.gserviceaccount.com" \
--scopes ""https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email"
What's next
- View the source code and additional documentation for the Admin SDK on GitHub:
- Migrate existing users to Identity Platform
- Manage SAML and OIDC providers programmatically
- Manage Identity Platform tenants