Identity and Accounts

When you set up Spokes, you might notice that managing users and logging in works a bit differently than some other apps.

This page explains how accounts work, where you should go to manage them, and why we designed it this way.

How Logging In Works

Spokes itself does not actually handle logins or store your passwords. Instead, it relies on a separate system called an Identity Provider (often shortened to IdP).

Think of it like the “Log in with Google” or “Log in with Apple” buttons you see on many websites, but instead of Google or Apple, you use a self-hosted identity provider. You can use popular providers like Authelia, Authentik, Keycloak, or the Casdoor instance that comes built-in with Spokes.

Here is what happens behind the scenes when someone uses Spokes:

1. A user visits your Spokes server’s URL.
2. Spokes redirects them to your identity provider’s login page (for example, your built-in Casdoor page).
3. The user enters their email and password to log in.
4. If successful, the identity provider sends them back to Spokes with a secure “ticket” (an OpenID token) that says, “This person is allowed in.”
5. Spokes checks its database. If this is the user’s first time, Spokes automatically creates a new profile for them using the name and email provided by the identity provider.

Where to Manage Users

Because the login system and Spokes are two separate things, user management is split into two places.

Let’s use the built-in Casdoor provider as our example.

1. The Casdoor Dashboard (For Logins and Signups)

Anything related to getting into the app happens in Casdoor. You use the Casdoor admin dashboard to:

• Create new user accounts.
• Change or reset user passwords.
• Delete user accounts entirely.
• Generate invitation codes for new users to sign up.

Tip: As a Spokes admin, you can quickly access the Casdoor dashboard by clicking the Open Casdoor button at the top of the Members & Groups page in Spokes.

2. The Spokes App (For Profiles and Permissions)

Anything related to what happens inside the app happens in Spokes. Once a user is logged in, you (or the user) can use Spokes to:

• Change their display name (first and last name).
• Update the email address displayed on their Spokes profile.
• Assign roles and permissions within Spokes groups.

(Note: Changing a user’s name or email inside Spokes does not change their login credentials in Casdoor. They will still log in with their original account details.)

Why Do We Do It This Way?

If this sounds like extra work, we completely understand! However, there are very good reasons for this architecture:

• Rock-Solid Security: Handling passwords securely is difficult and risky. By relying on a dedicated identity provider and standard industry protocols (OpenID), Spokes ensures your authentication is incredibly secure.
• Single Sign-On (SSO) for Everything: As self-hosters, managing separate accounts and passwords for every single app on your server is a nightmare. By using an identity provider, your users only need one account to log into all of your self-hosted services.
• The Perfect Middle Ground: By bundling Casdoor with Spokes, you get the best of both worlds. If you don’t already have an identity provider set up, Spokes is still a quick, easy install. Plus, you now have a fully functioning identity provider (Casdoor) that you can use to secure other self-hosted apps you might install in the future!

We know that bouncing between two dashboards isn’t always the most user-friendly experience. In the future, we plan to connect directly to Casdoor under the hood so you can create users and invitation links directly from within the Spokes interface.