firebase_admin.auth module

Firebase Authentication module.

This module contains functions for minting and verifying JWTs used for authenticating against Firebase services. It also provides functions for creating and managing user accounts in Firebase projects.

Exceptions

CertificateFetchError

exception firebase_admin.auth.CertificateFetchError(message, cause)

Bases: UnknownError

Failed to fetch some public key certificates required to verify a token.

ConfigurationNotFoundError

exception firebase_admin.auth.ConfigurationNotFoundError(message, cause=None, http_response=None)

Bases: NotFoundError

No auth provider found for the specified identifier.

default_message = 'No auth provider found for the given identifier'

EmailAlreadyExistsError

exception firebase_admin.auth.EmailAlreadyExistsError(message, cause, http_response)

Bases: AlreadyExistsError

The user with the provided email already exists.

default_message = 'The user with the provided email already exists'

EmailNotFoundError

exception firebase_admin.auth.EmailNotFoundError(message, cause=None, http_response=None)

Bases: NotFoundError

No user record found for the specified email.

default_message = 'No user record found for the given email'

ExpiredIdTokenError

exception firebase_admin.auth.ExpiredIdTokenError(message, cause)

Bases: InvalidIdTokenError

The provided ID token is expired.

ExpiredSessionCookieError

exception firebase_admin.auth.ExpiredSessionCookieError(message, cause)

Bases: InvalidSessionCookieError

The provided session cookie is expired.

InsufficientPermissionError

exception firebase_admin.auth.InsufficientPermissionError(message, cause, http_response)

Bases: PermissionDeniedError

The credential used to initialize the SDK lacks required permissions.

default_message = 'The credential used to initialize the SDK has insufficient permissions to perform the requested operation. See https://firebase.google.com/docs/admin/setup for details on how to initialize the Admin SDK with appropriate permissions'

InvalidDynamicLinkDomainError

exception firebase_admin.auth.InvalidDynamicLinkDomainError(message, cause, http_response)

Bases: InvalidArgumentError

Dynamic link domain in ActionCodeSettings is not authorized.

default_message = 'Dynamic link domain specified in ActionCodeSettings is not authorized'

InvalidIdTokenError

exception firebase_admin.auth.InvalidIdTokenError(message, cause=None, http_response=None)

Bases: InvalidArgumentError

The provided ID token is not a valid Firebase ID token.

default_message = 'The provided ID token is invalid'

InvalidSessionCookieError

exception firebase_admin.auth.InvalidSessionCookieError(message, cause=None)

Bases: InvalidArgumentError

The provided string is not a valid Firebase session cookie.

PhoneNumberAlreadyExistsError

exception firebase_admin.auth.PhoneNumberAlreadyExistsError(message, cause, http_response)

Bases: AlreadyExistsError

The user with the provided phone number already exists.

default_message = 'The user with the provided phone number already exists'

ResetPasswordExceedLimitError

exception firebase_admin.auth.ResetPasswordExceedLimitError(message, cause=None, http_response=None)

Bases: ResourceExhaustedError

Reset password emails exceeded their limits.

RevokedIdTokenError

exception firebase_admin.auth.RevokedIdTokenError(message)

Bases: InvalidIdTokenError

The provided ID token has been revoked.

RevokedSessionCookieError

exception firebase_admin.auth.RevokedSessionCookieError(message)

Bases: InvalidSessionCookieError

The provided session cookie has been revoked.

TokenSignError

exception firebase_admin.auth.TokenSignError(message, cause)

Bases: UnknownError

Unexpected error while signing a Firebase custom token.

TooManyAttemptsTryLaterError

exception firebase_admin.auth.TooManyAttemptsTryLaterError(message, cause=None, http_response=None)

Bases: ResourceExhaustedError

Rate limited because of too many attempts.

UidAlreadyExistsError

exception firebase_admin.auth.UidAlreadyExistsError(message, cause, http_response)

Bases: AlreadyExistsError

The user with the provided uid already exists.

default_message = 'The user with the provided uid already exists'

UnexpectedResponseError

exception firebase_admin.auth.UnexpectedResponseError(message, cause=None, http_response=None)

Bases: UnknownError

Backend service responded with an unexpected or malformed response.

UserDisabledError

exception firebase_admin.auth.UserDisabledError(message, cause=None, http_response=None)

Bases: InvalidArgumentError

An operation failed due to a user record being disabled.

default_message = 'The user record is disabled'

UserNotFoundError

exception firebase_admin.auth.UserNotFoundError(message, cause=None, http_response=None)

Bases: NotFoundError

No user record found for the specified identifier.

default_message = 'No user record found for the given identifier'

Classes

ActionCodeSettings

class firebase_admin.auth.ActionCodeSettings(url, handle_code_in_app=None, dynamic_link_domain=None, ios_bundle_id=None, android_package_name=None, android_install_app=None, android_minimum_version=None)

Bases: object

Contains required continue/state URL with optional Android and iOS settings. Used when invoking the email action link generation APIs.

Client

class firebase_admin.auth.Client(app, tenant_id=None)

Bases: object

Firebase Authentication client scoped to a specific tenant.

create_custom_token(uid, developer_claims=None)

Builds and signs a Firebase custom auth token.

Parameters:
  • uid – ID of the user for whom the token is created.

  • developer_claims – A dictionary of claims to be included in the token (optional).

Returns:

A token minted from the input parameters.

Return type:

bytes

Raises:
  • ValueError – If input parameters are invalid.

  • TokenSignError – If an error occurs while signing the token using the remote IAM service.

create_oidc_provider_config(provider_id, client_id, issuer, display_name=None, enabled=None, client_secret=None, id_token_response_type=None, code_response_type=None)

Creates a new OIDC provider config from the given parameters.

OIDC provider support requires Google Cloud’s Identity Platform (GCIP). To learn more about GCIP, including pricing and features, see https://cloud.google.com/identity-platform.

Parameters:
  • provider_id – Provider ID string. Must have the prefix oidc..

  • client_id – Client ID of the new config.

  • issuer – Issuer of the new config. Must be a valid URL.

  • display_name – The user-friendly display name to the current configuration (optional). This name is also used as the provider label in the Cloud Console.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional). A user cannot sign in using a disabled provider.

  • client_secret – A string which sets the client secret for the new provider. This is required for the code flow.

  • code_response_type – A boolean which sets whether to enable the code response flow for the new provider. By default, this is not enabled if no response type is specified. A client secret must be set for this response type. Having both the code and ID token response flows is currently not supported.

  • id_token_response_type – A boolean which sets whether to enable the ID token response flow for the new provider. By default, this is enabled if no response type is specified. Having both the code and ID token response flows is currently not supported.

Returns:

The newly created OIDC provider config instance.

Return type:

OIDCProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while creating the new OIDC provider config.

create_saml_provider_config(provider_id, idp_entity_id, sso_url, x509_certificates, rp_entity_id, callback_url, display_name=None, enabled=None)

Creates a new SAML provider config from the given parameters.

SAML provider support requires Google Cloud’s Identity Platform (GCIP). To learn more about GCIP, including pricing and features, see https://cloud.google.com/identity-platform.

Parameters:
  • provider_id – Provider ID string. Must have the prefix saml..

  • idp_entity_id – The SAML IdP entity identifier.

  • sso_url – The SAML IdP SSO URL. Must be a valid URL.

  • x509_certificates – The list of SAML IdP X.509 certificates issued by CA for this provider. Multiple certificates are accepted to prevent outages during IdP key rotation (for example ADFS rotates every 10 days). When the Auth server receives a SAML response, it will match the SAML response with the certificate on record. Otherwise the response is rejected. Developers are expected to manage the certificate updates as keys are rotated.

  • rp_entity_id – The SAML relying party (service provider) entity ID. This is defined by the developer but needs to be provided to the SAML IdP.

  • callback_url – Callback URL string. This is fixed and must always be the same as the OAuth redirect URL provisioned by Firebase Auth, unless a custom authDomain is used.

  • display_name – The user-friendly display name to the current configuration (optional). This name is also used as the provider label in the Cloud Console.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional). A user cannot sign in using a disabled provider.

Returns:

The newly created SAML provider config instance.

Return type:

SAMLProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while creating the new SAML provider config.

create_user(**kwargs)

Creates a new user account with the specified properties.

Parameters:

**kwargs – A series of keyword arguments (optional).

Keyword Arguments:
  • uid – User ID to assign to the newly created user (optional).

  • display_name – The user’s display name (optional).

  • email – The user’s primary email (optional).

  • email_verified – A boolean indicating whether or not the user’s primary email is verified (optional).

  • phone_number – The user’s primary phone number (optional).

  • photo_url – The user’s photo URL (optional).

  • password – The user’s raw, unhashed password. (optional).

  • disabled – A boolean indicating whether or not the user account is disabled (optional).

Returns:

A UserRecord instance for the newly created user.

Return type:

UserRecord

Raises:
  • ValueError – If the specified user properties are invalid.

  • FirebaseError – If an error occurs while creating the user account.

delete_oidc_provider_config(provider_id)

Deletes the OIDCProviderConfig with the given ID.

Parameters:

provider_id – Provider ID string.

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have oidc. prefix.

  • ConfigurationNotFoundError – If no OIDC provider is available with the given identifier.

  • FirebaseError – If an error occurs while deleting the OIDC provider.

delete_saml_provider_config(provider_id)

Deletes the SAMLProviderConfig with the given ID.

Parameters:

provider_id – Provider ID string.

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have saml. prefix.

  • ConfigurationNotFoundError – If no SAML provider is available with the given identifier.

  • FirebaseError – If an error occurs while deleting the SAML provider.

delete_user(uid)

Deletes the user identified by the specified user ID.

Parameters:

uid – A user ID string.

Raises:
  • ValueError – If the user ID is None, empty or malformed.

  • FirebaseError – If an error occurs while deleting the user account.

delete_users(uids)

Deletes the users specified by the given identifiers.

Deleting a non-existing user does not generate an error (the method is idempotent.) Non-existing users are considered to be successfully deleted and are therefore included in the DeleteUserResult.success_count value.

A maximum of 1000 identifiers may be supplied. If more than 1000 identifiers are supplied, this method raises a ValueError.

Parameters:

uids – A list of strings indicating the uids of the users to be deleted. Must have <= 1000 entries.

Returns:

The total number of successful/failed deletions, as well as the array of errors that correspond to the failed deletions.

Return type:

DeleteUsersResult

Raises:

ValueError – If any of the identifiers are invalid or if more than 1000 identifiers are specified.

Generates the out-of-band email action link for email verification flows for the specified email address.

Parameters:
  • email – The email of the user to be verified.

  • action_code_settingsActionCodeSettings instance (optional). Defines whether the link is to be handled by a mobile app and the additional state information to be passed in the deep link.

Returns:

The email verification link created by the API

Return type:

link

Raises:
  • ValueError – If the provided arguments are invalid

  • UserNotFoundError – If no user exists for the specified email address.

  • FirebaseError – If an error occurs while generating the link

Generates the out-of-band email action link for password reset flows for the specified email address.

Parameters:
  • email – The email of the user whose password is to be reset.

  • action_code_settingsActionCodeSettings instance (optional). Defines whether the link is to be handled by a mobile app and the additional state information to be passed in the deep link.

Returns:

The password reset link created by the API

Return type:

link

Raises:
  • ValueError – If the provided arguments are invalid

  • EmailNotFoundError – If no user exists for the specified email address.

  • FirebaseError – If an error occurs while generating the link

Generates the out-of-band email action link for email link sign-in flows, using the action code settings provided.

Parameters:
  • email – The email of the user signing in.

  • action_code_settingsActionCodeSettings instance. Defines whether the link is to be handled by a mobile app and the additional state information to be passed in the deep link.

Returns:

The email sign-in link created by the API

Return type:

link

Raises:
  • ValueError – If the provided arguments are invalid

  • FirebaseError – If an error occurs while generating the link

get_oidc_provider_config(provider_id)

Returns the OIDCProviderConfig with the given ID.

Parameters:

provider_id – Provider ID string.

Returns:

An OIDC provider config instance.

Return type:

SAMLProviderConfig

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have oidc. prefix.

  • ConfigurationNotFoundError – If no OIDC provider is available with the given identifier.

  • FirebaseError – If an error occurs while retrieving the OIDC provider.

get_saml_provider_config(provider_id)

Returns the SAMLProviderConfig with the given ID.

Parameters:

provider_id – Provider ID string.

Returns:

A SAML provider config instance.

Return type:

SAMLProviderConfig

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have saml. prefix.

  • ConfigurationNotFoundError – If no SAML provider is available with the given identifier.

  • FirebaseError – If an error occurs while retrieving the SAML provider.

get_user(uid)

Gets the user data corresponding to the specified user ID.

Parameters:

uid – A user ID string.

Returns:

A user record instance.

Return type:

UserRecord

Raises:
  • ValueError – If the user ID is None, empty or malformed.

  • UserNotFoundError – If the specified user ID does not exist.

  • FirebaseError – If an error occurs while retrieving the user.

get_user_by_email(email)

Gets the user data corresponding to the specified user email.

Parameters:

email – A user email address string.

Returns:

A user record instance.

Return type:

UserRecord

Raises:
  • ValueError – If the email is None, empty or malformed.

  • UserNotFoundError – If no user exists for the specified email address.

  • FirebaseError – If an error occurs while retrieving the user.

get_user_by_phone_number(phone_number)

Gets the user data corresponding to the specified phone number.

Parameters:

phone_number – A phone number string.

Returns:

A user record instance.

Return type:

UserRecord

Raises:
  • ValueError – If the phone number is None, empty or malformed.

  • UserNotFoundError – If no user exists for the specified phone number.

  • FirebaseError – If an error occurs while retrieving the user.

get_users(identifiers)

Gets the user data corresponding to the specified identifiers.

There are no ordering guarantees; in particular, the nth entry in the result list is not guaranteed to correspond to the nth entry in the input parameters list.

A maximum of 100 identifiers may be supplied. If more than 100 identifiers are supplied, this method raises a ValueError.

Parameters:

identifiers (list[Identifier]) – A list of Identifier instances used to indicate which user records should be returned. Must have <= 100 entries.

Returns:

A GetUsersResult instance corresponding to the specified identifiers.

Return type:

GetUsersResult

Raises:

ValueError – If any of the identifiers are invalid or if more than 100 identifiers are specified.

import_users(users, hash_alg=None)

Imports the specified list of users into Firebase Auth.

At most 1000 users can be imported at a time. This operation is optimized for bulk imports and ignores checks on identifier uniqueness, which could result in duplications. The hash_alg parameter must be specified when importing users with passwords. Refer to the UserImportHash class for supported hash algorithms.

Parameters:
  • users – A list of ImportUserRecord instances to import. Length of the list must not exceed 1000.

  • hash_alg – A UserImportHash object (optional). Required when importing users with passwords.

Returns:

An object summarizing the result of the import operation.

Return type:

UserImportResult

Raises:
  • ValueError – If the provided arguments are invalid.

  • FirebaseError – If an error occurs while importing users.

list_oidc_provider_configs(page_token=None, max_results=100)

Retrieves a page of OIDC provider configs from a Firebase project.

The page_token argument governs the starting point of the page. The max_results argument governs the maximum number of configs that may be included in the returned page. This function never returns None. If there are no OIDC configs in the Firebase project, this returns an empty page.

Parameters:
  • page_token – A non-empty page token string, which indicates the starting point of the page (optional). Defaults to None, which will retrieve the first page of users.

  • max_results – A positive integer indicating the maximum number of users to include in the returned page (optional). Defaults to 100, which is also the maximum number allowed.

Returns:

A page of OIDC provider config instances.

Return type:

ListProviderConfigsPage

Raises:
  • ValueError – If max_results or page_token are invalid.

  • FirebaseError – If an error occurs while retrieving the OIDC provider configs.

list_saml_provider_configs(page_token=None, max_results=100)

Retrieves a page of SAML provider configs from a Firebase project.

The page_token argument governs the starting point of the page. The max_results argument governs the maximum number of configs that may be included in the returned page. This function never returns None. If there are no SAML configs in the Firebase project, this returns an empty page.

Parameters:
  • page_token – A non-empty page token string, which indicates the starting point of the page (optional). Defaults to None, which will retrieve the first page of users.

  • max_results – A positive integer indicating the maximum number of users to include in the returned page (optional). Defaults to 100, which is also the maximum number allowed.

Returns:

A page of SAML provider config instances.

Return type:

ListProviderConfigsPage

Raises:
  • ValueError – If max_results or page_token are invalid.

  • FirebaseError – If an error occurs while retrieving the SAML provider configs.

list_users(page_token=None, max_results=1000)

Retrieves a page of user accounts from a Firebase project.

The page_token argument governs the starting point of the page. The max_results argument governs the maximum number of user accounts that may be included in the returned page. This function never returns None. If there are no user accounts in the Firebase project, this returns an empty page.

Parameters:
  • page_token – A non-empty page token string, which indicates the starting point of the page (optional). Defaults to None, which will retrieve the first page of users.

  • max_results – A positive integer indicating the maximum number of users to include in the returned page (optional). Defaults to 1000, which is also the maximum number allowed.

Returns:

A page of user accounts.

Return type:

ListUsersPage

Raises:
  • ValueError – If max_results or page_token are invalid.

  • FirebaseError – If an error occurs while retrieving the user accounts.

revoke_refresh_tokens(uid)

Revokes all refresh tokens for an existing user.

This method updates the user’s tokens_valid_after_timestamp to the current UTC in seconds since the epoch. It is important that the server on which this is called has its clock set correctly and synchronized.

While this revokes all sessions for a specified user and disables 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 verify_id_token(idToken, check_revoked=True).

Parameters:

uid – A user ID string.

Raises:
  • ValueError – If the user ID is None, empty or malformed.

  • FirebaseError – If an error occurs while revoking the refresh token.

set_custom_user_claims(uid, custom_claims)

Sets additional claims on an existing user account.

Custom claims set via this function can be used to define user roles and privilege levels. These claims propagate to all the devices where the user is already signed in (after token expiration or when token refresh is forced), and next time the user signs in. The claims can be accessed via the user’s ID token JWT. If a reserved OIDC claim is specified (sub, iat, iss, etc), an error is thrown. Claims payload must also not be larger then 1000 characters when serialized into a JSON string.

Parameters:
  • uid – A user ID string.

  • custom_claims – A dictionary or a JSON string of custom claims. Pass None to unset any claims set previously.

Raises:
  • ValueError – If the specified user ID or the custom claims are invalid.

  • FirebaseError – If an error occurs while updating the user account.

update_oidc_provider_config(provider_id, client_id=None, issuer=None, display_name=None, enabled=None, client_secret=None, id_token_response_type=None, code_response_type=None)

Updates an existing OIDC provider config with the given parameters.

Parameters:
  • provider_id – Provider ID string. Must have the prefix oidc..

  • client_id – Client ID of the new config (optional).

  • issuer – Issuer of the new config (optional). Must be a valid URL.

  • display_name – The user-friendly display name to the current configuration (optional). Pass auth.DELETE_ATTRIBUTE to delete the current display name.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional).

  • client_secret – A string which sets the client secret for the new provider. This is required for the code flow.

  • code_response_type – A boolean which sets whether to enable the code response flow for the new provider. By default, this is not enabled if no response type is specified. A client secret must be set for this response type. Having both the code and ID token response flows is currently not supported.

  • id_token_response_type – A boolean which sets whether to enable the ID token response flow for the new provider. By default, this is enabled if no response type is specified. Having both the code and ID token response flows is currently not supported.

Returns:

The updated OIDC provider config instance.

Return type:

OIDCProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while updating the OIDC provider config.

update_saml_provider_config(provider_id, idp_entity_id=None, sso_url=None, x509_certificates=None, rp_entity_id=None, callback_url=None, display_name=None, enabled=None)

Updates an existing SAML provider config with the given parameters.

Parameters:
  • provider_id – Provider ID string. Must have the prefix saml..

  • idp_entity_id – The SAML IdP entity identifier (optional).

  • sso_url – The SAML IdP SSO URL. Must be a valid URL (optional).

  • x509_certificates – The list of SAML IdP X.509 certificates issued by CA for this provider (optional).

  • rp_entity_id – The SAML relying party entity ID (optional).

  • callback_url – Callback URL string (optional).

  • display_name – The user-friendly display name of the current configuration (optional). Pass auth.DELETE_ATTRIBUTE to delete the current display name.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional).

Returns:

The updated SAML provider config instance.

Return type:

SAMLProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while updating the SAML provider config.

update_user(uid, **kwargs)

Updates an existing user account with the specified properties.

Parameters:
  • uid – A user ID string.

  • **kwargs – A series of keyword arguments (optional).

Keyword Arguments:
  • display_name – The user’s display name (optional). Can be removed by explicitly passing auth.DELETE_ATTRIBUTE.

  • email – The user’s primary email (optional).

  • email_verified – A boolean indicating whether or not the user’s primary email is verified (optional).

  • phone_number – The user’s primary phone number (optional). Can be removed by explicitly passing auth.DELETE_ATTRIBUTE.

  • photo_url – The user’s photo URL (optional). Can be removed by explicitly passing auth.DELETE_ATTRIBUTE.

  • password – The user’s raw, unhashed password. (optional).

  • disabled – A boolean indicating whether or not the user account is disabled (optional).

  • custom_claims – A dictionary or a JSON string contining the custom claims to be set on the user account (optional). To remove all custom claims, pass auth.DELETE_ATTRIBUTE.

  • valid_since – An integer signifying the seconds since the epoch (optional). This field is set by revoke_refresh_tokens and it is discouraged to set this field directly.

  • providers_to_delete – The list of provider IDs to unlink, eg: ‘google.com’, ‘password’, etc.

Returns:

An updated UserRecord instance for the user.

Return type:

UserRecord

Raises:
  • ValueError – If the specified user ID or properties are invalid.

  • FirebaseError – If an error occurs while updating the user account.

verify_id_token(id_token, check_revoked=False, clock_skew_seconds=0)

Verifies the signature and data for the provided JWT.

Accepts a signed token string, verifies that it is current, was issued to this project, and that it was correctly signed by Google.

Parameters:
  • id_token – A string of the encoded JWT.

  • check_revoked – Boolean, If true, checks whether the token has been revoked or the user disabled (optional).

  • clock_skew_seconds – The number of seconds to tolerate when checking the token. Must be between 0-60. Defaults to 0.

Returns:

A dictionary of key-value pairs parsed from the decoded JWT.

Return type:

dict

Raises:
  • ValueError – If id_token is a not a string or is empty.

  • InvalidIdTokenError – If id_token is not a valid Firebase ID token.

  • ExpiredIdTokenError – If the specified ID token has expired.

  • RevokedIdTokenError – If check_revoked is True and the ID token has been revoked.

  • TenantIdMismatchError – If id_token belongs to a tenant that is different than this Client instance.

  • CertificateFetchError – If an error occurs while fetching the public key certificates required to verify the ID token.

  • UserDisabledError – If check_revoked is True and the corresponding user record is disabled.

property tenant_id

Tenant ID associated with this client.

DeleteUsersResult

class firebase_admin.auth.DeleteUsersResult(result, total)

Bases: object

Represents the result of the auth.delete_users() API.

property errors

A list of auth.ErrorInfo instances describing the errors that were encountered during the deletion. Length of this list is equal to failure_count.

property failure_count

Returns the number of users that failed to be deleted (possibly zero).

property success_count

Returns the number of users that were deleted successfully (possibly zero).

Users that did not exist prior to calling delete_users() are considered to be successfully deleted.

EmailIdentifier

class firebase_admin.auth.EmailIdentifier(email)

Bases: UserIdentifier

Used for looking up an account by email.

See auth.get_user().

property email

ErrorInfo

class firebase_admin.auth.ErrorInfo(error)

Bases: object

Represents an error encountered while performing a batch operation such as importing users or deleting multiple user accounts.

property index
property reason

ExportedUserRecord

class firebase_admin.auth.ExportedUserRecord(data)

Bases: UserRecord

Contains metadata associated with a user including password hash and salt.

property password_hash

The user’s password hash as a base64-encoded string.

If the Firebase Auth hashing algorithm (SCRYPT) was used to create the user account, this is the base64-encoded password hash of the user. If a different hashing algorithm was used to create this user, as is typical when migrating from another Auth system, this is an empty string. If no password is set, or if the service account doesn’t have permission to read the password, then this is None.

property password_salt

The user’s password salt as a base64-encoded string.

If the Firebase Auth hashing algorithm (SCRYPT) was used to create the user account, this is the base64-encoded password salt of the user. If a different hashing algorithm was used to create this user, as is typical when migrating from another Auth system, this is an empty string. If no password is set, or if the service account doesn’t have permission to read the password, then this is None.

GetUsersResult

class firebase_admin.auth.GetUsersResult(users, not_found)

Bases: object

Represents the result of the auth.get_users() API.

property not_found

Set of UserIdentifier instances that were requested, but not found.

property users

Set of UserRecord instances, corresponding to the set of users that were requested. Only users that were found are listed here. The result set is unordered.

ImportUserRecord

class firebase_admin.auth.ImportUserRecord(uid, email=None, email_verified=None, display_name=None, phone_number=None, photo_url=None, disabled=None, user_metadata=None, provider_data=None, custom_claims=None, password_hash=None, password_salt=None)

Bases: object

Represents a user account to be imported to Firebase Auth.

Must specify the uid field at a minimum. A sequence of ImportUserRecord objects can be passed to the auth.import_users() function, in order to import those users into Firebase Auth in bulk. If the password_hash is set on a user, a hash configuration must be specified when calling import_users().

Parameters:
  • uid – User’s unique ID. Must be a non-empty string not longer than 128 characters.

  • email – User’s email address (optional).

  • email_verified – A boolean indicating whether the user’s email has been verified (optional).

  • display_name – User’s display name (optional).

  • phone_number – User’s phone number (optional).

  • photo_url – User’s photo URL (optional).

  • disabled – A boolean indicating whether this user account has been disabled (optional).

  • user_metadata – An auth.UserMetadata instance with additional user metadata (optional).

  • provider_data – A list of auth.UserProvider instances (optional).

  • custom_claims – A dict of custom claims to be set on the user account (optional).

  • password_hash – User’s password hash as a bytes sequence (optional).

  • password_salt – User’s password salt as a bytes sequence (optional).

Raises:

ValueError – If provided arguments are invalid.

to_dict()

Returns a dict representation of the user. For internal use only.

property custom_claims
property display_name
property email
property password_hash
property password_salt
property phone_number
property photo_url
property provider_data
property uid
property user_metadata

ListProviderConfigsPage

class firebase_admin.auth.ListProviderConfigsPage(download, page_token, max_results)

Bases: object

Represents a page of AuthProviderConfig instances retrieved from a Firebase project.

Provides methods for traversing the provider configs included in this page, as well as retrieving subsequent pages. The iterator returned by iterate_all() can be used to iterate through all provider configs in the Firebase project starting from this page.

get_next_page()

Retrieves the next page of provider configs, if available.

Returns:

Next page of provider configs, or None if this is the last page.

Return type:

ListProviderConfigsPage

iterate_all()

Retrieves an iterator for provider configs.

Returned iterator will iterate through all the provider configs in the Firebase project starting from this page. The iterator will never buffer more than one page of configs in memory at a time.

Returns:

An iterator of AuthProviderConfig instances.

Return type:

iterator

property has_next_page

A boolean indicating whether more pages are available.

property next_page_token

Page token string for the next page (empty string indicates no more pages).

property provider_configs

A list of AuthProviderConfig instances available in this page.

ListUsersPage

class firebase_admin.auth.ListUsersPage(download, page_token, max_results)

Bases: object

Represents a page of user records exported from a Firebase project.

Provides methods for traversing the user accounts included in this page, as well as retrieving subsequent pages of users. The iterator returned by iterate_all() can be used to iterate through all users in the Firebase project starting from this page.

get_next_page()

Retrieves the next page of user accounts, if available.

Returns:

Next page of users, or None if this is the last page.

Return type:

ListUsersPage

iterate_all()

Retrieves an iterator for user accounts.

Returned iterator will iterate through all the user accounts in the Firebase project starting from this page. The iterator will never buffer more than one page of users in memory at a time.

Returns:

An iterator of ExportedUserRecord instances.

Return type:

iterator

property has_next_page

A boolean indicating whether more pages are available.

property next_page_token

Page token string for the next page (empty string indicates no more pages).

property users

A list of ExportedUserRecord instances available in this page.

OIDCProviderConfig

class firebase_admin.auth.OIDCProviderConfig(data)

Bases: ProviderConfig

Represents the OIDC auth provider configuration.

See https://openid.net/specs/openid-connect-core-1_0-final.html.

property client_id
property client_secret
property code_response_type
property id_token_response_type
property issuer

PhoneIdentifier

class firebase_admin.auth.PhoneIdentifier(phone_number)

Bases: UserIdentifier

Used for looking up an account by phone number.

See auth.get_user().

property phone_number

ProviderConfig

class firebase_admin.auth.ProviderConfig(data)

Bases: object

Parent type for all authentication provider config types.

property display_name
property enabled
property provider_id

ProviderIdentifier

class firebase_admin.auth.ProviderIdentifier(provider_id, provider_uid)

Bases: UserIdentifier

Used for looking up an account by provider.

See auth.get_user().

property provider_id
property provider_uid

SAMLProviderConfig

class firebase_admin.auth.SAMLProviderConfig(data)

Bases: ProviderConfig

Represents he SAML auth provider configuration.

See http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html.

property callback_url
property idp_entity_id
property rp_entity_id
property sso_url
property x509_certificates

UidIdentifier

class firebase_admin.auth.UidIdentifier(uid)

Bases: UserIdentifier

Used for looking up an account by uid.

See auth.get_user().

property uid

UserIdentifier

class firebase_admin.auth.UserIdentifier

Bases: object

Identifies a user to be looked up.

UserImportHash

class firebase_admin.auth.UserImportHash(name, data=None)

Bases: object

Represents a hash algorithm used to hash user passwords.

An instance of this class must be specified when importing users with passwords via the auth.import_users() API. Use one of the provided class methods to obtain new instances when required. Refer to documentation for more details.

classmethod bcrypt()

Creates a new Bcrypt algorithm instance.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod hmac_md5(key)

Creates a new HMAC MD5 algorithm instance.

Parameters:

key – Signer key as a byte sequence.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod hmac_sha1(key)

Creates a new HMAC SHA1 algorithm instance.

Parameters:

key – Signer key as a byte sequence.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod hmac_sha256(key)

Creates a new HMAC SHA256 algorithm instance.

Parameters:

key – Signer key as a byte sequence.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod hmac_sha512(key)

Creates a new HMAC SHA512 algorithm instance.

Parameters:

key – Signer key as a byte sequence.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod md5(rounds)

Creates a new MD5 algorithm instance.

Parameters:

rounds – Number of rounds. Must be an integer between 0 and 8192.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod pbkdf2_sha256(rounds)

Creates a new PBKDF2 SHA256 algorithm instance.

Parameters:

rounds – Number of rounds. Must be an integer between 0 and 120000.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod pbkdf_sha1(rounds)

Creates a new PBKDF SHA1 algorithm instance.

Parameters:

rounds – Number of rounds. Must be an integer between 0 and 120000.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod scrypt(key, rounds, memory_cost, salt_separator=None)

Creates a new Scrypt algorithm instance.

This is the modified Scrypt algorithm used by Firebase Auth. See standard_scrypt() function for the standard Scrypt algorith,

Parameters:
  • key – Signer key as a byte sequence.

  • rounds – Number of rounds. Must be an integer between 1 and 8.

  • memory_cost – Memory cost as an integer between 1 and 14.

  • salt_separator – Salt separator as a byte sequence (optional).

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod sha1(rounds)

Creates a new SHA1 algorithm instance.

Parameters:

rounds – Number of rounds. Must be an integer between 1 and 8192.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod sha256(rounds)

Creates a new SHA256 algorithm instance.

Parameters:

rounds – Number of rounds. Must be an integer between 1 and 8192.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod sha512(rounds)

Creates a new SHA512 algorithm instance.

Parameters:

rounds – Number of rounds. Must be an integer between 1 and 8192.

Returns:

A new UserImportHash.

Return type:

UserImportHash

classmethod standard_scrypt(memory_cost, parallelization, block_size, derived_key_length)

Creates a new standard Scrypt algorithm instance.

Parameters:
  • memory_cost – CPU Memory cost as a non-negative integer.

  • parallelization – Parallelization as a non-negative integer.

  • block_size – Block size as a non-negative integer.

  • derived_key_length – Derived key length as a non-negative integer.

Returns:

A new UserImportHash.

Return type:

UserImportHash

to_dict()

UserImportResult

class firebase_admin.auth.UserImportResult(result, total)

Bases: object

Represents the result of a bulk user import operation.

See auth.import_users() API for more details.

property errors

Returns a list of auth.ErrorInfo instances describing the errors encountered.

property failure_count

Returns the number of users that failed to be imported.

property success_count

Returns the number of users successfully imported.

UserInfo

class firebase_admin.auth.UserInfo

Bases: object

A collection of standard profile information for a user.

Used to expose profile information returned by an identity provider.

property display_name

Returns the display name of this user.

property email

Returns the email address associated with this user.

property phone_number

Returns the phone number associated with this user.

property photo_url

Returns the photo URL of this user.

property provider_id

Returns the ID of the identity provider.

This can be a short domain name (e.g. google.com), or the identity of an OpenID identity provider.

property uid

Returns the user ID of this user.

UserMetadata

class firebase_admin.auth.UserMetadata(creation_timestamp=None, last_sign_in_timestamp=None, last_refresh_timestamp=None)

Bases: object

Contains additional metadata associated with a user account.

property creation_timestamp

Creation timestamp in milliseconds since the epoch.

Returns:

The user creation timestamp in milliseconds since the epoch.

Return type:

integer

property last_refresh_timestamp

The time at which the user was last active (ID token refreshed).

Returns:

Milliseconds since epoch timestamp, or None if the user was never active.

Return type:

integer

property last_sign_in_timestamp

Last sign in timestamp in milliseconds since the epoch.

Returns:

The last sign in timestamp in milliseconds since the epoch.

Return type:

integer

UserProvider

class firebase_admin.auth.UserProvider(uid, provider_id, email=None, display_name=None, photo_url=None)

Bases: object

Represents a user identity provider that can be associated with a Firebase user.

One or more providers can be specified in an ImportUserRecord when importing users via auth.import_users().

Parameters:
  • uid – User’s unique ID assigned by the identity provider.

  • provider_id – ID of the identity provider. This can be a short domain name or the identifier of an OpenID identity provider.

  • email – User’s email address (optional).

  • display_name – User’s display name (optional).

  • photo_url – User’s photo URL (optional).

to_dict()
property display_name
property email
property photo_url
property provider_id
property uid

UserRecord

class firebase_admin.auth.UserRecord(data)

Bases: UserInfo

Contains metadata associated with a Firebase user account.

property custom_claims

Returns any custom claims set on this user account.

Returns:

A dictionary of claims or None.

Return type:

dict

property disabled

Returns whether this user account is disabled.

Returns:

True if the user account is disabled, and False otherwise.

Return type:

bool

property display_name

Returns the display name of this user.

Returns:

A display name string or None.

Return type:

string

property email

Returns the email address associated with this user.

Returns:

An email address string or None.

Return type:

string

property email_verified

Returns whether the email address of this user has been verified.

Returns:

True if the email has been verified, and False otherwise.

Return type:

bool

property phone_number

Returns the phone number associated with this user.

Returns:

A phone number string or None.

Return type:

string

property photo_url

Returns the photo URL of this user.

Returns:

A URL string or None.

Return type:

string

property provider_data

Returns a list of UserInfo instances.

Each object represents an identity from an identity provider that is linked to this user.

Returns:

A list of UserInfo objects, which may be empty.

Return type:

list

property provider_id

Returns the provider ID of this user.

Returns:

A constant provider ID value.

Return type:

string

property tenant_id

Returns the tenant ID of this user.

Returns:

A tenant ID string or None.

Return type:

string

property tokens_valid_after_timestamp

Returns the time, in milliseconds since the epoch, before which tokens are invalid.

Note: this is truncated to 1 second accuracy.

Returns:

Timestamp in milliseconds since the epoch, truncated to the second. All tokens issued before that time are considered revoked.

Return type:

int

property uid

Returns the user ID of this user.

Returns:

A user ID string. This value is never None or empty.

Return type:

string

property user_metadata

Returns additional metadata associated with this user.

Returns:

A UserMetadata instance. Does not return None.

Return type:

UserMetadata

Functions

create_custom_token

firebase_admin.auth.create_custom_token(uid, developer_claims=None, app=None)

Builds and signs a Firebase custom auth token.

Parameters:
  • uid – ID of the user for whom the token is created.

  • developer_claims – A dictionary of claims to be included in the token (optional).

  • app – An App instance (optional).

Returns:

A token minted from the input parameters.

Return type:

bytes

Raises:
  • ValueError – If input parameters are invalid.

  • TokenSignError – If an error occurs while signing the token using the remote IAM service.

create_oidc_provider_config

firebase_admin.auth.create_oidc_provider_config(provider_id, client_id, issuer, display_name=None, enabled=None, client_secret=None, id_token_response_type=None, code_response_type=None, app=None)

Creates a new OIDC provider config from the given parameters.

OIDC provider support requires Google Cloud’s Identity Platform (GCIP). To learn more about GCIP, including pricing and features, see https://cloud.google.com/identity-platform.

Parameters:
  • provider_id – Provider ID string. Must have the prefix oidc..

  • client_id – Client ID of the new config.

  • issuer – Issuer of the new config. Must be a valid URL.

  • display_name – The user-friendly display name to the current configuration (optional). This name is also used as the provider label in the Cloud Console.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional). A user cannot sign in using a disabled provider.

  • app – An App instance (optional).

  • client_secret – A string which sets the client secret for the new provider. This is required for the code flow.

  • code_response_type – A boolean which sets whether to enable the code response flow for the new provider. By default, this is not enabled if no response type is specified. A client secret must be set for this response type. Having both the code and ID token response flows is currently not supported.

  • id_token_response_type – A boolean which sets whether to enable the ID token response flow for the new provider. By default, this is enabled if no response type is specified. Having both the code and ID token response flows is currently not supported.

Returns:

The newly created OIDC provider config instance.

Return type:

OIDCProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while creating the new OIDC provider config.

create_saml_provider_config

firebase_admin.auth.create_saml_provider_config(provider_id, idp_entity_id, sso_url, x509_certificates, rp_entity_id, callback_url, display_name=None, enabled=None, app=None)

Creates a new SAML provider config from the given parameters.

SAML provider support requires Google Cloud’s Identity Platform (GCIP). To learn more about GCIP, including pricing and features, see https://cloud.google.com/identity-platform.

Parameters:
  • provider_id – Provider ID string. Must have the prefix saml..

  • idp_entity_id – The SAML IdP entity identifier.

  • sso_url – The SAML IdP SSO URL. Must be a valid URL.

  • x509_certificates – The list of SAML IdP X.509 certificates issued by CA for this provider. Multiple certificates are accepted to prevent outages during IdP key rotation (for example ADFS rotates every 10 days). When the Auth server receives a SAML response, it will match the SAML response with the certificate on record. Otherwise the response is rejected. Developers are expected to manage the certificate updates as keys are rotated.

  • rp_entity_id – The SAML relying party (service provider) entity ID. This is defined by the developer but needs to be provided to the SAML IdP.

  • callback_url – Callback URL string. This is fixed and must always be the same as the OAuth redirect URL provisioned by Firebase Auth, unless a custom authDomain is used.

  • display_name – The user-friendly display name to the current configuration (optional). This name is also used as the provider label in the Cloud Console.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional). A user cannot sign in using a disabled provider.

  • app – An App instance (optional).

Returns:

The newly created SAML provider config instance.

Return type:

SAMLProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while creating the new SAML provider config.

firebase_admin.auth.create_session_cookie(id_token, expires_in, app=None)

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:
  • id_token – The Firebase ID token to exchange for a session cookie.

  • expires_in – Duration until the cookie is expired. This can be specified as a numeric seconds value or a datetime.timedelta instance.

  • app – An App instance (optional).

Returns:

A session cookie generated from the input parameters.

Return type:

bytes

Raises:
  • ValueError – If input parameters are invalid.

  • FirebaseError – If an error occurs while creating the cookie.

create_user

firebase_admin.auth.create_user(**kwargs)

Creates a new user account with the specified properties.

Parameters:

**kwargs – A series of keyword arguments (optional).

Keyword Arguments:
  • uid – User ID to assign to the newly created user (optional).

  • display_name – The user’s display name (optional).

  • email – The user’s primary email (optional).

  • email_verified – A boolean indicating whether or not the user’s primary email is verified (optional).

  • phone_number – The user’s primary phone number (optional).

  • photo_url – The user’s photo URL (optional).

  • password – The user’s raw, unhashed password. (optional).

  • disabled – A boolean indicating whether or not the user account is disabled (optional).

  • app – An App instance (optional).

Returns:

A user record instance for the newly created user.

Return type:

UserRecord

Raises:
  • ValueError – If the specified user properties are invalid.

  • FirebaseError – If an error occurs while creating the user account.

delete_oidc_provider_config

firebase_admin.auth.delete_oidc_provider_config(provider_id, app=None)

Deletes the OIDCProviderConfig with the given ID.

Parameters:
  • provider_id – Provider ID string.

  • app – An App instance (optional).

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have oidc. prefix.

  • ConfigurationNotFoundError – If no OIDC provider is available with the given identifier.

  • FirebaseError – If an error occurs while deleting the OIDC provider.

delete_saml_provider_config

firebase_admin.auth.delete_saml_provider_config(provider_id, app=None)

Deletes the SAMLProviderConfig with the given ID.

Parameters:
  • provider_id – Provider ID string.

  • app – An App instance (optional).

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have saml. prefix.

  • ConfigurationNotFoundError – If no SAML provider is available with the given identifier.

  • FirebaseError – If an error occurs while deleting the SAML provider.

delete_user

firebase_admin.auth.delete_user(uid, app=None)

Deletes the user identified by the specified user ID.

Parameters:
  • uid – A user ID string.

  • app – An App instance (optional).

Raises:
  • ValueError – If the user ID is None, empty or malformed.

  • FirebaseError – If an error occurs while deleting the user account.

delete_users

firebase_admin.auth.delete_users(uids, app=None)

Deletes the users specified by the given identifiers.

Deleting a non-existing user does not generate an error (the method is idempotent.) Non-existing users are considered to be successfully deleted and are therefore included in the DeleteUserResult.success_count value.

A maximum of 1000 identifiers may be supplied. If more than 1000 identifiers are supplied, this method raises a ValueError.

Parameters:
  • uids – A list of strings indicating the uids of the users to be deleted. Must have <= 1000 entries.

  • app – An App instance (optional).

Returns:

The total number of successful/failed deletions, as well as the array of errors that correspond to the failed deletions.

Return type:

DeleteUsersResult

Raises:

ValueError – If any of the identifiers are invalid or if more than 1000 identifiers are specified.

firebase_admin.auth.generate_email_verification_link(email, action_code_settings=None, app=None)

Generates the out-of-band email action link for email verification flows for the specified email address.

Parameters:
  • email – The email of the user to be verified.

  • action_code_settingsActionCodeSettings instance (optional). Defines whether the link is to be handled by a mobile app and the additional state information to be passed in the deep link.

  • app – An App instance (optional).

Returns:

The email verification link created by the API

Return type:

link

Raises:
  • ValueError – If the provided arguments are invalid

  • FirebaseError – If an error occurs while generating the link

firebase_admin.auth.generate_password_reset_link(email, action_code_settings=None, app=None)

Generates the out-of-band email action link for password reset flows for the specified email address.

Parameters:
  • email – The email of the user whose password is to be reset.

  • action_code_settingsActionCodeSettings instance (optional). Defines whether the link is to be handled by a mobile app and the additional state information to be passed in the deep link.

  • app – An App instance (optional).

Returns:

The password reset link created by the API

Return type:

link

Raises:
  • ValueError – If the provided arguments are invalid

  • FirebaseError – If an error occurs while generating the link

firebase_admin.auth.generate_sign_in_with_email_link(email, action_code_settings, app=None)

Generates the out-of-band email action link for email link sign-in flows, using the action code settings provided.

Parameters:
  • email – The email of the user signing in.

  • action_code_settingsActionCodeSettings instance. Defines whether the link is to be handled by a mobile app and the additional state information to be passed in the deep link.

  • app – An App instance (optional).

Returns:

The email sign-in link created by the API

Return type:

link

Raises:
  • ValueError – If the provided arguments are invalid

  • FirebaseError – If an error occurs while generating the link

get_oidc_provider_config

firebase_admin.auth.get_oidc_provider_config(provider_id, app=None)

Returns the OIDCProviderConfig with the given ID.

Parameters:
  • provider_id – Provider ID string.

  • app – An App instance (optional).

Returns:

An OIDC provider config instance.

Return type:

OIDCProviderConfig

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have oidc. prefix.

  • ConfigurationNotFoundError – If no OIDC provider is available with the given identifier.

  • FirebaseError – If an error occurs while retrieving the OIDC provider.

get_saml_provider_config

firebase_admin.auth.get_saml_provider_config(provider_id, app=None)

Returns the SAMLProviderConfig with the given ID.

Parameters:
  • provider_id – Provider ID string.

  • app – An App instance (optional).

Returns:

A SAML provider config instance.

Return type:

SAMLProviderConfig

Raises:
  • ValueError – If the provider ID is invalid, empty or does not have saml. prefix.

  • ConfigurationNotFoundError – If no SAML provider is available with the given identifier.

  • FirebaseError – If an error occurs while retrieving the SAML provider.

get_user

firebase_admin.auth.get_user(uid, app=None)

Gets the user data corresponding to the specified user ID.

Parameters:
  • uid – A user ID string.

  • app – An App instance (optional).

Returns:

A user record instance.

Return type:

UserRecord

Raises:
  • ValueError – If the user ID is None, empty or malformed.

  • UserNotFoundError – If the specified user ID does not exist.

  • FirebaseError – If an error occurs while retrieving the user.

get_user_by_email

firebase_admin.auth.get_user_by_email(email, app=None)

Gets the user data corresponding to the specified user email.

Parameters:
  • email – A user email address string.

  • app – An App instance (optional).

Returns:

A user record instance.

Return type:

UserRecord

Raises:
  • ValueError – If the email is None, empty or malformed.

  • UserNotFoundError – If no user exists by the specified email address.

  • FirebaseError – If an error occurs while retrieving the user.

get_user_by_phone_number

firebase_admin.auth.get_user_by_phone_number(phone_number, app=None)

Gets the user data corresponding to the specified phone number.

Parameters:
  • phone_number – A phone number string.

  • app – An App instance (optional).

Returns:

A user record instance.

Return type:

UserRecord

Raises:
  • ValueError – If the phone number is None, empty or malformed.

  • UserNotFoundError – If no user exists by the specified phone number.

  • FirebaseError – If an error occurs while retrieving the user.

get_users

firebase_admin.auth.get_users(identifiers, app=None)

Gets the user data corresponding to the specified identifiers.

There are no ordering guarantees; in particular, the nth entry in the result list is not guaranteed to correspond to the nth entry in the input parameters list.

A maximum of 100 identifiers may be supplied. If more than 100 identifiers are supplied, this method raises a ValueError.

Parameters:
  • identifiers (list[UserIdentifier]) – A list of UserIdentifier instances used to indicate which user records should be returned. Must have <= 100 entries.

  • app – An App instance (optional).

Returns:

A GetUsersResult instance corresponding to the specified identifiers.

Return type:

GetUsersResult

Raises:

ValueError – If any of the identifiers are invalid or if more than 100 identifiers are specified.

import_users

firebase_admin.auth.import_users(users, hash_alg=None, app=None)

Imports the specified list of users into Firebase Auth.

At most 1000 users can be imported at a time. This operation is optimized for bulk imports and will ignore checks on identifier uniqueness which could result in duplications. The hash_alg parameter must be specified when importing users with passwords. Refer to the UserImportHash class for supported hash algorithms.

Parameters:
  • users – A list of ImportUserRecord instances to import. Length of the list must not exceed 1000.

  • hash_alg – A UserImportHash object (optional). Required when importing users with passwords.

  • app – An App instance (optional).

Returns:

An object summarizing the result of the import operation.

Return type:

UserImportResult

Raises:
  • ValueError – If the provided arguments are invalid.

  • FirebaseError – If an error occurs while importing users.

list_saml_provider_configs

firebase_admin.auth.list_saml_provider_configs(page_token=None, max_results=100, app=None)

Retrieves a page of SAML provider configs from a Firebase project.

The page_token argument governs the starting point of the page. The max_results argument governs the maximum number of configs that may be included in the returned page. This function never returns None. If there are no SAML configs in the Firebase project, this returns an empty page.

Parameters:
  • page_token – A non-empty page token string, which indicates the starting point of the page (optional). Defaults to None, which will retrieve the first page of users.

  • max_results – A positive integer indicating the maximum number of users to include in the returned page (optional). Defaults to 100, which is also the maximum number allowed.

  • app – An App instance (optional).

Returns:

A page of SAML provider config instances.

Return type:

ListProviderConfigsPage

Raises:
  • ValueError – If max_results or page_token are invalid.

  • FirebaseError – If an error occurs while retrieving the SAML provider configs.

list_users

firebase_admin.auth.list_users(page_token=None, max_results=1000, app=None)

Retrieves a page of user accounts from a Firebase project.

The page_token argument governs the starting point of the page. The max_results argument governs the maximum number of user accounts that may be included in the returned page. This function never returns None. If there are no user accounts in the Firebase project, this returns an empty page.

Parameters:
  • page_token – A non-empty page token string, which indicates the starting point of the page (optional). Defaults to None, which will retrieve the first page of users.

  • max_results – A positive integer indicating the maximum number of users to include in the returned page (optional). Defaults to 1000, which is also the maximum number allowed.

  • app – An App instance (optional).

Returns:

A page of user accounts.

Return type:

ListUsersPage

Raises:
  • ValueError – If max_results or page_token are invalid.

  • FirebaseError – If an error occurs while retrieving the user accounts.

revoke_refresh_tokens

firebase_admin.auth.revoke_refresh_tokens(uid, app=None)

Revokes all refresh tokens for an existing user.

This function updates the user’s tokens_valid_after_timestamp to the current UTC in seconds since the epoch. It is important that the server on which this is called has its clock set correctly and synchronized.

While this revokes all sessions for a specified user and disables 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 verify_id_token(idToken, check_revoked=True).

Parameters:
  • uid – A user ID string.

  • app – An App instance (optional).

Raises:
  • ValueError – If the user ID is None, empty or malformed.

  • FirebaseError – If an error occurs while revoking the refresh token.

set_custom_user_claims

firebase_admin.auth.set_custom_user_claims(uid, custom_claims, app=None)

Sets additional claims on an existing user account.

Custom claims set via this function can be used to define user roles and privilege levels. These claims propagate to all the devices where the user is already signed in (after token expiration or when token refresh is forced), and next time the user signs in. The claims can be accessed via the user’s ID token JWT. If a reserved OIDC claim is specified (sub, iat, iss, etc), an error is thrown. Claims payload must also not be larger then 1000 characters when serialized into a JSON string.

Parameters:
  • uid – A user ID string.

  • custom_claims – A dictionary or a JSON string of custom claims. Pass None to unset any claims set previously.

  • app – An App instance (optional).

Raises:
  • ValueError – If the specified user ID or the custom claims are invalid.

  • FirebaseError – If an error occurs while updating the user account.

update_oidc_provider_config

firebase_admin.auth.update_oidc_provider_config(provider_id, client_id=None, issuer=None, display_name=None, enabled=None, client_secret=None, id_token_response_type=None, code_response_type=None, app=None)

Updates an existing OIDC provider config with the given parameters.

Parameters:
  • provider_id – Provider ID string. Must have the prefix oidc..

  • client_id – Client ID of the new config (optional).

  • issuer – Issuer of the new config (optional). Must be a valid URL.

  • display_name – The user-friendly display name of the current configuration (optional). Pass auth.DELETE_ATTRIBUTE to delete the current display name.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional).

  • app – An App instance (optional).

  • client_secret – A string which sets the client secret for the new provider. This is required for the code flow.

  • code_response_type – A boolean which sets whether to enable the code response flow for the new provider. By default, this is not enabled if no response type is specified. A client secret must be set for this response type. Having both the code and ID token response flows is currently not supported.

  • id_token_response_type – A boolean which sets whether to enable the ID token response flow for the new provider. By default, this is enabled if no response type is specified. Having both the code and ID token response flows is currently not supported.

Returns:

The updated OIDC provider config instance.

Return type:

OIDCProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while updating the OIDC provider config.

update_saml_provider_config

firebase_admin.auth.update_saml_provider_config(provider_id, idp_entity_id=None, sso_url=None, x509_certificates=None, rp_entity_id=None, callback_url=None, display_name=None, enabled=None, app=None)

Updates an existing SAML provider config with the given parameters.

Parameters:
  • provider_id – Provider ID string. Must have the prefix saml..

  • idp_entity_id – The SAML IdP entity identifier (optional).

  • sso_url – The SAML IdP SSO URL. Must be a valid URL (optional).

  • x509_certificates – The list of SAML IdP X.509 certificates issued by CA for this provider (optional).

  • rp_entity_id – The SAML relying party entity ID (optional).

  • callback_url – Callback URL string (optional).

  • display_name – The user-friendly display name of the current configuration (optional). Pass auth.DELETE_ATTRIBUTE to delete the current display name.

  • enabled – A boolean indicating whether the provider configuration is enabled or disabled (optional).

  • app – An App instance (optional).

Returns:

The updated SAML provider config instance.

Return type:

SAMLProviderConfig

Raises:
  • ValueError – If any of the specified input parameters are invalid.

  • FirebaseError – If an error occurs while updating the SAML provider config.

update_user

firebase_admin.auth.update_user(uid, **kwargs)

Updates an existing user account with the specified properties.

Parameters:
  • uid – A user ID string.

  • **kwargs – A series of keyword arguments (optional).

Keyword Arguments:
  • display_name – The user’s display name (optional). Can be removed by explicitly passing auth.DELETE_ATTRIBUTE.

  • email – The user’s primary email (optional).

  • email_verified – A boolean indicating whether or not the user’s primary email is verified (optional).

  • phone_number – The user’s primary phone number (optional). Can be removed by explicitly passing auth.DELETE_ATTRIBUTE.

  • photo_url – The user’s photo URL (optional). Can be removed by explicitly passing auth.DELETE_ATTRIBUTE.

  • password – The user’s raw, unhashed password. (optional).

  • disabled – A boolean indicating whether or not the user account is disabled (optional).

  • custom_claims – A dictionary or a JSON string containing the custom claims to be set on the user account (optional). To remove all custom claims, pass auth.DELETE_ATTRIBUTE.

  • valid_since – An integer signifying the seconds since the epoch (optional). This field is set by revoke_refresh_tokens and it is discouraged to set this field directly.

  • app – An App instance (optional).

Returns:

An updated user record instance for the user.

Return type:

UserRecord

Raises:
  • ValueError – If the specified user ID or properties are invalid.

  • FirebaseError – If an error occurs while updating the user account.

verify_id_token

firebase_admin.auth.verify_id_token(id_token, app=None, check_revoked=False, clock_skew_seconds=0)

Verifies the signature and data for the provided JWT.

Accepts a signed token string, verifies that it is current, and issued to this project, and that it was correctly signed by Google.

Parameters:
  • id_token – A string of the encoded JWT.

  • app – An App instance (optional).

  • check_revoked – Boolean, If true, checks whether the token has been revoked or the user disabled (optional).

  • clock_skew_seconds – The number of seconds to tolerate when checking the token. Must be between 0-60. Defaults to 0.

Returns:

A dictionary of key-value pairs parsed from the decoded JWT.

Return type:

dict

Raises:
  • ValueError – If id_token is a not a string or is empty.

  • InvalidIdTokenError – If id_token is not a valid Firebase ID token.

  • ExpiredIdTokenError – If the specified ID token has expired.

  • RevokedIdTokenError – If check_revoked is True and the ID token has been revoked.

  • CertificateFetchError – If an error occurs while fetching the public key certificates required to verify the ID token.

  • UserDisabledError – If check_revoked is True and the corresponding user record is disabled.

firebase_admin.auth.verify_session_cookie(session_cookie, check_revoked=False, app=None, clock_skew_seconds=0)

Verifies a Firebase session cookie.

Accepts a session cookie string, verifies that it is current, and issued to this project, and that it was correctly signed by Google.

Parameters:
  • session_cookie – A session cookie string to verify.

  • check_revoked – Boolean, if true, checks whether the cookie has been revoked or the user disabled (optional).

  • app – An App instance (optional).

  • clock_skew_seconds – The number of seconds to tolerate when checking the cookie.

Returns:

A dictionary of key-value pairs parsed from the decoded JWT.

Return type:

dict

Raises: