Login and SSO

The platform supports account/password login and enterprise single sign-on (SSO). After a successful login, a JWT is used as the admin access token, and you proceed to project selection.

Password login

1. Open the frontend address, for example http://localhost:7001 locally.
2. Enter your account and password and click Sign in.
3. After a successful login you enter the Workbench, and the project selection appears.

Security rules during login:

Item	Rule
Transport security	The login page must be deployed over HTTPS; passwords are never stored in plain text
Password storage	The server stores only the BCrypt hash, which cannot be reversed
Token type	JWT, default validity 2 hours (7200000 ms)
Token expiry	After expiry, 401 / 41005 is returned and you must log in again
No role	An account without an assigned role cannot log in; returns 41003
No menu	A role not associated with any menu cannot log in; returns 41004
Login failure	A wrong account or password returns 41001

Production deployment

Make sure to enable HTTPS, change the default administrator password, and assign roles to accounts following the principle of least privilege. Do not use default account credentials in public network environments.

Login state and project context

• The frontend writes the token from the login response into a cookie, and subsequent requests automatically carry Authorization.
• After login you must select a project; admin business requests automatically carry X-Project-Id.
• Refreshing the page does not lose the login state unless the token expires or the user signs out.
• After changing your password, it is recommended to log in again to refresh the token.

WeCom QR code login

The login page provides a WeCom entry. After clicking it:

1. The frontend requests WeCom authorization parameters from the backend (appId, agentId, redirectUri, state).
2. The page loads the official WeCom QR code script and displays the QR code in a popup.
3. After scanning and confirming, the browser redirects to the callback address.
4. The backend exchanges for the WeCom user identity and binds or matches it with a platform account.
5. Login succeeds and you proceed to project selection.

SSO binding relationships are stored in base_sys_sso_bind, with a one-to-one mapping between third-party identities and local users.

DingTalk login

DingTalk uses redirect authorization:

1. Click DingTalk login.
2. The browser redirects to the DingTalk authorization address.
3. After authorization is complete, DingTalk calls back to the platform.
4. The backend validates the state and exchanges for user information to complete login or binding.

Feishu

The frontend of the current version does not expose a Feishu login entry; if Feishu SSO is configured in your deployment environment, it can be integrated through the backend APIs and callback address, subject to the deployment configuration.

SSO callback handling

The callback page /login/sso/callback is responsible for:

• Parsing callback parameters and state.
• Calling the backend to exchange the login token.
• Writing the login state and redirecting to the Workbench on success.
• Displaying the error reason and providing an entry back to the login page on failure.

Common failure reasons:

Reason	Handling
state mismatch or expired	Restart SSO; do not reuse an old callback URL
Enterprise app trusted domain not configured	Configure the callback domain in the WeCom/DingTalk console
User not bound to a platform account	Have an administrator bind the account in the system, or create it automatically according to the deployment policy
Failed to obtain authorization parameters	Check the enterprise app Secret, AgentId and callback address configuration

Sign out

Click Sign out in the user menu at the top right; the platform clears the local token and returns to the login page. Signing out only affects the current browser session and does not disable the account.

Differences from open API authentication

Scenario	Authentication method
Admin pages and backend APIs	JWT (account login / SSO)
Open REST APIs	None / simple authentication (AppKey) / signature authentication (AppKey + AppSecret)
MCP (credential)	X-AppKey
MCP (agent)	X-Agent-Key

Open APIs do not use the admin JWT, and admin tokens cannot be used to call open APIs directly.

Related reading: Permission model, Signature authentication.