Custom Login

Firebase gives 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 servers or where you have more advanced authentication needs.

Generating A Secure Token

To authenticate a user using Custom Login, you must provide each client with a secure JWT that you've generated on your servers. We provide several helper libraries for generating JWTs. You'll need to use your Firebase Secret to generate these tokens, which can be found by logging into your Firebase account and clicking on the Security tab in your Firebase debugger.

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

// Generate a new secure JWT
var FirebaseTokenGenerator = require("firebase-token-generator");
var tokenGenerator = new FirebaseTokenGenerator(YOUR_FIREBASE_SECRET);
var token = tokenGenerator.createToken({some: "arbitrary", data: "here"});

// Generate a new secure JWT
JSONObject arbitraryPayload = new JSONObject();
try {
    arbitraryPayload.put("some", "arbitrary");
    arbitraryPayload.put("data", "here");
} catch (JSONException e) {
    e.printStackTrace();
}   

TokenGenerator tokenGenerator = new TokenGenerator(YOUR_FIREBASE_SECRET);
String token = tokenGenerator.createToken(arbitraryPayload);

System.out.println(token);

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

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 when creating the token by providing a specific expiration date (for details, see the docs for the token generator you're using).

To help you handle token expiration gracefully in your application, the authentication function (JS, Obj-C, Java) in the client library for each platform allows you to set a 'cancel' callback that is triggered when a token expires. You can also use the authentication info provided by the authentication function's success callback to tell in advance when the token will expire.

Authenticating Your Clients

Once you have generated a secure JWT, you can use any Firebase reference to authenticate using an authentication method (JS, Obj-C, Java).

var dataRef = new Firebase("https://<YOUR-FIREBASE>.firebaseio.com/");
// Log me in.
dataRef.auth(AUTH_TOKEN, function(error) {
  if(error) {
    console.log("Login Failed!", error);
  } else {
    console.log("Login Succeeded!");
  }
});

Firebase* dataRef = [[Firebase alloc] initWithUrl:@"https://<YOUR-FIREBASE>.firebaseio.com/"];
// Log me in.
[dataRef authWithCredential:AUTH_TOKEN withCompletionBlock:^(NSError* error, id authData) {
  if (error != nil) {
    NSLog(@"Login Failed! %@", error);
  } else {
    NSLog(@"Login Succeeded!");
  }
} withCancelBlock:^(NSError* error) {
  NSLog(@"Authentication status was cancelled! %@", error);
}];

Firebase dataRef = new Firebase("https://<YOUR-FIREBASE>.firebaseio.com/");
// Log me in.
dataRef.auth(AUTH_TOKEN, new Firebase.AuthListener() {

    @Override
    public void onAuthError(FirebaseError error) {
        System.err.println("Login Failed! " + error.getMessage());
    }

    @Override
    public void onAuthSuccess(Object authData) {
        System.out.println("Login Succeeded!");
    }

    @Override
    public void onAuthRevoked(FirebaseError error) {
        System.err.println("Authenticcation status was cancelled! " + error.getMessage());
    }

});

Calling an authentication method on any Firebase reference will authenticate you to the entire Firebase. If your app loses its internet connection, Firebase will automatically handle re-authenticating to the server when it reconnects. If you need to change a client's credentials (for example, when a user logs in to a different account), simply re-authenticate with a new token.

It is not possible to authenticate with multiple credentials to the same Firebase simaltaneously, even if you call .auth on different Firebase references. Authentication state is global and applies to all references to your Firebase. However, it is possible to create references to two (or more) different Firebases and authenticate to those independently.

To unauthenticate a client (such as when a user logs out), use the unauth (JS, Obj-C, Java) method:

// Log me out.
dataRef.unauth();

// Log me out.
[dataRef unauth];

// Log me out.
dataRef.unauth();

Authenticating Your Server

If you are running a trusted server that is connecting to your Firebase, you can authenticate it in several ways:

  1. Using a Firebase Secret. All authentication methods can accept your Firebase Secret instead of a JWT token. This will grant your server complete read / write access to your entire Firebase. This access will never expire unless you revoke the Secret from your Firebase.

  2. Using a secure JWT with the optional "admin" claim set to true. This method will grant your server complete read / write access to your entire Firebase. This token will expire normally, so make sure to set the expiration times accordingly.

  3. Using a secure JWT designed to give access to only the pieces of data your server needs to touch. This method is somewhat more complicated, but it is the safest way to authenticate a server, as it lets your Security Rules prevent your server from doing anything it's not supposed to, even if it has bugs or becomes compromised in some way.

Generating A Secure Token Without a Helper Library

Firebase JWTs can also be generated with any existing JWT generation library then signed by a SHA-256 HMAC signature. If you use an existing library, a Firebase authentication 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 epoch.
d The authentication data. This is the payload of the token that will become visible as the auth variable in the Security Rules.

These claims are optional:

Claim Description
nbf The token "not before" date as a number of seconds since the 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 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/write access to all data.
debug Set to true to enable debug mode, which provides verbose error messages when Security Rules fail.

Helper Libraries

We provide helper libraries to generate these tokens for various languages, including:


Have a suggestion to improve the documentation on this page? Tell us!