Password Policy and Two-Factor Authentication

Two controls harden dashboard sign-in beyond a password:

• A password policy makes the members of an organization change their password regularly and stops them from reusing recent ones.
• Two-factor authentication (2FA) adds a one-time code from an authenticator app to every password sign-in. Each person turns it on for their own account, and an organization can require it of every member.

Both are available in AISIX Enterprise and AISIX Cloud. The organization settings are on the Sign-in security card under Settings. Only an organization owner can change them; other members see them read-only.

Neither control applies to admin tokens, which do not sign in to the dashboard. Members who sign in through the organization's single sign-on are covered by the identity provider's own policies instead.

Password Policy

The policy has two settings:

Setting	Default	Description
Password expires after (days)	0 (off)	0 turns expiry off. Otherwise, from 1 to 365 days. A member whose password is older than this is asked to change it before continuing.
Recent passwords that cannot be reused	5	From 0 to 24. A new password must differ from the current one and from this many before it. 0 means it only has to differ from the current one. This setting applies only while expiry is on.

To set the policy, sign in as an owner, open Settings, change the values on the Sign-in security card, and select Save changes. Changes are recorded in the organization's audit log.

When a Password Expires

With expiry on, a member whose password is older than the configured number of days cannot open the organization until they change it. The dashboard sends them to the change-password page, which explains that the organization's password policy requires a new password, and returns them to the page they were opening once the password is changed. Owners are not exempt.

During the last 7 days before the password expires, a banner at the top of the dashboard shows how many days are left, with a Change password link.

Changing the password ends every other session of the account, on every device, and the old password stops working.

The age of a password counts from when it was last set. For a password set before the control plane was upgraded to a version with this policy, it counts from the last time the account's sign-in record changed, so turning on a short expiry in an organization whose members set their passwords long ago can ask them to change their passwords right away.

Password Reuse

The reuse check applies whenever a member chooses a new password: on the change-password page, and on a forgotten-password reset link or a set-password link. A password that matches the current one or one of the recent passwords is refused with a message that the organization's password policy does not allow reusing it.

The control plane remembers up to the 24 most recent passwords of every account, whether any organization has a policy, so the check takes effect as soon as an owner turns expiry on. Passwords replaced before the control plane was upgraded to a version with this policy are not remembered.

Accounts in Several Organizations

In AISIX Cloud, one account can belong to several organizations. Each organization sets its own policy:

• Expiry is checked per organization. A password that is too old for one organization still opens the others.
• The reuse check takes the strictest setting, the largest number of recent passwords, among the organizations the account belongs to that have expiry on. An organization with expiry off does not count.

AISIX Enterprise has one organization, so its policy applies to the whole deployment.

Who the Policy Does Not Affect

• Accounts without a password, such as members provisioned through SCIM or created by single sign-on, have no password to expire.
• A session that completed the organization's single sign-on within the last 24 hours is not checked for expiry in that organization, because it did not sign in with the password. Single sign-on with another organization does not count.
• Admin tokens.

Two-Factor Authentication

Two-factor authentication belongs to the account, not to an organization: turning it on once covers every organization the account belongs to. It uses time-based one-time passwords (TOTP), the six-digit codes that authenticator apps such as Google Authenticator, Microsoft Authenticator, or 1Password generate, plus recovery codes for when the app is not available.

Enable Two-Factor Authentication

1. Select Security in the top bar.
2. Select Set up two-factor authentication.
3. Scan the QR code with an authenticator app, or enter the key shown below it into the app manually.
4. Enter the six-digit code the app shows. If your account has a password, also enter your current password. An account without a password, such as one created by single sign-on, needs only the code.
5. Select Turn on.
6. Save the 10 recovery codes the page shows: copy them or download them, and keep them somewhere safe. They are shown only this once.

The session you turned it on from counts as verified, so you can keep working.

The codes depend on the time, so the device running the authenticator app needs an accurate clock. Each code is accepted only once.

Sign In with Two-Factor Authentication

A password sign-in to an account with two-factor authentication takes two steps:

1. Enter your email address and password.
2. Enter the six-digit code from your authenticator app, or select Use a recovery code instead and enter one of your recovery codes.

The second step has to be completed within 5 minutes and allows 5 wrong codes. After that, the sign-in starts over from the password.

Signing in through single sign-on does not ask for a code. The identity provider is responsible for the second factor there.

Recovery Codes

Each recovery code works once in place of a code from the app. The Security page shows how many are left.

To get a fresh set, select New recovery codes on the Security page and enter a current code from the app or a recovery code. The page shows 10 new codes once, and every earlier recovery code stops working.

Disable Two-Factor Authentication

On the Security page, select Turn off and enter a current code from the app or a recovery code. Password sign-in then needs only the password again. If the organization you are working in requires two-factor authentication, the page warns you first: you cannot work in that organization again until you turn it back on.

Wrong-Code Limits

Wrong codes are limited at two levels:

• Per sign-in or session. A sign-in allows 5 wrong codes in its second step, after which it starts over. On a signed-in session, such as when generating recovery codes, turning two-factor authentication off, or verifying the session for an organization, 5 wrong codes in a row sign that session out.
• Per account. After 10 wrong codes in a row on the account, across all its sign-ins and sessions, the account accepts no second factor for 15 minutes, not even a correct code or a recovery code. The dashboard shows how many minutes are left. When the time is up, the count starts again from zero.

A correct code or recovery code resets both counts.

If You Lose Your Authenticator App

Sign in with a recovery code. Then, on the Security page, turn two-factor authentication off with another recovery code, and set it up again on the new device. This uses two recovery codes: one to sign in and one to turn it off.

Without the app and without any recovery code, you cannot complete a password sign-in. There is no reset in the dashboard, and an organization owner cannot reset it for you:

• In AISIX Enterprise, ask an operator to reset it from the command line.
• In AISIX Cloud, contact API7 support.

Reset Two-Factor Authentication for an Account

In AISIX Enterprise, an operator resets an account's two-factor authentication by running cp-api two-factor reset inside a running cp-api container. The command uses the container's own configuration to reach the database. It removes the account's authenticator and recovery codes, clears the wrong-code lock, and signs the account out of every session. The next password sign-in needs only the password, and an organization that requires two-factor authentication sends the person to set it up again.

On Kubernetes, with the chart installed as aisix-cp in the aisix namespace:

kubectl --namespace aisix exec deployment/aisix-cp-api -- \
  cp-api two-factor reset --email "user@example.com"

With Docker Compose or the offline package, run the command from the aisix-self-hosted package directory. run.sh names the Compose project aisix-self-hosted; if you started the stack with your own COMPOSE_PROJECT_NAME, use that name instead:

COMPOSE_PROJECT_NAME=aisix-self-hosted docker compose exec api \
  cp-api two-factor reset --email "user@example.com"

The email address is matched without regard to case. The command prints what it did and exits with 0. It exits with 1 when no account uses the address or the database cannot be reached, and with 2 when the arguments are malformed.

Requirements for AISIX Enterprise

The control plane encrypts the secret behind each account's codes with its master key, the same key that encrypts stored provider keys: secrets.masterKey in the Helm chart, AISIX_CLOUD_MASTER_KEY in the Docker Compose and offline packages. Every supported installation sets one. On a control plane started without a master key, setting up two-factor authentication fails with a message that the deployment has no master key.

Organization backups do not include two-factor authentication or remembered passwords, because they belong to accounts rather than to the organization. After a restore, members set up two-factor authentication again. The Require two-factor authentication setting is part of the organization settings and is restored.

Require Two-Factor Authentication

An owner can make two-factor authentication mandatory for an organization by turning on Require two-factor authentication on the Sign-in security card and selecting Save changes. The owner must turn on two-factor authentication for their own account first; until then, the setting cannot be turned on. The change is recorded in the audit log.

With the requirement on, a member can open the organization only through a session that verified their second factor:

• A member without two-factor authentication is kept in the organization, but the dashboard sends them to the Security page with a notice that the organization requires it. Once it is set up, they continue where they were.
• A member with two-factor authentication whose current session has not verified it, for example a session opened through another organization's single sign-on or before two-factor authentication was turned on, is asked for a code from the app or a recovery code. They stay signed in and continue where they were.
• A session that completed this organization's single sign-on within the last 24 hours is admitted without a code, because the identity provider is responsible for the second factor.

There is no grace period, and owners are not exempt. Admin tokens keep working. A member who turns two-factor authentication off while the requirement is on is stopped again the next time they open the organization.

Two-Factor Status of Members

The Members list shows whether each member's account has two-factor authentication on, as 2FA on or 2FA off. Because two-factor authentication belongs to the account, the status is the same in every organization the account belongs to.

The members API returns the same information as two_factor_enabled on each member.

Next Steps

Use Single Sign-On (SAML) to let members sign in through your identity provider, and Members to manage who belongs to the organization.