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
  Note: Password criteria parameters are not available in the client SDK. See Enforcing on the client side for how to validate passwords using the client SDK.

  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": "[e-mail]",
    "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:

1. If you haven't already done so, configure email and password sign-in.

2. 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 length
   • MAX_PASSWORD_LENGTH: the maximum required password length

3. 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().tenantConfigManager().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

1. 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',
     },
   })
   

2. 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().tenantConfigManager().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.