public class

FirebaseAuth

extends Object
java.lang.Object
   ↳ com.google.firebase.auth.FirebaseAuth

Class Overview

This class is the entry point for all server-side Firebase Authentication actions.

You can get an instance of FirebaseAuth via getInstance(FirebaseApp) and then use it to perform a variety of authentication-related operations, including generating custom tokens for use by client-side code, verifying Firebase ID Tokens received from clients, or creating new FirebaseApp instances that are scoped to a particular authentication UID.

Summary

Public Methods
String createCustomToken(String uid)
Creates a Firebase custom token for the given UID.
String createCustomToken(String uid, Map<String, Object> developerClaims)
Creates a Firebase custom token for the given UID, containing the specified additional claims.
ApiFuture<String> createCustomTokenAsync(String uid, Map<String, Object> developerClaims)
Similar to createCustomToken(String, Map) but performs the operation asynchronously.
ApiFuture<String> createCustomTokenAsync(String uid)
Similar to createCustomToken(String) but performs the operation asynchronously.
String createSessionCookie(String idToken, SessionCookieOptions options)
Creates a new Firebase session cookie from the given ID token and options.
ApiFuture<String> createSessionCookieAsync(String idToken, SessionCookieOptions options)
Similar to createSessionCookie(String, SessionCookieOptions) but performs the operation asynchronously.
UserRecord createUser(UserRecord.CreateRequest request)
Creates a new user account with the attributes contained in the specified UserRecord.CreateRequest.
ApiFuture<UserRecord> createUserAsync(UserRecord.CreateRequest request)
Similar to createUser(CreateRequest) but performs the operation asynchronously.
void deleteUser(String uid)
Deletes the user identified by the specified user ID.
ApiFuture<Void> deleteUserAsync(String uid)
Similar to deleteUser(String) but performs the operation asynchronously.
static FirebaseAuth getInstance()
Gets the FirebaseAuth instance for the default FirebaseApp.
synchronized static FirebaseAuth getInstance(FirebaseApp app)
Gets an instance of FirebaseAuth for a specific FirebaseApp.
UserRecord getUser(String uid)
Gets the user data corresponding to the specified user ID.
ApiFuture<UserRecord> getUserAsync(String uid)
Similar to getUser(String) but performs the operation asynchronously.
UserRecord getUserByEmail(String email)
Gets the user data corresponding to the specified user email.
ApiFuture<UserRecord> getUserByEmailAsync(String email)
Similar to getUserByEmail(String) but performs the operation asynchronously.
UserRecord getUserByPhoneNumber(String phoneNumber)
Gets the user data corresponding to the specified user phone number.
ApiFuture<UserRecord> getUserByPhoneNumberAsync(String phoneNumber)
Gets the user data corresponding to the specified user phone number.
ListUsersPage listUsers(String pageToken)
Gets a page of users starting from the specified pageToken.
ListUsersPage listUsers(String pageToken, int maxResults)
Gets a page of users starting from the specified pageToken.
ApiFuture<ListUsersPage> listUsersAsync(String pageToken, int maxResults)
Similar to listUsers(String, int) but performs the operation asynchronously.
ApiFuture<ListUsersPage> listUsersAsync(String pageToken)
Similar to listUsers(String) but performs the operation asynchronously.
void revokeRefreshTokens(String uid)
Revokes all refresh tokens for the specified user.
ApiFuture<Void> revokeRefreshTokensAsync(String uid)
Similar to revokeRefreshTokens(String) but performs the operation asynchronously.
void setCustomClaims(String uid, Map<String, Object> claims)
This method is deprecated. Use setCustomUserClaims(String, Map) instead.
void setCustomUserClaims(String uid, Map<String, Object> claims)
Sets the specified custom claims on an existing user account.
ApiFuture<Void> setCustomUserClaimsAsync(String uid, Map<String, Object> claims)
Similar to setCustomUserClaims(String, Map) but performs the operation asynchronously.
UserRecord updateUser(UserRecord.UpdateRequest request)
Updates an existing user account with the attributes contained in the specified UserRecord.UpdateRequest.
ApiFuture<UserRecord> updateUserAsync(UserRecord.UpdateRequest request)
Similar to updateUser(UpdateRequest) but performs the operation asynchronously.
FirebaseToken verifyIdToken(String token)
Parses and verifies a Firebase ID Token.
FirebaseToken verifyIdToken(String token, boolean checkRevoked)
Parses and verifies a Firebase ID Token.
ApiFuture<FirebaseToken> verifyIdTokenAsync(String token, boolean checkRevoked)
Similar to verifyIdToken(String, boolean) but performs the operation asynchronously.
ApiFuture<FirebaseToken> verifyIdTokenAsync(String token)
Similar to verifyIdToken(String) but performs the operation asynchronously.
FirebaseToken verifySessionCookie(String cookie)
Parses and verifies a Firebase session cookie.
FirebaseToken verifySessionCookie(String cookie, boolean checkRevoked)
Parses and verifies a Firebase session cookie.
ApiFuture<FirebaseToken> verifySessionCookieAsync(String cookie)
Similar to verifySessionCookie(String) but performs the operation asynchronously.
ApiFuture<FirebaseToken> verifySessionCookieAsync(String cookie, boolean checkRevoked)
Similar to verifySessionCookie(String, boolean) but performs the operation asynchronously.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public String createCustomToken (String uid)

Creates a Firebase custom token for the given UID. This token can then be sent back to a client application to be used with the signInWithCustomToken authentication API.

FirebaseApp must have been initialized with service account credentials to use call this method.

Parameters
uid The UID to store in the token. This identifies the user to other Firebase services (Realtime Database, Firebase Auth, etc.). Should be less than 128 characters.
Returns
  • A Firebase custom token string.
Throws
IllegalArgumentException If the specified uid is null or empty, or if the app has not been initialized with service account credentials.
FirebaseAuthException If an error occurs while generating the custom token.

public String createCustomToken (String uid, Map<String, Object> developerClaims)

Creates a Firebase custom token for the given UID, containing the specified additional claims. This token can then be sent back to a client application to be used with the signInWithCustomToken authentication API.

FirebaseApp must have been initialized with service account credentials to use call this method.

Parameters
uid The UID to store in the token. This identifies the user to other Firebase services (Realtime Database, Firebase Auth, etc.). Should be less than 128 characters.
developerClaims Additional claims to be stored in the token (and made available to security rules in Database, Storage, etc.). These must be able to be serialized to JSON (e.g. contain only Maps, Arrays, Strings, Booleans, Numbers, etc.)
Returns
  • A Firebase custom token string.
Throws
IllegalArgumentException If the specified uid is null or empty, or if the app has not been initialized with service account credentials.
FirebaseAuthException If an error occurs while generating the custom token.

public ApiFuture<String> createCustomTokenAsync (String uid, Map<String, Object> developerClaims)

Similar to createCustomToken(String, Map) but performs the operation asynchronously.

Parameters
uid The UID to store in the token. This identifies the user to other Firebase services (Realtime Database, Storage, etc.). Should be less than 128 characters.
developerClaims Additional claims to be stored in the token (and made available to security rules in Database, Storage, etc.). These must be able to be serialized to JSON (e.g. contain only Maps, Arrays, Strings, Booleans, Numbers, etc.)
Returns
  • An ApiFuture which will complete successfully with the created Firebase custom token, or unsuccessfully with the failure Exception.
Throws
IllegalArgumentException If the specified uid is null or empty, or if the app has not been initialized with service account credentials.

public ApiFuture<String> createCustomTokenAsync (String uid)

Similar to createCustomToken(String) but performs the operation asynchronously.

Parameters
uid The UID to store in the token. This identifies the user to other Firebase services (Realtime Database, Firebase Auth, etc.). Should be less than 128 characters.
Returns
  • An ApiFuture which will complete successfully with the created Firebase custom token, or unsuccessfully with the failure Exception.
Throws
IllegalArgumentException If the specified uid is null or empty, or if the app has not been initialized with service account credentials.

public String createSessionCookie (String idToken, SessionCookieOptions options)

Creates a new Firebase session cookie from the given ID token and options. The returned JWT can be set as a server-side session cookie with a custom cookie policy.

Parameters
idToken The Firebase ID token to exchange for a session cookie.
options Additional options required to create the cookie.
Returns
  • A Firebase session cookie string.
Throws
IllegalArgumentException If the ID token is null or empty, or if options is null.
FirebaseAuthException If an error occurs while generating the session cookie.

public ApiFuture<String> createSessionCookieAsync (String idToken, SessionCookieOptions options)

Similar to createSessionCookie(String, SessionCookieOptions) but performs the operation asynchronously.

Parameters
idToken The Firebase ID token to exchange for a session cookie.
options Additional options required to create the cookie.
Returns
  • An ApiFuture which will complete successfully with a session cookie string. If an error occurs while generating the cookie or if the specified ID token is invalid, the future throws a FirebaseAuthException.
Throws
IllegalArgumentException If the ID token is null or empty, or if options is null.

public UserRecord createUser (UserRecord.CreateRequest request)

Creates a new user account with the attributes contained in the specified UserRecord.CreateRequest.

Parameters
request A non-null UserRecord.CreateRequest instance.
Returns
  • A UserRecord instance corresponding to the newly created account.
Throws
NullPointerException if the provided request is null.
FirebaseAuthException if an error occurs while creating the user account.

public ApiFuture<UserRecord> createUserAsync (UserRecord.CreateRequest request)

Similar to createUser(CreateRequest) but performs the operation asynchronously.

Parameters
request A non-null UserRecord.CreateRequest instance.
Returns
  • An ApiFuture which will complete successfully with a UserRecord instance corresponding to the newly created account. If an error occurs while creating the user account, the future throws a FirebaseAuthException.
Throws
NullPointerException if the provided request is null.

public void deleteUser (String uid)

Deletes the user identified by the specified user ID.

Parameters
uid A user ID string.
Throws
IllegalArgumentException If the user ID string is null or empty.
FirebaseAuthException If an error occurs while deleting the user.

public ApiFuture<Void> deleteUserAsync (String uid)

Similar to deleteUser(String) but performs the operation asynchronously.

Parameters
uid A user ID string.
Returns
  • An ApiFuture which will complete successfully when the specified user account has been deleted. If an error occurs while deleting the user account, the future throws a FirebaseAuthException.
Throws
IllegalArgumentException If the user ID string is null or empty.

public static FirebaseAuth getInstance ()

Gets the FirebaseAuth instance for the default FirebaseApp.

Returns
  • The FirebaseAuth instance for the default FirebaseApp.

public static synchronized FirebaseAuth getInstance (FirebaseApp app)

Gets an instance of FirebaseAuth for a specific FirebaseApp.

Parameters
app The FirebaseApp to get a FirebaseAuth instance for.
Returns
  • A FirebaseAuth instance.

public UserRecord getUser (String uid)

Gets the user data corresponding to the specified user ID.

Parameters
uid A user ID string.
Returns
Throws
IllegalArgumentException If the user ID string is null or empty.
FirebaseAuthException If an error occurs while retrieving user data.

public ApiFuture<UserRecord> getUserAsync (String uid)

Similar to getUser(String) but performs the operation asynchronously.

Parameters
uid A user ID string.
Returns
  • An ApiFuture which will complete successfully with a UserRecord instance. If an error occurs while retrieving user data or if the specified user ID does not exist, the future throws a FirebaseAuthException.
Throws
IllegalArgumentException If the user ID string is null or empty.

public UserRecord getUserByEmail (String email)

Gets the user data corresponding to the specified user email.

Parameters
email A user email address string.
Returns
Throws
IllegalArgumentException If the email is null or empty.
FirebaseAuthException If an error occurs while retrieving user data.

public ApiFuture<UserRecord> getUserByEmailAsync (String email)

Similar to getUserByEmail(String) but performs the operation asynchronously.

Parameters
email A user email address string.
Returns
  • An ApiFuture which will complete successfully with a UserRecord instance. If an error occurs while retrieving user data or if the email address does not correspond to a user, the future throws a FirebaseAuthException.
Throws
IllegalArgumentException If the email is null or empty.

public UserRecord getUserByPhoneNumber (String phoneNumber)

Gets the user data corresponding to the specified user phone number.

Parameters
phoneNumber A user phone number string.
Returns
Throws
IllegalArgumentException If the phone number is null or empty.
FirebaseAuthException If an error occurs while retrieving user data.

public ApiFuture<UserRecord> getUserByPhoneNumberAsync (String phoneNumber)

Gets the user data corresponding to the specified user phone number.

Parameters
phoneNumber A user phone number string.
Returns
  • An ApiFuture which will complete successfully with a UserRecord instance. If an error occurs while retrieving user data or if the phone number does not correspond to a user, the future throws a FirebaseAuthException.
Throws
IllegalArgumentException If the phone number is null or empty.

public ListUsersPage listUsers (String pageToken)

Gets a page of users starting from the specified pageToken. Page size will be limited to 1000 users.

Parameters
pageToken A non-empty page token string, or null to retrieve the first page of users.
Returns
Throws
IllegalArgumentException If the specified page token is empty.
FirebaseAuthException If an error occurs while retrieving user data.

public ListUsersPage listUsers (String pageToken, int maxResults)

Gets a page of users starting from the specified pageToken.

Parameters
pageToken A non-empty page token string, or null to retrieve the first page of users.
maxResults Maximum number of users to include in the returned page. This may not exceed 1000.
Returns
Throws
IllegalArgumentException If the specified page token is empty, or max results value is invalid.
FirebaseAuthException If an error occurs while retrieving user data.

public ApiFuture<ListUsersPage> listUsersAsync (String pageToken, int maxResults)

Similar to listUsers(String, int) but performs the operation asynchronously.

Parameters
pageToken A non-empty page token string, or null to retrieve the first page of users.
maxResults Maximum number of users to include in the returned page. This may not exceed 1000.
Returns
  • An ApiFuture which will complete successfully with a ListUsersPage instance. If an error occurs while retrieving user data, the future throws an exception.
Throws
IllegalArgumentException If the specified page token is empty, or max results value is invalid.

public ApiFuture<ListUsersPage> listUsersAsync (String pageToken)

Similar to listUsers(String) but performs the operation asynchronously.

Parameters
pageToken A non-empty page token string, or null to retrieve the first page of users.
Returns
  • An ApiFuture which will complete successfully with a ListUsersPage instance. If an error occurs while retrieving user data, the future throws an exception.
Throws
IllegalArgumentException If the specified page token is empty.

public void revokeRefreshTokens (String uid)

Revokes all refresh tokens for the specified user.

Updates the user's tokensValidAfterTimestamp to the current UTC time expressed in milliseconds since the epoch and truncated to 1 second accuracy. It is important that the server on which this is called has its clock set correctly and synchronized.

While 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 verifyIdTokenAsync(String, boolean).

Parameters
uid The user id for which tokens are revoked.
Throws
IllegalArgumentException If the user ID is null or empty.
FirebaseAuthException If an error occurs while revoking tokens.

public ApiFuture<Void> revokeRefreshTokensAsync (String uid)

Similar to revokeRefreshTokens(String) but performs the operation asynchronously.

Parameters
uid The user id for which tokens are revoked.
Returns
  • An ApiFuture which will complete successfully or fail with a FirebaseAuthException in the event of an error.
Throws
IllegalArgumentException If the user ID is null or empty.

public void setCustomClaims (String uid, Map<String, Object> claims)

This method is deprecated.
Use setCustomUserClaims(String, Map) instead.

Throws
FirebaseAuthException

public void setCustomUserClaims (String uid, Map<String, Object> claims)

Sets the specified custom claims on an existing user account. A null claims value removes any claims currently set on the user account. The claims should serialize into a valid JSON string. The serialized claims must not be larger than 1000 characters.

Parameters
uid A user ID string.
claims A map of custom claims or null.
Throws
FirebaseAuthException If an error occurs while updating custom claims.
IllegalArgumentException If the user ID string is null or empty, or the claims payload is invalid or too large.

public ApiFuture<Void> setCustomUserClaimsAsync (String uid, Map<String, Object> claims)

Similar to setCustomUserClaims(String, Map) but performs the operation asynchronously.

Parameters
uid A user ID string.
claims A map of custom claims or null.
Returns
  • An ApiFuture which will complete successfully when the user account has been updated. If an error occurs while deleting the user account, the future throws a FirebaseAuthException.
Throws
IllegalArgumentException If the user ID string is null or empty.

public UserRecord updateUser (UserRecord.UpdateRequest request)

Updates an existing user account with the attributes contained in the specified UserRecord.UpdateRequest.

Parameters
request A non-null UserRecord.UpdateRequest instance.
Returns
Throws
NullPointerException if the provided update request is null.
FirebaseAuthException if an error occurs while updating the user account.

public ApiFuture<UserRecord> updateUserAsync (UserRecord.UpdateRequest request)

Similar to updateUser(UpdateRequest) but performs the operation asynchronously.

Parameters
request A non-null UserRecord.UpdateRequest instance.
Returns
  • An ApiFuture which will complete successfully with a UserRecord instance corresponding to the updated user account. If an error occurs while updating the user account, the future throws a FirebaseAuthException.

public FirebaseToken verifyIdToken (String token)

Parses and verifies a Firebase ID Token.

A Firebase application can identify itself to a trusted backend server by sending its Firebase ID Token (accessible via the getToken API in the Firebase Authentication client) with its requests. The backend server can then use the verifyIdToken() method to verify that the token is valid. This method ensures that the token is correctly signed, has not expired, and it was issued to the Firebase project associated with this FirebaseAuth instance.

This method does not check whether a token has been revoked. Use verifyIdToken(String, boolean) to perform an additional revocation check.

Parameters
token A Firebase ID token string to parse and verify.
Returns
Throws
IllegalArgumentException If the token is null, empty, or if the FirebaseApp instance does not have a project ID associated with it.
FirebaseAuthException If an error occurs while parsing or validating the token.

public FirebaseToken verifyIdToken (String token, boolean checkRevoked)

Parses and verifies a Firebase ID Token.

A Firebase application can identify itself to a trusted backend server by sending its Firebase ID Token (accessible via the getToken API in the Firebase Authentication client) with its requests. The backend server can then use the verifyIdToken() method to verify that the token is valid. This method ensures that the token is correctly signed, has not expired, and it was issued to the Firebase project associated with this FirebaseAuth instance.

If checkRevoked is set to true, this method performs an additional check to see if the ID token has been revoked since it was issues. This requires making an additional remote API call.

Parameters
token A Firebase ID token string to parse and verify.
checkRevoked A boolean denoting whether to check if the tokens were revoked.
Returns
Throws
IllegalArgumentException If the token is null, empty, or if the FirebaseApp instance does not have a project ID associated with it.
FirebaseAuthException If an error occurs while parsing or validating the token.

public ApiFuture<FirebaseToken> verifyIdTokenAsync (String token, boolean checkRevoked)

Similar to verifyIdToken(String, boolean) but performs the operation asynchronously.

Parameters
token A Firebase ID Token to verify and parse.
checkRevoked A boolean denoting whether to check if the tokens were revoked.
Returns
  • An ApiFuture which will complete successfully with the parsed token, or unsuccessfully with a FirebaseAuthException.
Throws
IllegalArgumentException If the token is null, empty, or if the FirebaseApp instance does not have a project ID associated with it.

public ApiFuture<FirebaseToken> verifyIdTokenAsync (String token)

Similar to verifyIdToken(String) but performs the operation asynchronously.

Parameters
token A Firebase ID Token to verify and parse.
Returns
  • An ApiFuture which will complete successfully with the parsed token, or unsuccessfully with a FirebaseAuthException.
Throws
IllegalArgumentException If the token is null, empty, or if the FirebaseApp instance does not have a project ID associated with it.

public FirebaseToken verifySessionCookie (String cookie)

Parses and verifies a Firebase session cookie.

If verified successfully, returns a parsed version of the cookie from which the UID and the other claims can be read. If the cookie is invalid, throws a FirebaseAuthException.

This method does not check whether the cookie has been revoked. See verifySessionCookie(String, boolean).

Parameters
cookie A Firebase session cookie string to verify and parse.
Returns
Throws
FirebaseAuthException

public FirebaseToken verifySessionCookie (String cookie, boolean checkRevoked)

Parses and verifies a Firebase session cookie.

If checkRevoked is true, additionally verifies that the cookie has not been revoked.

If verified successfully, returns a parsed version of the cookie from which the UID and the other claims can be read. If the cookie is invalid or has been revoked while checkRevoked is true, throws a FirebaseAuthException.

Parameters
cookie A Firebase session cookie string to verify and parse.
checkRevoked A boolean indicating whether to check if the cookie was explicitly revoked.
Returns
Throws
FirebaseAuthException

public ApiFuture<FirebaseToken> verifySessionCookieAsync (String cookie)

Similar to verifySessionCookie(String) but performs the operation asynchronously.

Parameters
cookie A Firebase session cookie string to verify and parse.
Returns
  • An ApiFuture which will complete successfully with the parsed cookie, or unsuccessfully with the failure Exception.

public ApiFuture<FirebaseToken> verifySessionCookieAsync (String cookie, boolean checkRevoked)

Similar to verifySessionCookie(String, boolean) but performs the operation asynchronously.

Parameters
cookie A Firebase session cookie string to verify and parse.
checkRevoked A boolean indicating whether to check if the cookie was explicitly revoked.
Returns
  • An ApiFuture which will complete successfully with the parsed cookie, or unsuccessfully with the failure Exception.