Console Administration
Lurus uses Casdoor as its unified identity authentication platform, with the console available at identity.lurus.cn. This page is aimed at organization administrators / IT operations and covers the complete workflow for day-to-day operations.
Who should read this
Create / switch, domain verification, member roles, metadata
Human / Service Users, PAT, state transitions, auditing
Roles, Grant, Redirect URI, Token settings
Login / password / lockout / branding / notification policies
1. Console Navigation
After logging in, you enter the Management Console, which is divided into three areas:
- Top Breadcrumb: shows the current level (Instance level global / Organization level single tenant). Click the organization name dropdown to switch or create a new one (New organization). Instance-level operations require Instance Manager permissions; ordinary Org Owners only see their own Organization.
- Left-hand menu:
| Menu item | Function |
|---|---|
| Users | Human User / Service User management |
| Projects | Project, application, and Role management |
| Actions | Custom event-trigger scripts |
| Settings | Login / Password Policy / Branding and other policies |
| IDP | External identity providers (Google / GitHub / SAML, etc.) |
- Right-hand panel: clicking a list resource expands a details panel, where you can edit fields directly and save.
2. Organization Management （Organization）
2.1 Creating and Switching Organizations
Create: top dropdown → New organization → enter a name → choose the initial administrator identity (Current User sets the current account as Org Owner / New Account creates a separate admin account) → confirm.
Switch: top Breadcrumb dropdown → click the target organization name.
Self-service registration entry (B2B): customers visit https://identity.lurus.cn/ui/login/register/org to register an organization on their own.
2.2 Setting the Default Organization
Left-hand Organizations (Instance level) → the target organization row’s "..." → Set as default organization (the row shows a Default label).
If a user logs in without an organization context (no
urn:casdoor:iam:org:id:{id}scope), they fall into the default Organization’s policy and branding configuration.
2.3 Domain Verification
Binding a company email domain to an Organization enables domain-based login routing and direct single-point access.
Target Organization → Settings → Organization Domains → Add Domain → enter the domain (e.g. lurus.cn) → choose a verification method (DNS Challenge: add a TXT record in DNS with a value generated by Casdoor / HTTP Challenge: place a verification file at a specified path on the web server) → Verify → once verified, you can Set as primary to designate the primary domain.
WARNING
After the DNS TXT record is verified, do not delete it; Casdoor re-validates periodically, and deleting it will cause the domain status to lapse.
2.4 Member Management （Organization Members）
Add: Organization → Members → Add Member → search for a user (email / username) → assign a role → Save. Remove: the delete icon on the right of the corresponding row in the Members list.
| Role | Permission scope |
|---|---|
| Org Owner | All permissions within the organization, including member management |
| Org User Manager | Manage Human / Service Users |
| Org User Viewer | Read-only view of users |
| Org Project Creator | Create new Projects |
| Org Project Permission Editor | Manage Project Grants and role authorizations |
2.5 Metadata （Metadata）
Organization → Metadata → Add Metadata → enter Key / Value → save. Any key-value pair; can be read via the API for business extension fields.
3. User Management （Users）
3.1 Human User: Creation
Users → New → fill in First/Last Name, Email (you can check Email verified to skip verification), Username (defaults to the Email), Phone (optional) → choose the initial password policy (Setup authentication later the user sets it on first login / Send an invitation E-Mail sends an invitation email / Set an initial password the administrator sets it directly) → Create.
3.2 Human User: Day-to-Day Operations
- Reset password: user details → Security → Send Password Reset Email, or Set New Password to set it directly.
- Lock/unlock: top-right of the details page Lock / Unlock (after locking, the user cannot log in, and any existing Session becomes invalid at the next authentication).
- Send initial password email: details page → Resend Initialization Email.
- Reset MFA: details → Security → Authenticators → delete the target MFA device (TOTP / Passkey / U2F) → the user must re-register at next login.
3.3 User State Transitions
stateDiagram-v2
[*] --> Initial: Create
Initial --> Active: Initialization complete
Active --> Locked: Lock / policy triggered
Locked --> Active: Unlock
Active --> Inactive: Deactivate
Active --> Deleted: Delete
Deleted --> [*]Text version of the state diagram
[Initial] →(完成初始化)→ [Active]
[Active] →(Lock / 策略触发)→ [Locked] →(Unlock)→ [Active]
[Active] →(停用)→ [Inactive] [Active]→(删除)→[Deleted]| State | Description |
|---|---|
| Initial | Created but has not completed initial password setup or email verification |
| Active | Normal and able to log in |
| Inactive | Deactivated by an administrator, cannot log in |
| Locked | Exceeded the password error limit or manually locked |
| Deleted | Deleted; data is retained for auditing |
3.4 Service User: Creation and Configuration
Used for machine-to-machine communication (CI/CD, backend calls); does not log in with a password.
- Create: Users → Service Users → New → fill in Username and Display Name (Description optional) → Create.
- Generate a PAT: details → Personal Access Tokens → New → optionally set an expiry → after creation, copy it immediately (shown only once) → the caller sets the environment variable
Authorization: Bearer <token>. - Upload a JWT public key (Key File): details → Keys → Add Key → type JSON + expiry → Add → download the JSON Key file (contains the private key, shown only once) → the server uses the private key to sign a JWT and exchanges it at the token endpoint for an Access Token.
3.5 Auditing and Login History
- Login history: details → Login History (time, IP, User Agent, success/failure).
- Resource change history: at the bottom of any resource’s details page, Changes (Which User / Timestamp / Field / Old → New Value).
4. Project Management （Projects）
4.1 Creating a Project
Projects → Create New Project → enter a name (e.g. lurus-api, lucrum, switch) → Continue.
4.2 Project Settings (Settings tab)
| Setting | Description |
|---|---|
| Assert Roles on Authentication | Injects Roles into the Token and Userinfo at login; enabling recommended |
| Check Role Assignment on Authentication | Requires the user to have at least one Role Grant in this Project, otherwise login is denied |
| Check for Project on Authentication | Verifies whether the user’s Organization has obtained a Grant for this Project |
Branding policy: Unspecified (system default) / Enforce project’s policy (use the branding of the project’s Org throughout) / Allow login user policy (use the project’s branding initially, then switch to the user’s own Org branding once the user is identified).
4.3 Role Definition （Project Roles）
A role is just a string identifier; its semantics are defined by the business. Details → Roles → New Role → fill in Key (the code identifier, unique within the Project, e.g. admin/viewer/trader), Display Name (the name shown in the console), Group (optional, for grouped display) → Save.
4.4 User Grant (Granting a User a Role)
Details → Authorizations → New → search for the target user (Human / Service) → check the Role(s) (multiple allowed) → Save.
4.5 Project Grant (Cross-Organization Authorization, B2B)
Authorize an entire Project to another Organization, allowing it to manage the roles its users hold in that project. Details → Project Grants → New → enter the partner Organization’s domain to search and select → check the allowed Roles (you can limit to a subset) → Save.
The granted Organization’s administrator can see the project under Granted Projects and assign Roles to their own organization’s users.
5. Application Management （Applications）
5.1 Choosing an Application Type
Details → Applications → New Application → choose a type:
| Type | Use case | Authentication flow |
|---|---|---|
| Web | Server-side rendering (Spring / PHP / Django) | Authorization Code (PKCE recommended) + Client Secret |
| SPA（User Agent） | Frontend single-page (React / Vue) | Authorization Code + PKCE (no Client Secret) |
| Native | Desktop/mobile (Electron / iOS) | Authorization Code + PKCE |
| API | Machine-to-machine communication (microservices/scripts) | Client Credentials / JWT Profile |
| SAML | Enterprise integration (systems that don’t support OIDC) | SAML 2.0, upload Metadata XML or enter a URL |
5.2 Redirect URI Configuration
- Exact match, case-sensitive; you can add multiple (configure production/staging/local separately).
- Native Apps support custom schemes (
myapp://callback); IPv6 requires escaping the brackets:http://\[::1\]:8080/callback. - Typical Web configuration:
https://app.lurus.cn/auth/callback,https://staging.lurus.cn/auth/callback,http://localhost:3000/auth/callback(requires enabling Development Mode). - Post-Logout Redirect URI: the destination to redirect to after logout, also exact-match, multiple allowed.
5.3 Token Settings （Token Settings）
| Field | Description | Recommended value |
|---|---|---|
| Token Type | JWT (client-side signature verification) or Opaque (requires a callback to Userinfo) | JWT |
| Access Token Lifetime | Access Token validity period | 15 min |
| Refresh Token Lifetime | Refresh Token maximum validity period | 7 days |
| Refresh Token Idle Lifetime | Refresh Token expiry when inactive | 24 h |
| ID Token Lifetime | ID Token validity period | 1 h |
| Add User Roles to Token | Write Project Roles into Token claims | As needed |
| Add User Info to ID Token | Merge user info into the ID Token (reduces Userinfo requests) | Optional |
| Clock Skew | Tolerance for server clock skew | Default |
5.4 Development Mode
Details → Redirect Settings → check Development Mode: allows http:// Redirect URIs and Glob pattern matching (*, /**, ?).
WARNING
For local development only; do not enable in production.
5.5 Client Secret
Automatically generated after a Web application is created: shown once in a popup at creation time, copy it immediately. To regenerate: details → Generate New Client Secret (the old Secret is invalidated immediately).
6. Identity Providers （Identity Providers, IdP）
6.1 Built-in IdP Types
Organization → Settings → IDP → Add IDP:
| Type | Description |
|---|---|
| OAuth2, requires a Google Cloud Console Client ID/Secret | |
| GitHub | OAuth2, requires GitHub OAuth App credentials |
| GitLab | OAuth2, supports GitLab.com or self-hosted |
| Microsoft | Azure AD / Entra ID, single/multi-tenant |
| Apple | Sign in with Apple, requires an Apple Developer account |
| Generic OIDC | Any standard OIDC Provider, enter a Discovery URL |
| Generic SAML | Any SAML 2.0 IdP, upload Metadata |
| LDAP | Enterprise AD / OpenLDAP |
| JWT IDP | A custom JWT token issuer |
6.2 Adding a Generic OIDC IdP (Example)
Add IDP → Generic OIDC → fill in Name (the login-page button text), Client ID / Secret (registered on the IdP side), Issuer / Discovery URL (e.g. https://accounts.google.com) → configure field mapping (ID Attribute is usually sub; map First/Last Name / Email / Display Name to IdP claims) → set Auto Linking (None no linking, always create new / By Email merge by matching email / By Username merge by username) → Save. Once activated, the corresponding button appears on the login page.
6.3 Enabling an IdP in the Login Policy
Settings → Login Behavior and Security → External IDPs → check the IdP you just added → save.
7. Policy Management （Policies）
An Organization can override the Instance default policies (Organization → Settings, various submenus).
7.1 Login Policy （Login Behavior and Security）
| Toggle | Description |
|---|---|
| Username / Password | Allow username-and-password login |
| Registration | Allow self-service registration |
| External IDP | Allow third-party IdP login |
| Hide Password Reset | Hide the "Forgot password" link |
| Email / Phone as Login Name | Allow using email/phone number as the username |
| Domain Discovery | Automatically route to the corresponding Organization by email domain |
| Passkey / WebAuthn | Enable passwordless login |
| Force MFA | Force all users to enable MFA |
Session lifetimes: Password Check Lifetime / External IDP Check Lifetime / MFA Init Skip Lifetime (the grace period during which MFA setup can be skipped) / Second Factor Check Lifetime.
7.2 Password Complexity （Password Complexity）
Configurable: minimum length (Min Length), and whether uppercase/lowercase/digits/special characters are required.
7.3 Lockout （Lockout）
Max Password Attempts / Max OTP / TOTP Attempts (0 means no limit). After lockout, an administrator must unlock manually (details → Unlock).
7.4 Password Age （Password Age）
Max Age in Days (after expiry, login forces a reset) / Expiry Warning in Days (warn on the login page N days in advance).
7.5 Branding （Branding）
Logo/Icon (a set each for light/dark), Primary Color, Background Color, Warning Color, Font, Hide Watermark (hide "Powered by Casdoor"), Login Name Suffix (whether to display the login name suffix).
7.6 Privacy Policy （Privacy Policy）
Configure the URLs shown in the compliance-links area of the registration/login pages: Terms of Service, Privacy Policy, Help, Support Email (supports the {{.Lang}} language variable).
7.7 Domain Policy （Domain Policy）
| Toggle | Description |
|---|---|
| Username must contain org domain | The username becomes {user}@{org}.{instance-domain} |
| Validate Organization Domains | Require DNS/HTTP verification before a domain can be used |
| SMTP sender address must match domain | The notification email sender’s domain must match the organization’s domain |
| Email as username | Allow using the Email directly as the login username |
7.8 Notification （Notifications）
Trigger events: domain claim, user initialization (invitation/initial password), Passkey registration confirmation, password reset, Email verification, successful password change. Channels are configured via Settings → SMTP / SMS Providers (Twilio) with their credentials.
8. Actions (Custom Code Extensions)
INFO
Actions run JavaScript (in the Casdoor server-side sandbox) at key event trigger points such as login/registration/user creation, and the execution result can affect whether the flow continues or is interrupted.
Left-hand Actions → New Action → fill in a name, choose the trigger Flow and Trigger Type → write a JS handler function → activate and bind it to the Flow.
Common uses: call a business Webhook on user registration to sync to a CRM/data warehouse; inject a custom Claim into the Token (tenant_id, plan_tier); validate the email domain against an allowlist at registration.
Flow types (common):
| Flow | Trigger scenario |
|---|---|
| Complement Token | When an Access/ID Token is generated, inject extra claims |
| Internal Authentication | After successful password/Passkey authentication |
| External Authentication | After successful external IdP authentication |
| Save success login | When a successful login is recorded |
| User Creation | After a new user is created |
9. Auditing and Logs
- Events stream: at the Instance level, Events in the top bar / at the Organization level, Events after entering. The timeline lists all changes (Event Type / Aggregate / Editor / timestamp).
- Resource-level change history: at the bottom of each resource’s details page, Changes (Who / When / Field + Old → New Value).
- SIEM integration: the Events API (
/v2/events) filters by event type/time/resource ID and pushes to Elasticsearch / Loki / Splunk for compliance auditing.
10. Common Operational Scenarios for Lurus
Quick reference Four high-frequency operations playbooks — expand and follow along.
New employee onboarding
- Users → Human Users → New, fill in the name and work email, choose Send Invitation Email.
lurus-apiproject → Authorizations → New → search for the user → assign a role.- Repeat to assign Grants for projects such as
lucrumandswitch(by role). - Notify the employee to check the initialization email and complete password setup and MFA registration.
CI / machine account
- Users → Service Users → New; Username is recommended to be
ci-<service-name>. - Details → Personal Access Tokens → New set an expiry and copy the Token; or Keys → Add Key download the JSON Key file and configure the private key in CI.
- The corresponding Project → Authorizations assign the required Role.
Employee offboarding
- Top-right of the details page Lock (immediately blocks login, keeps the account and audit trail).
- For each associated Project → Authorizations → find the user → use the delete icon to revoke all Grants.
- If you confirm the audit data is no longer needed (usually not recommended), you can further Delete User.
Enterprise customer onboarding (B2B)
- Instance level → Organizations → New Organization, use the customer’s company name.
- Add an Org Owner (the customer’s IT admin account).
- Organization → Settings → Organization Domains verify the customer’s domain.
- If the customer has their own IdP (Azure AD): Organization → Settings → IDP add a SAML/OIDC IdP.
lurus-apiproject → Project Grants → New → select the customer’s Organization → assign the allowed Roles.- After the customer’s Org Owner logs in, they assign roles to their employees under Granted Projects.
Related documentation
Based on a self-hosted Casdoor instance (identity.lurus.cn); interface details are subject to the actual version. Please keep this document in sync with any policy changes.