Built-in Identity (Casdoor)

Spokes offers a zero-configuration identity solution by bundling an embedded instance of Casdoor, a powerful OpenID Connect (OIDC) provider. This built-in option is recommended for most users as it simplifies deployment while offering enterprise-grade identity management features.

This page explains how the Casdoor integration works under the hood and how to manage it.

High-Level Architecture

When you select “Built-in Identity” during the Setup Wizard, Spokes automatically configures and provisions a local Casdoor server.

• Embedded Service: Casdoor runs inside the exact same Docker container as the main Spokes application. A process manager (Supervisor) handles keeping both the Spokes Server and Casdoor running smoothly.
• Data Storage: Casdoor stores its data in a dedicated SQLite database (casdoor.db) located in the persistent data volume, separate from the primary Spokes database.
• OIDC Integration: Spokes communicates with Casdoor via standard OpenID Connect protocols (OIDC) over localhost. From Spokes’ perspective, it is communicating with a standard external identity provider.

Administration & Management

Organizations Explained

To isolate your server’s data from global identity settings, the built-in Casdoor instance is divided into two distinct organizations:

1. The built-in Organization

This is Casdoor’s root organization. It owns the base identity system and has absolute access to everything. The Global Admin account belongs to this organization.

2. The spokes-org Organization

This is an automatically generated organization dedicated entirely to your Spokes server. The Spokes Admin account belongs to this organization. Users, groups, and permissions used by your server are all managed within spokes-org.

Administrator Accounts

During the Setup Wizard, you are asked to create two administrator accounts. It is crucial to understand the difference between them.

Global Admin (System Management)

• Username: admin (Fixed)
• Organization: built-in
• Purpose: Managing the Casdoor identity server itself globally.
• Capabilities: Adding third-party login providers (Google, GitHub, etc.), configuring identity syncers (LDAP/Active Directory), setting up webhooks, and modifying global security policies.

Spokes Admin (Day-to-Day Management)

• Username: Chosen during setup (defaults to admin)
• Organization: spokes-org
• Purpose: Managing your server’s directory within Spokes.
• Capabilities: Adding/removing users, creating teams, resetting user passwords, and managing permissions specific to the Spokes application.

Save Your Credentials!

The passwords for both admin accounts are displayed only once at the end of the Setup Wizard. If you lose them, you may lose access to your identity server.

Accessing Casdoor

Depending on your role and what you need to configure, there are two ways to access the Casdoor admin interface:

Method 1: The “Open Casdoor” Button (For Spokes Admins)

If you are logged into Spokes and have administrative privileges (or the ManageUsers permission):

1. Navigate to the Directory (Organization) page in the Spokes server UI.
2. Click the Open Casdoor button in the top right corner.
3. You will be automatically logged in as your current user within the spokes-org context.

Method 2: Direct Login (For Global Admins)

To access the root built-in organization and configure global identity settings, you must log in directly with the Global Admin account:

1. Open an Incognito / Private Browsing window (or ensure you are completely logged out of Spokes).
2. Navigate directly to the login page: https://spokes.yourdomain.com/login
3. Enter the Global Admin credentials (Username: admin + the global password from the Setup Wizard).

Additional Integration Details

Spokes takes several steps to ensure the Casdoor experience feels native and seamless:

• Branding Synchronization: When you update your server name, logo, or icon in Spokes, those changes are automatically synchronized to the Casdoor application. Your users will always see a login page that matches your brand.
• First-Run Sanitization: By default, Casdoor exposes dozens of complex identity management fields. Spokes automatically sanitizes the spokes-org UI, hiding unnecessary navigation items and profile fields so your users are presented with a clean, easy-to-understand directory.