ShadowLogin

Days of grace, running normally, before the licence stops applying when a subscription expires or when the server address does not match the licence. A renewal has almost always already been started, and an address that stops matching is far more often a NAT than a thief.

The address this server is known by, if you know it. Behind a proxy the machine never sees its own domain, and this line is the only way to tell it without calling anybody.

One call at start-up to the licence service (activation-url + /ip) to find out this server's public address: behind NAT it is the only way to recognise it. Only when a licence is installed: a server without a key asks nobody. false = never ask.

Activation service. This is the BASE address: the plugin appends /claim and /check itself. Empty means fully offline verification.

BCrypt's cost factor. Every +1 DOUBLES the time it takes.

10 -> about 60 ms      a little thin in 2026
12 -> about 250 ms     the recommended value
14 -> about 1 second   for few players and a lot of worry

When you raise the cost above, existing accounts still carry the old hash. With this option each password is recomputed at the new cost on its owner's next login: nobody has to do anything, and within a few days the whole database is up to date.

It never works the other way round: if you lower the cost, stronger hashes are left alone.

Minimum length. Six is the honest compromise for a Minecraft server: below that it gets guessed, above it people write it on a sticky note or reuse one from another site.

The maximum is NOT strictness: BCrypt only looks at the first 72 bytes, so beyond that characters stop counting. The plugin says so rather than letting you find out the day you change the end of a very long phrase and the old one still works.

Require a letter AND a digit. Off by default, and that is not an oversight: complicated rules produce worse passwords ("Marco1", "Password1") and stop nobody. If you turn it on, know what you bought.

Forbid a password identical to the player's own name. This one yes, because it is the first thing anybody tries.

Passwords that may not be used. These are the first entries in any dictionary: blocking them costs nothing and removes half of the account thefts on a Minecraft server.

Add your own server name: it is always on an attacker's list.

How many attempts before being kicked. Five is generous for somebody who really did mistype and tight for somebody guessing.

How long before a mistake is forgotten. Somebody who got it wrong once last month should not be dragging it around.

The wait after the first mistake, which then DOUBLES with every further one: 5s, 10s, 20s, 40s... up to the ceiling below.

After how many mistakes the account is locked outright, and for how long.

Whether to kick somebody who has run out of attempts. On: whoever is guessing passwords has to reconnect every time, and reconnecting goes through the antibot limits.

How long there is to log in before being kicked. Mostly this is against people who open connections and leave them sitting on a slot.

How often to remind somebody waiting what they are supposed to do. Five seconds is enough to be noticed without becoming annoying.

After logging in, push what was typed off the screen.

HONESTLY: no plugin can clear the client's local history - the up arrow will still bring back the typed command, and that is a limit of the game, not an oversight. This takes the line out of sight immediately, so it is not left sitting there while somebody watches the screen.

If this genuinely worries you, the answer is login.input: GUI: with the on-screen keypad the password never goes through the chat box at all.

Turns the whole chapter off: no calls to Mojang, passwords for everybody.

AUTO = an already-authenticated session comes in without a password.
OFF  = nobody skips the password, but name protection stays on.

- the server is in online-mode, or
- the server sits behind a proxy with forwarding configured, and
  trust-proxy-authentication below is on.

Whether to trust the UUID arriving from a proxy. Read the paragraph above: if you leave this on, make sure your server can ONLY be reached through the proxy. It only ever applies when this server really has proxy forwarding on (paper-global.yml proxies.velocity.enabled, or spigot.yml settings.bungeecord) and that proxy is declared online-mode (proxies.velocity.online-mode / proxies.bungee-cord.online-mode). Without forwarding no UUID comes from a proxy, and none is trusted.

Ask for a password even from somebody Mojang already authenticated. For people who want two barriers instead of one: it is less convenient and it is more secure, and it is a legitimate choice for a server with expensive ranks.

Stop a name belonging to a real account from being registered by an unauthenticated session.

This is the most important protection in the whole chapter. Without it anybody can connect using an official player's name before the owner arrives, register it with a password of their own, and from that moment they are that player: it is the most common theft on mixed servers.

How long to wait for Mojang's answer. Three seconds is generous: it sits in the middle of a connection, and one extra second is felt by whoever is coming in.

How many hours to remember an answer. A bought name stays bought; a free name bought today is discovered within three days at worst. Raising it reduces calls, lowering it increases them.

What to do when Mojang does not answer (it happens: they have had outages lasting hours). Under no circumstance is anybody blocked from coming in.

CACHE_THEN_PASSWORD = use the last known answer, otherwise ask for the
                      password (recommended)
PASSWORD            = just ask for the password

The service address. Change it only if you use a mirror.

THE PROBLEM, with the example that actually happens. Marco logs in with the original game, gets Mojang's UUID, and builds an island. The next day he logs in from an unofficial client with the same name: that UUID is a different one, so to the server he is A DIFFERENT PERSON. New island, empty inventory, no money. Marco does not understand, and he is right not to: he is still Marco.

OFF      = change nothing (default). Official and unofficial stay two
           different people, with two accounts, two islands and two
           inventories - which is also what the server would do by
           itself. Right for a server where the two never mix.

OFFLINE  = everybody gets the UUID computed from the name, official
           players included. RECOMMENDED on a mixed server, and the
           reason is that it depends on nobody: that UUID is worked
           out from the name with a calculation, always the same,
           without asking any service anything. A UUID that changes
           because Mojang was down for five minutes is a lost island.

PREMIUM  = everybody gets Mojang's real UUID, when the name has one.
           For servers that already have data created in online-mode
           and do not want to lose it. It costs one dependency: if
           Mojang does not answer for a name never seen before, the
           plugin does NOT guess - it refuses the connection with
           "try again in a minute". Letting somebody in under the
           wrong UUID is not an inconvenience like retyping a
           password: it is landing on nobody's island and building
           on it.

What to do when the name is right but the UUID is not.

DENY         = refuse the connection and write it in the console
               (recommended: this is exactly the dangerous case)
ASK_PASSWORD = let them try with the password, with no shortcuts at all
               (useful while you are changing your network setup and you
               know what you are doing)
ALLOW        = adopt the new UUID as the account's own
               (only for a migration, and only for as long as it takes)

How long it lasts. Half an hour covers a disconnect, a server restart and a hop between servers on a network; several hours starts to be a real window for somebody sitting down at another person's computer.

Tie the session to the address. Leave this on: without it a session would be valid from anywhere in the world, and at that point the password would be needed exactly once, ever.

Automatic, or on request.

false = a [ REMEMBER ME ] button appears after login and the player
        decides (recommended: trust is given, not imposed)
true  = a token is issued by itself on every password login

How long a token is worth, counted from the last time it was used - so a player who comes back every evening never meets the login screen, and a computer somebody stopped using stops being trusted a week later.

What a remembered device is anchored to when the client does not hand the token back. This is the setting that decides whether the feature actually works on your server.

ADDRESS = token first; if it does not arrive, the address the device was
          switched on from is accepted instead. RECOMMENDED, and the
          default: it survives closing the game and restarting the
          server, which is what a player means by "remember me".
          The trade: anybody sharing that address is indistinguishable
          from the owner for as long as the trust lasts. On a home
          connection that is the family; behind a mobile carrier it can
          be thousands of people. Shorten "duration" if that worries you.

COOKIE  = the token and nothing else. Stronger, and much more fragile:
          closing the game means typing the password again, and on some
          setups it means typing it every single time.

How long the just-replaced token is still accepted.

It exists for one real case: the connection drops between the moment the server replaces the token and the moment the client receives the new one. Inside this window the old one still works; outside it, presenting it means two copies exist, and the second was not made by the owner.

Keep it short. Every second here is a second in which a stolen copy would still be accepted as an honest retry.

Tie a remembered device to the address it was issued from.

Off by default, and on purpose: the whole point of this feature is to NOT depend on the address, which changes on its own (mobile data, a router reboot) and is shared by everybody in the same house. Turn it on only if your players have stable addresses and you want a second lock.

How many different computers one account may remember. The oldest drops off when number N+1 arrives.

The cookie name. Change it only if you have several servers behind the same proxy and you do NOT want them to share trust (see above). Lowercase letters, digits, dot, dash and underscore only.

Whether a trusted device also skips two-factor authentication.

Leave this false: the token proves the computer is the usual one, not that the right person is sitting in front of it. Those are two different questions, and somebody who turned on a second factor asked for both.

How long to wait for the client's answer DURING the connection. This is the fast path, and it holds a network thread while it waits, so it stays short on purpose.

The name shown in the authenticator app. Put your server's name here: somebody with twenty entries in their app needs to work out which one is you.

How many codes to accept before and after the current one (one = a minute and a half in total). This is for clocks that are not in sync. Raising it multiplies the codes valid at any instant: if you need more than 1, the problem is the server's clock.

How many backup codes to hand out. They are for the day the phone breaks: without them, that day the account is lost.

The security question, set by the player.

The code an operator generates with /shadowlogin resetpassword. This is the honest route: an administrator recognises the person and hands them a temporary token, instead of walking into the account in their place.

Use the player's world spawn, raised to the height below. Turn it off to use the fixed position in location.

Three hundred and twenty blocks: there is nothing to look at above the clouds, and from up there you cannot even tell which part of the map you are on.

How many blocks one may move. Not zero: blocking movement entirely makes the client "rubber-band" and the screen shakes. Three blocks let client and server stay in agreement.

Hide those waiting from everybody else, and everybody else from them. That way the login screen cannot be used to spy on who is online.

Blindness: the empty sky mentioned above.

Put the inventory aside and give it back after login.

The snapshot is written to the database BEFORE emptying anything, and if that write fails the inventory is not touched at all. So a sudden server crash costs nobody anything: on the first login after the restart everything comes back where it was.

No hunger while waiting.

How many simultaneous connections from one address. Three lets a family with three brothers through and stops a botnet on a single address.

IF YOU ARE BEHIND A PROXY WITHOUT REAL-ADDRESS FORWARDING, this number applies to THE WHOLE SERVER AT ONCE: read the "proxy" chapter below. The plugin notices by itself and tells you in the console.

How many registrations from one address inside the window. This is the limit that matters most: creating accounts is the only thing a bot can do that REMAINS after it has gone.

Above this many connections inside the window, the plugin works out that something is happening. Eight in five seconds is far more than a normal server sees, even a full one.

Strict mode switches itself ON above the threshold above, and for a few minutes only people who already have an account get in.

During strict mode, block new registrations as well.

The shape a name has to have. The default is exactly what Minecraft allows: 3 to 16 letters, digits and underscores.

CAREFUL if you have Bedrock players through Geyser: their names carry a prefix (usually a dot) and are longer. In that case use:

"^[.A-Za-z0-9_ ]{3,20}$"

Use the address the proxy declares (the player's real one). Set it to false only if you do NOT trust your forwarding: in that case everybody will look like they come from the same address. With forwarding on and this set to false the plugin knows it, and switches off everything keyed on the address: the per-address limits (they would apply to the whole server), address-bound sessions and devices remembered by address (they would let in anybody typing the name).

CHAT = /login and /register only
GUI  = the on-screen keypad only
BOTH = both, and the player chooses

Open the keypad by itself on join. Off by default: somebody used to typing /login would get a window in their face.

How many digits the PIN has. Do not go below six.

Minimum wait between two clicks, against click bots.

Do not announce "Marco joined" before Marco has typed his password: whoever joined is somebody who typed the name Marco. The message is sent after login, and if the login never happens it is not sent at all.

The table prefix. Change it if two servers share one database but must NOT share accounts.

An external MySQL or MariaDB. It buys one thing, and it is worth it only for that: on a network, a registration made on one server counts on all the others.

(Part of the Premium edition. Without a licence the plugin stays on the local database, with all of its data, and says so in the console.)

If MySQL does not answer, start on the local database instead of not starting. On: a login plugin that does not start is a closed server.

Lets another process open the same H2 file. Only useful if you know why you need it.

The default language. The files live in lang/: the plugin ships en_US and it_IT, and a file you add there is picked up too.

Follow the language each player has set in their client.

Move the language files to the new version when the plugin is updated: new texts arrive, the texts you changed stay yours, and the previous file is kept in backup/<date>/. With false the files in lang/ are never rewritten, and a text missing from them is read from the copy inside the jar.

Accept the section character as well as & in colour codes.

Do not start if another login plugin is installed.

Two plugins handling entry do not add up: they get in each other's way, and the result is not "more secure" but UNDEFINED. Leave this on.

Suspicious registrations and repeated attempts become a report in the panel. No password and no secret ever ends up in there: only what happened and to whom.

Teleport to spawn after login, and not before: before would mean showing spawn to somebody who has not yet proved they are who they say.

Permissions are recomputed after login. Before that none of them apply, and not because we take them away: because there is nothing that could use them.

Write every wrong password to the console (name and address, never the password). Useful for noticing a targeted attack.

Write every SQL statement. Only for working out a problem: it is slow and it fills the log.

bStats (https://bStats.org): how many servers use this plugin and which version they are on. What is sent, every 30 minutes: a random server id (serverUuid, not derived from anything), the plugin version, the Minecraft/Paper and Java versions, the operating system and core count, the online mode, how many players are online (a number only) and the licence tier (free/premium/creator). No player data of any kind: no names, no UUIDs, no addresses, no passwords. Nothing is sent while the plugin waits for a licence.

How many rows the window has. From 1 to 6.

The title changes depending on what is being done.

Confirm by itself as soon as the PIN is complete. One click less for somebody who logs in ten times a day.