Enable, disable, and use password policies
This document shows you how to use password policies to improve password strength for new and existing users.
Overview
With password policies, you can improve account security by enforcing password complexity requirements. Password policies support the following password requirements:
- Lowercase character required
- Uppercase character required
- Numeric character required
- Non-alphanumeric character required
- Minimum password length (ranges from 6 to 30 characters; defaults to 6)
- Maximum password length (maximum length of 4096 characters)
The following characters satisfy the non-alphanumeric character requirement if configured:
^ $ * . [ ] { } ( ) ? " ! @ # % & / \ , > < ' : ; | _ ~ `
Before you begin
- Install the admin SDK
Enforcement modes
You can enable password policy enforcement in two modes:
- Require: Attempts to sign in fail until the user updates to a password that complies with your policy.
Notify: Users are allowed to sign in with a non-compliant password. Any missing criteria needed to satisfy the policy are returned. Criteria returned include:
MISSING_LOWERCASE_CHARACTER
MISSING_UPPERCASE_CHARACTER
MISSING_NUMERIC_CHARACTER
MISSING_NON_ALPHANUMERIC_CHARACTER
MINIMUM_PASSWORD_LENGTH
MAXIMUM_PASSWORD_LENGTH
You can send this information to the user to inform them to update their password. The following example shows a response containing missing password criteria:
{ "kind": "identitytoolkit#VerifyPasswordResponse", "localId": "CJL1i2", "email": "cloudysanfrancisco@gmail.com", "displayName": "", "idToken": "ID_TOKEN", "registered": true, "userNotifications": [ { "notificationCode": "MISSING_NUMERIC_CHARACTER", "notificationMessage": "Password must contain a numeric character" }, { "notificationCode": "MISSING_NON_ALPHANUMERIC_CHARACTER", "notificationMessage": "Password must contain a non-alphanumeric character" } ] }
New users are required to choose a password that complies with your policy. If you have active users, we recommend not enabling require mode unless you intend to immediately enforce the password policy. Instead, use notify mode, which allows users to sign in with their current passwords and sends notifications that detail the requirements their password lacks.
When you enable enforcement, set forceUpgradeOnSignin
to true
to enable enforcement
in require mode. Set it to false
to enable enforcment in notify mode.
Enable enforcement
To enforce a password policy, do the following:
- If you haven't already done so, configure email and password sign-in.
To enforce a password policy at the project level, run the following:
import { getAuth } from 'firebase-admin/auth'; // Update project config with password policy config getAuth().projectConfigManager().updateProjectConfig({ passwordPolicyConfig: { enforcementState: 'ENFORCE', forceUpgradeOnSignin: true, constraints: { requireUppercase: true, requireLowercase: true, requireNonAlphanumeric: true, requireNumeric: true, minLength: MIN_PASSWORD_LENGTH, maxLength: MAX_PASSWORD_LENGTH, }, }, })
Replace the following:
MIN_PASSWORD_LENGTH
: the minimum required password lengthMAX_PASSWORD_LENGTH
: the maximum required password length
To enforce a password policy at the tenant level, run the following:
import { getAuth } from 'firebase-admin/auth'; // Update project config with password policy config getAuth().tenantManager().createTenant({ displayName: "admin-tenant", passwordPolicyConfig: { enforcementState: 'ENFORCE', forceUpgradeOnSignin: true, constraints: { requireUppercase: true, requireLowercase: true, requireNonAlphanumeric: true, requireNumeric: true, minLength: MIN_PASSWORD_LENGTH, maxLength: MAX_PASSWORD_LENGTH, }, }, })
Disable enforcement
To disable password policy enforcement at the project level, run the following:
import { getAuth } from 'firebase-admin/auth'; // Update project config with password policy config getAuth().projectConfigManager().updateProjectConfig({ passwordPolicyConfig: { enforcementState: 'OFF', }, })
To disable password policy enforcement at the tenant level, run the following:
import { getAuth } from 'firebase-admin/auth'; // Update tenant config with password policy config getAuth().tenantManager().updateTenant(TENANT-ID, { passwordPolicyConfig: { enforcementState: 'OFF', }, })
Replace
TENANT-ID
with the tenant ID you want to disable a password policy for.
Enforcing on the client side
Passwords can be validated against the password policy for the project or a tenant on the client side before submission.
import { getAuth, validatePassword } from 'firebase/auth';
const auth = getAuth();
auth.tenantId = TENANT-ID;
const status = await validatePassword(auth, 'password').catch((error) => {
// Password could not be validated.
});
const policy = status.passwordPolicy;
// Use the status and policy to show what requirements are met and which are missing.