You're viewing the legacy docs. They are deprecated as of May 18, 2016.
Go to current docs

REST Guide

User Authorization

Overview

Most applications need to know the identity of a user. Knowing a user's identity allows an app to provide a customized experience and grant them permissions to access their data. The process of proving a user's identity is called authentication. Firebase provides a full set of authentication options out-of-the-box.

When a user authenticates to a Firebase app, two things happen:

  • Information about the user is returned in callbacks on the client device. This allows you to customize your app's user experience for that specific user.
  • The value of the auth variable in your app's Security and Firebase Rules becomes defined. This variable is null for unauthenticated users, but for authenticated users it is an object containing the user's unique (auth.uid) and potentially other data about the user. This allows you to securely control data access on a per-user basis.

The Firebase JavaScript, Java, and Objective-C libraries provide built-in functionality for many login providers, but the REST API works a little differently. The REST API's goal is to be flexible and platform independent. Custom Login aligns with this goal by allowing you to generate user login tokens with your own server side code.

Firebase apps give you complete control over user authentication by allowing you to authenticate users using secure JSON Web Tokens (JWTs). This method of authentication is useful in cases where you are already managing user accounts on your server, where you have more advanced authentication needs, or for authenticating server-side workers.

Generating a Secure Token

To authenticate a user with Custom Login, we must provide each client with a secure JWT that has been generated on a server. There are several helper libraries for generating JWTs given a Firebase app's secret. Our secret can be found under the Secrets tab in our Firebase app's dashboard.

Firebase JWTs should always be generated on a trusted server so that the Firebase app secret which is needed to generate them can be kept private. Here are some examples of generating JWTs on a server using several different languages:

var FirebaseTokenGenerator = require("firebase-token-generator");
var tokenGenerator = new FirebaseTokenGenerator("<YOUR_FIREBASE_SECRET>");
var token = tokenGenerator.createToken({ uid: "uniqueId1", some: "arbitrary", data: "here" });
Map<String, Object> payload = new HashMap<String, Object>();
payload.put("uid", "uniqueId1");
payload.put("some", "arbitrary");
payload.put("data", "here");

TokenGenerator tokenGenerator = new TokenGenerator("<YOUR_FIREBASE_SECRET>");
String token = tokenGenerator.createToken(payload);
var tokenGenerator = new Firebase.TokenGenerator("<YOUR_FIREBASE_SECRET>");
var authPayload = new Dictionary<string, object>()
{
  { "uid", "uniqueId1" },
  { "some", "arbitrary" },
  { "data", "here" }
};
string token = tokenGenerator.CreateToken(authPayload);
<?php
  include_once "FirebaseToken.php";

  $tokenGen = new Services_FirebaseTokenGenerator("<YOUR_FIREBASE_SECRET>");
  $token = $tokenGen->createToken(array("uid" => "uniqueId1"));
?>
from firebase_token_generator import create_token

auth_payload = { "uid": "uniqueId1", "auth_data": "foo", "other_auth_data": "bar" }
token = create_token("<YOUR_FIREBASE_SECRET>", auth_payload)
require "firebase_token_generator"

payload = { :uid => "uniqueId1", :auth_data => "foo", :other_auth_data => "bar" }

generator = Firebase::FirebaseTokenGenerator.new("<YOUR_FIREBASE_SECRET>")
token = generator.create_token(payload)

When authenticating with a secure JWT, the data encoded in the token will be accessible in the Security and Firebase Rules as the auth variable. This allows rules to be written which grant access based on the data within the token.

Token Restrictions

The token payload can contain any data of your choosing with the restriction that it must contain a uid key that is a string of less than 256 characters. The generated token's total payload must also be less than 1024 characters.

By default, authentication tokens expire 24 hours after they are issued and the client will automatically be unauthenticated at that time. You can override this by changing the session length setting under the Login & Auth tab of your App Dashboard, or individually when creating the token by providing a specific expiration date. For details, see the docs for the specific token generator library you're using.

To handle token expiration gracefully, the client libraries for each platform (web, iOS, and Android) provide methods (onAuth(), observeAuthEventWithBlock:, and addAuthStateListener(), respectively), which trigger the provided callback or block whenever the authentication state changes.

Authenticating Requests

Once we've generated a secure JWT, we can use the auth request parameter to access data protected by Security and Firebase Rules. The argument can either be your Firebase app's secret or an authentication token.

curl 'https://docs-examples.firebaseio.com/rest/saving-data/auth-example.json?auth=CREDENTIAL'
If the token's debug flag is set, debug information can be found in the X-Firebase-Auth-Debug header of the response.

Authenticating Servers

If we are running a trusted server that is connecting to our Firebase database, we can authenticate it in several ways:

  1. Using a Firebase app secret: All authentication methods can accept a Firebase app secret instead of a JWT token. This will grant the server complete read and write access to the entire Firebase database. This access will never expire unless it is revoked via the App Dashboard.
  2. Using a secure JWT with the optional admin claim set to true: This method will grant a server complete read and write access to the entire Firebase database. This token will expire normally, so it is important to set the expiration times accordingly.
  3. Using a secure JWT designed to give access to only the pieces of data a server needs to touch: This method is more complicated, but it is the safest way to authenticate a server as it lets the Security and Firebase Rules prevent the server from doing anything it's not supposed to, even if it becomes compromised in some way.

Generating a Token Without a Helper Library

Firebase app JWTs can also be generated with any existing JWT generation library and then signed by a SHA-256 HMAC signature. When using an existing library, a Firebase app auth token must contain the following claims:

Claim Description
v The version of the token. Set this to the number 0.
iat The "issued at" date as a number of seconds since the Unix epoch.
d The authentication data. This is the payload of the token that will become visible as the auth variable in the Security and Firebase Rules.

The following claims are optional when using an authentication token:

Claim Description
nbf The token "not before" date as a number of seconds since the Unix epoch. If specified, the token will not be considered valid until after this date.
exp The token expiration date as a number of seconds since the Unix epoch. If not specified, by default the token will expire 24 hours after the "issued at" date (iat).
admin Set to true to make this an "admin" token, which grants full read and write access to all data.
debug Set to true to enable debug mode, which provides verbose error messages when Security and Firebase Rules fail.

Helper Libraries

Language
Go (Unofficial)
Java
.NET
Node.js
Perl (Unofficial)
PHP
Python
Ruby
  1. 1

    Next

    Installation & Setup

  2. 2

    Next

    Understanding Data

  3. 3

    Next

    Saving Data

  4. 4

    Next

    Retrieving Data

  5. 5

    Next

    Structuring Data

  6. 6

    Next

    Understanding Security

  7. 7

    Next

    User Authentication

  8. 8

    Next

    App Management