Installation & Setup for Servers

In this document, we'll guide you through adding the Firebase Server SDK to your project.

Create an account and configure your project

Within the Firebase console you can create, manage and delete Firebase projects. Clicking on the Database panel of a specific Firebase project lets you view and modify your app's data in realtime. In your app dashboard, you can also set Security and Firebase Rules, manage your app's authentication, deploys, and view analytics.

Server SDK Setup

To get started with the Firebase Realtime Database on your server, you'll first need to set up the Firebase Server SDK in your language of choice.

Server SDK Authentication

Before you can access the Firebase Realtime Database from a server using the Firebase Server SDK, you must authenticate your server with Firebase. When you authenticate a server, rather than sign in with a user account's credentials as you would in a client app, you authenticate with a service account which identifies your server to Firebase.

You can get three different levels of access when you authenticate using the Firebase Server SDK:

Authenticate with admin privileges

When you initialize a FirebaseApp with the credentials for a service account with the Editor role on your Firebase project, that instance has complete read and write access to your project's Realtime Database.

// Initialize the app with a service account, granting admin privileges
FirebaseOptions options = new FirebaseOptions.Builder()
    .setDatabaseUrl("https://databaseName.firebaseio.com")
    .setServiceAccount(new FileInputStream("path/to/serviceAccountCredentials.json"))
    .build();
FirebaseApp.initializeApp(options);

// As an admin, the app has access to read and write all data, regardless of Security Rules
DatabaseReference ref = FirebaseDatabase
    .getInstance()
    .getReference("restricted_access/secret_document");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
    @Override
    public void onDataChange(DataSnapshot dataSnapshot) {
        Object document = dataSnapshot.getValue();
        System.out.println(document);
    }
});

var firebase = require("firebase");

// Initialize the app with a service account, granting admin privileges
firebase.initializeApp({
  databaseURL: "https://databaseName.firebaseio.com",
  serviceAccount: "path/to/serviceAccountCredentials.json"
});

// As an admin, the app has access to read and write all data, regardless of Security Rules
var db = firebase.database();
var ref = db.ref("restricted_access/secret_document");
ref.once("value", function(snapshot) {
  console.log(snapshot.val());
});

Authenticate with limited privileges

As a best practice, a service should have access to only the resources it needs. To get more fine-grained control over the resources a FirebaseApp instance can access, use a unique identifier in your Security Rules to represent your service. Then set up appropriate rules which grant your service access to the resources it needs. For example:

{
  "rules": {
    "some_resource": {
      ".read": "auth.uid === 'my-service-worker'",
      ".write": false
    },
    "another_resource": {
      ".read": "auth.uid === 'my-service-worker'",
      ".write": "auth.uid === 'my-service-worker'"
    }
  }
}

Then, on your server, when you initialize the FirebaseApp object, use the databaseAuthVariableOverride parameter to override the auth object used by your database rules. In this custom auth object, set the uid field to the identifier you used to represent your service in your Security Rules.

// Initialize the app with a custom auth variable, limiting the server's access
Map<String, Object> auth = new HashMap<String, Object>();
auth.put("uid", "my-service-worker");

FirebaseOptions options = new FirebaseOptions.Builder()
    .setDatabaseUrl("https://databaseName.firebaseio.com")
    .setServiceAccount(new FileInputStream("path/to/serviceAccountCredentials.json"))
    .setDatabaseAuthVariableOverride(auth)
    .build();
FirebaseApp.initializeApp(options);

// The app only has access as defined in the Security Rules
DatabaseReference ref = FirebaseDatabase
    .getInstance()
    .getReference("/some_resource");
ref.addListenerForSingleValueEvent(new ValueEventListener() {
    @Override
    public void onDataChange(DataSnapshot dataSnapshot) {
        String res = dataSnapshot.getValue();
        System.out.println(res);
    }
});

var firebase = require("firebase");

// Initialize the app with a custom auth variable, limiting the server's access
firebase.initializeApp({
  databaseURL: "https://databaseName.firebaseio.com",
  serviceAccount: "path/to/serviceAccountCredentials.json",
  databaseAuthVariableOverride: {
    uid: "my-service-worker"
  }
});

// The app only has access as defined in the Security Rules
var db = firebase.database();
var ref = db.ref("/some_resource");
ref.once("value", function(snapshot) {
  console.log(snapshot.val());
});

Unauthenticated access

var firebase = require("firebase");

// Initialize the app with no authentication
firebase.initializeApp({
  databaseURL: "https://databaseName.firebaseio.com"
});

// The app only has access to public data as defined in the Security Rules
var db = firebase.database();
var ref = db.ref("/some_public_resource");
ref.once("value", function(snapshot) {
  console.log(snapshot.val());
});