Docs
Contents

Security Policies

Feature Overview

Authentication security policies (Security) are the project-level identity security control hub of Agentbase (route: /console/project-{region}-{project}/auth/security). In enterprise production environments (e.g., the sample project 企业智能客服与知识中台, Project ID: enterprise-ai-hub-210), security administrators can use the seven core configuration cards on this page to define, in one place: the project's total end-user registration limit (Users limit), login session lifetime (Session length), maximum concurrent online devices per user (Sessions limit), enterprise-grade password compliance policies (Password policies: password history reuse prevention, weak password dictionary blocking, personal sensitive information exclusion), session security alerts and automatic session invalidation on password change (Session security), mock phone numbers for testing and mobile app store reviews (Mock phone numbers), and privacy visibility boundaries among multi-tenant team members (Memberships privacy).

Agentbase also provides multi-factor authentication (MFA), including authenticator apps, email, SMS, and recovery codes. Clients must implement the corresponding verification flow; verify policy and compliance requirements for your deployment and use case.


Core Concepts and Architecture

Agentbase applies project security policies to operations such as registration, login, and password changes. The table below describes each policy and its boundaries.

Core Security Concepts and Mechanisms

Security control domainCore policy itemsRuntime execution semantics and technical boundaries
Anti-abuse total limitUsers limit (user registration limit)Limits the maximum total number of end users the project can contain (Unlimited or 1–10,000). In a non-Console project, an invitation by a non-privileged, non-app caller also checks the limit if it must create a new user. Inviting an existing user does not trigger this new-user check; privileged or app callers and the Console project are exempt from this invitation check.
Session lifecycleSession length (session lifetime)Defines the lifetime of newly created or renewed sessions (configurable in Days, Hours, Minutes, Seconds). After the duration is shortened, background cleanup may remove existing sessions whose creation time exceeds the new duration. Do not assume saving the setting immediately signs out existing sessions.
Concurrent device evictionSessions limit (concurrent session limit)Limits the maximum number of devices/sessions a single end user can keep online simultaneously (range 1–100). Evaluation is triggered on the next successful new login: if the limit is exceeded, the system automatically evicts and destroys the user's oldest sessions in FIFO order.
Password policiesPassword history / dictionary / personal dataPassword history, dictionary, and personal-data checks can be configured. Validation differs across account creation, self-service changes, administrator changes, and password recovery. For example, self-service changes check personal data when enabled; the recovery path does not perform the same check. Verify each path used by your application after enabling a policy.
Proactive session defenseSession alerts & Invalidate sessionsSession alerts queues an email for some logins when conditions are met; it does not compare devices or guarantee delivery. With Invalidate enabled, a self-service password change deletes other sessions only when the current session is identified, and preserves that current session; an administrator password change deletes all of the user's sessions. Password recovery does not automatically delete sessions on that path. Explicitly revoke and verify sessions when all devices must be signed out.
Multi-factor authentication (MFA)TOTP / Email / Phone / Recovery CodesWhen MFA is enabled, successful email/password login first creates an initial session. Accessing a protected endpoint before that session completes the required factor verification may return user_more_factors_required. The client should guide the user through an available second-factor challenge before retrying.
Testing sandbox capabilityMock phone numbers (mock phone numbers)Allows pre-registering up to 10 groups of virtual test phone numbers (9–16 digits) with fixed 6-digit verification codes. Logging in with these numbers does not call the real SMS gateway; the preset code is verified directly—dedicated to automated E2E regression testing or Apple App Store / mobile app marketplace review demonstrations.
Multi-tenant member privacyMemberships privacy (team member privacy)Controls whether ordinary members of the same team can see other members' Name, Email, and MFA status when querying the member list from the client. Unchecking the corresponding checkbox only hides and masks data in responses; it does not delete underlying data.

Roles, Entry Points, and Relationships

Console Entry Point and Shortcuts

Relationships with Other Modules

  1. Integration with user management (Auth Users):

    • After password policies are enabled on the Security page, validation paths can differ when administrators create users or reset passwords in Auth → Users and when end users change passwords from the client; verify each operation separately.

    • If a user's TOTP authenticator device is lost, the administrator can go to the Auth → Users → user details → Overview → Multi-factor authentication card and click Delete authenticator to unbind it.

  2. Integration with email templates (Auth Templates):

    • After enabling Session security → Session alerts, the content of the new-session alert emails sent by the system is defined by the Session alert template in Auth → Templates (containing the {{device}}, {{ipAddress}}, {{country}} variables).

    • When using email as the MFA second factor, the verification code email content is defined by the 2FA verification template.

  3. Integration with team management (Auth Teams):

    • The checkbox state of the Memberships privacy card directly determines the visibility of member fields returned when the client calls teams.listMemberships(teamId).


Feature Details and Operation Guide

On Authentication → Security, edit each policy separately and select Save on the corresponding card. Editable settings depend on project permissions:

Password policy settings

Figure: Password policy settings in a 2.12.0 test project. Choose policies appropriate to your security requirements.

The table below summarizes each card's configuration fields, value ranges, system default behavior, and the recommended security baseline for production environments (such as enterprise-ai-hub-210):

Card nameConfiguration fieldValue range and constraintsRecommended production baseline (enterprise-ai-hub-210)Key behavior and activation timing
Users limitUnlimited / Limited + quantity input boxEnable the unlimited switch, or turn it off and enter 1–10000For public ToC/ToB portals choose Unlimited; internal closed pilot projects can set Limited (e.g., 500)In non-Console projects, an invitation by a non-privileged, non-app caller also checks the limit if it creates a user. Inviting an existing user, privileged or app callers, and the Console project are exempt from this invitation check.
Session lengthDuration value + time unit dropdownChoose days, hours, minutes, or seconds; the server limit is 31536000 seconds after conversionFor enterprise internal customer service agents, it is recommended to set 7 Days or 24 Hours; for highly sensitive admin consoles, 8 Hours is recommendedThe console warns that shortening the duration may log out current users; verify existing session behavior in the target environment before changing it.
Sessions limitMaximum number of active sessions per userInteger, 1–100It is recommended to set 3 or 5 (allowing users to log in simultaneously from desktop browsers, mobile devices, and tablets); for strict single sign-on, set 1The check is triggered only on the user's next new login: if the number of active sessions has reached the limit, the system automatically logs out the user's earliest created session.
Password policiesPassword historyUse the toggle to enable or disable it; when enabled, the server accepts a history count of 1–20, and API value 0 disables itEnabled, with Limit set to 5 (prohibits reuse of the last 5 passwords)The server securely stores historical password hash digests and compares them only when the user newly sets or changes a password; it does not affect login with existing passwords.
Password policiesPassword dictionaryBoolean toggle (on / off)EnabledRejects common weak passwords and frequently leaked passwords (such as password123, qwertyuiop, admin888).
Password policiesDisallow personal dataBoolean toggle (on / off)EnabledOn applicable paths, checks the complete user ID, full email or email prefix, complete name, and complete phone number (with or without a plus sign); arbitrary fragments are not checked. Password operations do not all use the same validation path.
Session securitySession alertsBoolean toggle (on / off)Enabled (ensure the project's SMTP is properly configured)When conditions are met, a reminder with device, IP, and country information is queued; delivery is not guaranteed. See the conditions below.
Session securityInvalidate (handle sessions on password change)Boolean toggle (on / off)EnabledA self-service password change deletes other sessions only when the current session is identified and preserves that session; an administrator password change deletes all of the user's sessions; password recovery does not automatically delete sessions on that path. Explicitly revoke and verify sessions when all devices must be signed out.
Mock phone numbersMock phone number list (Phone number + Verification code)Add up to 10 entries; phone number length 9–16 digits, fixed verification code of 6 digitsConfigure only as needed during testing in a test environment or mobile app store review (e.g., +8619900000001 corresponds to verification code 123456); in production, clear the list or keep only a dedicated sandbox numberPaid/licensed capability: The cloud requires the corresponding plan; self-hosted requires enabling the license. Real SMS sending is skipped when logging in with a mock number.
Memberships privacyName / Email / MFA status three checkboxesAll checked by default (publicly displayed to fellow team members)For external teams shared across enterprise customers (e.g., teams containing vip_guest), it is recommended to uncheck Email and MFA status, keeping only NameUnchecking does not delete user data; it only masks the corresponding fields when the client queries the team member list, preventing information leakage between customers.

Session alert conditions: With Session alerts enabled, an email/password login queues an alert only when the user session count is not 1. Token-based session creation additionally requires a user email and excludes Magic URL and email tokens. This checks the session count, not whether the device is new; the first session normally does not trigger an alert. A later session on the same device may trigger one. Delivery depends on the mail service and queue processing.

2. Multi-Factor Authentication (MFA) End-to-End Workflow Guide

Agentbase allows end users to self-bind and enable multi-factor authentication (MFA), supporting four verification factors:

  1. TOTP authenticator app (Authenticator App): Compatible with standard TOTP apps such as Google Authenticator, Microsoft Authenticator, and 1Password (dynamic 6-digit codes, rotating every 30 seconds).

  2. Email second-factor verification (Email MFA): Sends a one-time 6-digit verification code to the user's verified (emailVerification = true) bound email address.

  3. Phone SMS second-factor verification (Phone MFA): Sends a one-time 6-digit SMS verification code to the user's verified (phoneVerification = true) bound phone number.

  4. One-time recovery codes (Recovery Codes): A set of backup recovery codes generated when MFA is enabled, for emergency verification when the phone is lost or codes cannot be received.

Client-Side Integration Example for MFA Login and Challenge Verification (agentbase-web-sdk@2.12.0)

When a user (such as senior support specialist Li Na user_lina_002) has MFA enabled, the standard flow for frontend login and completing second-factor verification is as follows:

Before running, replace <APPBASE_ENDPOINT_WITH_V1> and <APPBASE_PROJECT_ID> with the confirmed target API endpoint and project ID. Until replaced, the SDK rejects the invalid endpoint before making a request.

import { Client, Account, AuthenticationFactor } from 'agentbase-web-sdk'; // Pin version @2.12.0

const client = new Client()
    .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
    .setProject('<APPBASE_PROJECT_ID>');

const account = new Account(client);

async function signInWithMFA(email, password, chooseFactorFromUI, getCodeFromUI) {
    await account.createEmailPasswordSession(email, password);
    try {
        return await account.get();
    } catch (error) {
        if (error.type !== 'user_more_factors_required') throw error;
        const factors = await account.listMfaFactors();
        const available = [
            factors.totp && AuthenticationFactor.Totp,
            factors.email && AuthenticationFactor.Email,
            factors.phone && AuthenticationFactor.Phone,
            factors.recoveryCode && 'recoveryCode',
        ].filter(Boolean);
        if (available.length === 0) throw new Error('No MFA factor available');
        const factor = await chooseFactorFromUI(available);
        if (!available.includes(factor)) throw new Error('Invalid MFA factor selection');
        const challenge = await account.createMfaChallenge(factor);
        const code = await getCodeFromUI(factor);
        await account.updateMfaChallenge(challenge.$id, code);
        return await account.get();
    }
}

The current Web SDK enum value Recoverycode differs in case from the server recovery-code factor. This JavaScript example explicitly sends recoveryCode; if a TypeScript SDK type rejects it, check the SDK version or send recoveryCode through the REST API.

3. Steps to Configure Mock Phone Numbers

When performing automated E2E testing (such as verifying the SMS verification code login flow) or submitting demo accounts for app store review, frequently calling real SMS channels not only incurs costs but also easily triggers carrier rate limiting:

  1. On the Auth → Security page, scroll down to the Mock phone numbers card.

  2. Click the Add number button to add a new configuration row:

    • Phone number: Enter a 9–16 digit test-only virtual phone number (e.g., +8619900000001).

    • Verification code: Enter a fixed 6-digit numeric verification code (e.g., 654321).

  3. Up to 10 mock number entries can be added; after filling them in, click the Update button at the bottom right of the card to save.

  4. Test verification: First ensure the environment meets SMS configuration, permission and deployment-policy requirements; mock numbers do not bypass those checks. After they pass, account.createPhoneToken(ID.unique(), '+8619900000001') with a matching mock number avoids real SMS delivery. Use the returned user ID and preset code with account.createSession(userId, '654321') to create a session.


FAQ and Troubleshooting

Q1: I changed Session length from 365 days to 1 day and changed Sessions limit from 10 to 1. Why haven't currently logged-in users been immediately logged out?

Root cause analysis: This is a smooth transition mechanism designed by Agentbase to prevent configuration changes from causing large-scale online avalanches:

Solution: If you need to immediately force all online devices of a specific user (e.g., a departed employee or an abnormal account) offline, go to Auth → Users, open that user's detail page, switch to the Sessions tab, and click Sign out all sessions in the upper-right corner (or click Block account on the user's Overview tab to block the account).

Q2: After enabling Password dictionary and Disallow personal data, can previously registered legacy users still log in with their old simple passwords?

Answer: Existing passwords are not automatically changed when new policies are enabled; login still depends on account status and other authentication requirements. User creation, self-service changes, administrator changes, and password recovery follow different validation paths, so do not assume every policy is enforced identically on each path. When replacing weak passwords, verify password policy enforcement and session revocation in the deployed environment.

Q3: A user enabled TOTP MFA, then switched to a new phone. They cannot generate the 6-digit dynamic code and did not save recovery codes. How can the account be unlocked?

Troubleshooting steps:

  1. Log in to the Agentbase Console as an administrator and go to the project's Auth → Users.

  2. Search for and click into the user's detail page (/auth/user-{userId}).

  3. At the bottom of the Overview tab, locate the Multi-factor authentication card.

  4. Click the Delete authenticator button to the right of TOTP (One-time code) and confirm in the dialog (note: deleting the authenticator is irreversible). Alternatively, temporarily turn off the user's overall MFA toggle, and have the user re-bind the authenticator app on their new phone after logging in.