Authentication

Before you start, please read about Firebase Authentication in the official documentation:

Before you can access the Firebase Realtime Database from a server using the Firebase Admin 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 two different levels of access when you authenticate using the Firebase Admin SDK:

Administrative privileges: Complete read and write access to a project’s Realtime Database. Use with caution to complete administrative tasks such as data migration or restructuring that require unrestricted access to your project’s resources.

Limited privileges: Access to a project’s Realtime Database, limited to only the resources your server needs. Use this level to complete administrative tasks that have well-defined access requirements. For example, when running a summarization job that reads data across the entire database, you can protect against accidental writes by setting a read-only security rule and then initializing the Admin SDK with privileges limited by that rule.

Initializing the Auth component

With the SDK

$auth = $factory->createAuth();

With Dependency Injection (Symfony Bundle/Laravel/Lumen Package)

use Kreait\Firebase\Auth;

class MyService
{
    public function __construct(Auth $auth)
    {
        $this->auth = $auth;
    }
}

With the Laravel app() helper (Laravel/Lumen Package)

$auth = app('firebase.auth');

Create custom tokens

The Firebase Admin SDK has a built-in method for creating custom tokens. At a minimum, you need to provide a uid, which can be any string but should uniquely identify the user or device you are authenticating. These tokens expire after one hour.

$uid = 'some-uid';

$customToken = $auth->createCustomToken($uid);

You can also optionally specify additional claims to be included in the custom token. For example, below, a premiumAccount field has been added to the custom token, which will be available in the auth / request.auth objects in your Security Rules:

$uid = 'some-uid';
$additionalClaims = [
    'premiumAccount' => true
];

$customToken = $auth->createCustomToken($uid, $additionalClaims);

$customTokenString = (string) $customToken;

Note

This library uses lcobucci/jwt to work with JSON Web Tokens (JWT). You can find the usage instructions at https://github.com/lcobucci/jwt/blob/3.2/README.md.

Verify a Firebase ID Token

If a Firebase client app communicates with your server, you might need to identify the currently signed-in user. To do so, verify the integrity and authenticity of the ID token and retrieve the uid from it. You can use the uid transmitted in this way to securely identify the currently signed-in user on your server.

Note

Many use cases for verifying ID tokens on the server can be accomplished by using Security Rules for the Firebase Realtime Database and Cloud Storage. See if those solve your problem before verifying ID tokens yourself.

Warning

The ID token verification methods included in the Firebase Admin SDKs are meant to verify ID tokens that come from the client SDKs, not the custom tokens that you create with the Admin SDKs. See Auth tokens for more information.

Use Auth::verifyIdToken() to verify an ID token:

use Firebase\Auth\Token\Exception\InvalidToken;

$idTokenString = '...';

try {
    $verifiedIdToken = $auth->verifyIdToken($idTokenString);
} catch (\InvalidArgumentException $e) {
    echo 'The token could not be parsed: '.$e->getMessage();
} catch (InvalidToken $e) {
    echo 'The token is invalid: '.$e->getMessage();
}

$uid = $verifiedIdToken->getClaim('sub');
$user = $auth->getUser($uid);

Auth::verifyIdToken() accepts the following parameters:

Parameter Type Description
idToken string|Token (required) The ID token to verify
checkIfRevoked boolean (optional, default: false ) check if the ID token is revoked

Note

A leeway of 5 minutes is applied when verifying time based claims starting with release 4.25.0

Note

This library uses lcobucci/jwt to work with JSON Web Tokens (JWT). You can find the usage instructions at https://github.com/lcobucci/jwt/blob/3.2/README.md.

Caching Google’s public keys

In order to verify ID tokens, the verifier makes a call to fetch Firebase’s currently available public keys. The keys are cached in memory by default.

If you want to cache the public keys more effectively, you can provide any implementation of psr/simple-cache to the Firebase factory when creating your Firebase instance.

For Symfony and Laravel, the Frameworks cache will automatically be used.

Here is an example using the Symfony Cache Component:

use Kreait\Firebase\Factory;
use Symfony\Component\Cache\Simple\FilesystemCache;

$cache = new FilesystemCache();

$factory = (new Factory)
    ->withServiceAccount('/path/to/google-service-account.json')
    ->withVerifierCache($cache);

Custom Authentication Flows

Available since v4.41

Warning

It is recommended that you use the Firebase Client SDKs to perform user authentication. Once signed in via a client SDK, you should pass the logged-in user’s current ID token to your PHP endpoint and verify the ID token with each request to your backend.

Each of the methods documented below will return an instance of Kreait\Firebase\Auth\SignInResult\SignInResult with the following accessors:

use Kreait\Firebase\Auth;

// $signInResult = $auth->signIn*()

$signInResult->idToken(); // string|null
$signInResult->accessToken(); // string|null
$signInResult->refreshToken(); // string|null
$signInResult->data(); // array
$signInResult->asTokenResponse(); // array

SignInResult::data() returns the full payload of the response returned by the Firebase API, SignInResult::asTokenResponse() returns the Sign-In result in a format that can be returned to clients:

$tokenResponse = [
    'token_type' => 'Bearer',
    'access_token' => '...',
    'id_token' => '...',
    'refresh_token' => '...',
    'expires_in' => 3600,
];

Note

Not all sign-in methods return all types of tokens.

Anonymous Sign In

Note

This method will create a new user in the Firebase Auth User Database each time it is invoked

$signInResult = $auth->signInAnonymously();

Sign In with Email and Password

$signInResult = $auth->signInWithEmailAndPassword($email, $clearTextPassword);

Sign In with a Custom Token

$signInResult = $auth->signInWithCustomToken($customToken);

Sign In with a Refresh Token

$signInResult = $auth->signInWithRefreshToken($refreshToken);

Sign In without a token

$signInResult = $auth->signInAsUser($userOrUid, array $claims = null);

Invalidate user sessions

This will revoke all sessions for a specified user and disable any new ID tokens for existing sessions from getting minted. Existing ID tokens may remain active until their natural expiration (one hour). To verify that ID tokens are revoked, use Auth::verifyIdToken() with the second parameter set to true.

If the check fails, a RevokedIdToken exception will be thrown.

use Kreait\Firebase\Exception\Auth\RevokedIdToken;

$auth->revokeRefreshTokens($uid);

try {
    $verifiedIdToken = $auth->verifyIdToken($idTokenString, $checkIfRevoked = true);
} catch (RevokedIdToken $e) {
    echo $e->getMessage();
}

Note

Because Firebase ID tokens are stateless JWTs, you can determine a token has been revoked only by requesting the token’s status from the Firebase Authentication backend. For this reason, performing this check on your server is an expensive operation, requiring an extra network round trip. You can avoid making this network request by setting up Firebase Rules that check for revocation rather than using the Admin SDK to make the check.

For more information, please visit Google: Detect ID token revocation in Database Rules