Signing in

This page explains how people sign in to the MicroB2B web UI. It covers passwords, the authenticator app, recovery codes, sessions and what happens after too many failed attempts.

One login page, every way in

Everybody signs in at /ui/login. The page offers every way in at once:

• Password: a user name, a password and a code from an authenticator app. This is always available.
• Single sign-on: a Sign in with <display name> button for each enabled identity provider. See identity providers.

You cannot turn sign-in off. MicroB2B does not start without PUBLIC_URL and SESSION_KEY. See required settings.

Scripts and other systems do not sign in. They use the REST API with a token. See service accounts.

Passwords

A password must be at least 12 characters and at most 256 bytes. MicroB2B refuses a password that:

• is on its built-in list of common passwords,
• contains the user’s name, display name or microb2b,
• is too repetitive.

There are no other rules: no required symbols or digits, and no expiry. A long phrase is good: you can remember it and others cannot guess it. MicroB2B stores only a hash of the password.

The authenticator app

Password login always needs a second step: a six-digit code from an authenticator app. Any app for time-based one-time codes works. Examples are Google Authenticator, Microsoft Authenticator, 1Password or Bitwarden.

When a user sets up their account, the setup page shows a QR code and a key. The user scans the code or types the key into the app. Then they enter a code from the app to prove it works. MicroB2B keeps the authenticator only after that.

A code changes every 30 seconds. MicroB2B accepts each code once. The phone’s clock must be roughly right. One step of difference either way is allowed.

Recovery codes

After setup, the user gets 10 recovery codes, like abcde-fghij. MicroB2B shows them once. Each code works once, in place of an authenticator code.

Tell users to store their recovery codes somewhere safe, away from their phone. On the login page they click Use a recovery code instead to enter one.

A user can make new codes on Your account with Get new recovery codes. The old ones then stop working.

How a password sign-in works

1. The user enters their name and password and clicks Sign in.
2. MicroB2B asks for a Code from your authenticator app. The user can also enter a recovery code.
3. The user is signed in.

If anything is wrong, the answer is always the same. It does not say whether the name, the password or the code was wrong. This makes guessing harder.

A user with password login off, or without a finished setup, cannot sign in with a password. They get the same answer.

Too many failed attempts

MicroB2B slows down repeated failed password sign-ins:

• Per account name: 3 failures are free. After that, each attempt waits longer: 1 second, then 2, then 4, up to 15 minutes.
• Per client address: 20 failures are free, then the same growing wait.

While a wait lasts, MicroB2B answers with HTTP status 429 and a Retry-After header.

This is a delay, never a lock. Once the wait has passed, the next attempt counts again. There is no unlock command and nobody is locked out for good. A successful sign-in resets the account’s count. Restarting MicroB2B resets all counts.

Behind a reverse proxy, MicroB2B sees every client with the proxy’s address. The per-address limit then applies to all clients together.

Identity providers handle failed sign-ins at their end.

Sessions

After signing in, the browser gets a session cookie. The cookie is encrypted and cannot be changed by the browser. Every sign-in method uses the same kind of session.

MicroB2B checks the session against the user on every request. These actions end a user’s sessions at once, however they signed in:

• disabling or deleting the user,
• any reset,
• changing the password or the authenticator,
• turning password login off,
• Sign out everywhere.

This also stops a stolen cookie from working.

A session lasts for SESSION_TTL, 8 hours by default. You can set it from 5 minutes to 72 hours, for example SESSION_TTL=4h. After that the user signs in again.

Logout clears the session cookie in that browser. It ends no other session of the user.

Changing SESSION_KEY ends every session of every user. If you run several MicroB2B instances behind one address, they all need the same SESSION_KEY.

HTTPS and cookies

The cookies are marked Secure and their names start with __Host-. Browsers keep such cookies only:

• over HTTPS (or on localhost), and
• when the site is served from the root of its host name.

So MicroB2B cannot run under a path prefix like https://example.com/b2b/. In production, put it behind a reverse proxy that handles HTTPS. For a trial on the same machine, http://localhost:8080 works.

The reverse proxy must pass the Cookie, Set-Cookie and Location headers unchanged. It must not cache /ui/login, /ui/setup/* or /ui/auth/*.

Setup links and logs

A setup link gives access to an account until it is used. MicroB2B leaves setup links out of its own access log. Your reverse proxy may log them. Stop it from logging them, or keep that log as private as the links.

When signing in fails

See troubleshooting sign-in. If nobody can sign in at all, see account recovery.