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).

In addition, combined with Agentbase's multi-factor authentication (MFA, covering TOTP authenticator apps, email OTP, SMS verification codes, and one-time recovery codes), enterprises can quickly meet compliance and classified-protection requirements for identity verification, password complexity, concurrent session control, and multi-factor verification in finance, government, and large-enterprise internal control scenarios—without changing the structure of frontend business code. All policies saved on the Auth → Security page are written to the project metadata in real time and take effect immediately for all subsequent authentication requests in the project.


Core Concepts and Architecture

Agentbase embeds synchronous policy enforcers (Policy Enforcers) at every stage: end-user registration, login, password change, MFA challenge creation, and team member list queries. The diagram below shows where project-level security policies execute and their control logic throughout the full user authentication flow:

Security Policies: workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

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). Only blocks self-service client registrations; users created manually by administrators from the Console or members created via team invitations are not blocked by this limit.
Session lifecycleSession length (session lifetime)Defines the lifetime of newly created or renewed sessions (configurable in Days, Hours, Minutes, Seconds). Changing this setting only affects sessions created or renewed after saving; existing online sessions are not immediately signed out.
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 strength compliancePassword history / dictionary / personal dataEnforces validation of newly set passwords: they must not repeat any of the most recent 1–20 historical passwords, must not match the built-in dictionary of tens of thousands of common weak passwords (e.g., 12345678, password), and must not contain the user's own name, email prefix, or phone number fragments.
Proactive session defenseSession alerts & Invalidate sessionsSession alerts: automatically sends a security reminder email to the user's inbox when a session is created by a new device login; Invalidate: after the user changes their password, all existing sessions under their account are automatically invalidated immediately, blocking potential account thieves from continuing to access with old tokens.
Multi-factor authentication (MFA)TOTP / Email / Phone / Recovery CodesOnce MFA is enabled for an account, after the first factor (e.g., email and password) passes verification, only an intermediate state requiring secondary verification (user_more_factors_required) is returned; the client must complete the authenticator app dynamic code (TOTP), email verification code, or SMS verification code challenge before accessing protected resources.
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, when administrators create users or reset passwords in Auth → Users, and when end users change passwords from the client, the same password rules apply.

    • 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

After entering the Auth → Security page, seven policy configuration cards are arranged from top to bottom. Each card supports independent modification, and clicking the Update button at the bottom right saves changes immediately:

Authentication security settings page (reusing the registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

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 boxUnlimited (unlimited) or Limited (1–10000; entering 0 and saving is equivalent to Unlimited)For public ToC/ToB portals choose Unlimited; internal closed pilot projects can set Limited (e.g., 500)Only restricts the client-side new user registration endpoint; users manually created by Console administrators or via team invitations are not restricted.
Session lengthDuration value + time unit dropdownUnits available: Days (days), Hours (hours), Minutes (minutes), Seconds (seconds)For enterprise internal customer service agents, it is recommended to set 7 Days or 24 Hours; for highly sensitive admin consoles, 8 Hours is recommendedThe expiration time is calculated based on the current configuration only when a session is newly created or renewed; saving the change itself will not immediately log out currently online users.
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 historyToggle + number of remembered passwords Limit (1–20; saving 0 means disabled)Enabled, 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)EnabledVerifies that a new password does not contain any substring of the user's own Name, Email (including the email prefix), or Phone.
Session securitySession alertsBoolean toggle (on / off)Enabled (ensure the project's SMTP is properly configured)Whenever a new login session is created for a user account, a reminder email containing the login device, IP, and country information is automatically sent to the bound email address.
Session securityInvalidate (invalidate all sessions after password change)Boolean toggle (on / off)EnabledAfter a user completes a password change or reset, the server immediately clears and destroys all existing sessions of that user, forcing re-login.
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 SIT testing 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.

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.10.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:

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

const client = new Client()
    .setEndpoint('https://appbuild.oceanbase.com/v1')
    .setProject('enterprise-ai-hub-210');

const account = new Account(client);

async function signInWithMFA(email, password, getTotpCodeFromUI) {
    // Step One: standard email/password login to create the initial session
    await account.createEmailPasswordSession(email, password);

    try {
        // Attempts to read the current account info; if the user has MFA enabled and the second verification step is not yet completed, the server throws user_more_factors_required
        const user = await account.get();
        return user;
    } catch (error) {
        if (error.type === 'user_more_factors_required') {
            // Step Two: query the MFA factors available to the user (e.g. totp / email / phone)
            const factors = await account.listMfaFactors();

            // Step Three: initiate a TOTP (or Email / Phone) challenge
            const challenge = await account.createMfaChallenge(
                factors.totp ? AuthenticationFactor.Totp : AuthenticationFactor.Email
            );

            // Step Four: prompt the user to enter the 6-digit one-time code and complete challenge verification
            const otpCode = await getTotpCodeFromUI();
            await account.updateMfaChallenge(challenge.$id, otpCode);

            // After verification passes, the current session is formally upgraded to fully authorized status
            return await account.get();
        }
        throw error;
    }
}

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: When the client calls account.createPhoneToken(ID.unique(), '+8619900000001'), the system will not send a request to the SMS gateway and directly returns success; subsequently calling account.createSession(userId, '654321') directly creates a real, valid end-user 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: Yes, they can log in normally. All password compliance policies (Password history, Password dictionary, Disallow personal data) are only triggered when creating a new user, changing a password, or resetting a password (i.e., write operations on the password field); the system does not enforce checks against legacy passwords during regular login verification (because the server only stores irreversible password hashes, not plaintext). To force legacy users to upgrade password strength, guide them through the password reset flow.

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.