MCIdentity Central Server

What it is

• A separate program you run once for your network, next to your game servers rather than inside them. The current version is 3.4.5.
• The single owner of identities, professions, stats, sessions, base identity slots, aliases, and the audit log.
• A home for the add-ons' data too: runes, cosmetics, and equipped skills can live on it when those add-ons are pointed at the central server. MCIdentityPerks keeps its own database and does not use it.
• An optional choice. A single server, or a network happy to share one ordinary database, does not need it. See Data Storage for the alternatives.

How it works

1. You start the Central Server with a secret API token, and give the same token to each game server in its MCIdentity configuration, together with the server's address.

2. When a player logs in, the game server first checks that the Central Server is reachable. That check also wakes up a deployment that sleeps when idle, and players are politely asked to wait while it starts.

3. From then on, every read and write MCIdentity makes goes to the Central Server over the network, in the background, so the game never pauses for it. Data in use is still cached in the game server's memory.

4. The Central Server checks every request, saves the change in its own database, and answers. Because there is only one copy of the data, two game servers can never disagree about a player.

Storage

The Central Server keeps its data in one of two databases, both with exactly the same layout:

The layout also matches the SQLite file the MCIdentity plugin writes on its own, so an existing server's data file can be moved onto the Central Server as it is.

Security

The Central Server holds every player's data, so it is locked down by default:

• Tokens with roles. Game servers use a read and write token. An optional second token can only read, for things like a public stats page, and every write made with it is refused.
• Address allow-list. It can be told to accept requests only from your game servers' addresses.
• Brute-force protection. Failed logins are counted separately, and an address that keeps guessing is shut out for a while.
• Rate and size limits. Each address can only send so many requests per minute, and oversized requests are refused.
• Strict input checks. Every value is checked before it is stored, and stat names must come from the fixed list of nine.
• Hardened defaults. Browser access is allowed only from addresses you name, standard protective headers are always sent, and the container never runs with administrator rights.

Running it

• It runs on Node.js 22.13 or newer, or from the ready-made container image, which keeps its database in a persistent volume and reports its own health.
• All settings, including the token and the database choice, are given as environment settings when it starts. No secret is ever built into the image.
• In production it sits behind a reverse proxy that provides the secure connection.
• An open health check, which needs no token, lets the plugin and the container platform see that it is up.

Compatibility

Each Central Server release is checked against the requests every plugin actually sends.

The add-ons reach the Central Server through the core plugin's own connection, so an add-on stored on the central server needs MCIdentity 4.7.0 or newer.