Signing in and the REST API

This page helps when you or a user cannot sign in, when single sign-on fails, and when the REST API refuses a request. Each heading is what you see. Below it are the likely causes and what to do.

For how signing in works, see Signing in. For identity providers, see Identity providers.

Signing in with a password

Nobody can sign in to a new installation

There is no default user. Create the first one on the server, with the same DB_TYPE and DB_URL as MicroB2B:

microb2b users create admin

It prints a setup link. Open it, choose a password and set up the authenticator app. See Users.

The setup link is only a path, like /ui/setup/...

PUBLIC_URL was not set when you ran the command. Put the address of MicroB2B in front of the path, or set PUBLIC_URL and run the command again.

This setup link does not work

The link was already used, was replaced by a later reset, is older than 24 hours, or the user’s password login was turned off. Make a new one: reset the user on Access > Users, or run microb2b users reset-password <name> on the server.

The name, password or code is not correct, or the account cannot sign in.

MicroB2B gives the same answer for every refusal, so it does not tell an attacker which part was wrong. Possible causes:

• A wrong name, password or code.
• A code that was already used. Each code works once.
• The phone’s clock is off. A code is valid for 30 seconds, with one step of leeway either way.
• The user is disabled, or has not finished setup.
• The user’s password login is off. A user of an identity provider signs in with the Sign in with button.

The log line Sign-in refused says which, with user and factor. microb2b users list shows whether a user is enabled and has a password and an authenticator.

Too many failed sign-ins. Try again in N seconds.

After more than 3 failures for one account, or more than 20 from one address, MicroB2B makes the next attempt wait. The wait doubles each time, up to 15 minutes.

• Wait, or restart MicroB2B, which forgets the counts.
• There is no lock and nothing to unlock.
• Behind a reverse proxy, every user may share the proxy’s address. See Reverse proxy.

A user forgot the password or lost the phone

Another user resets them on Access > Users. Or, on the server, run one of these:

microb2b users reset-password <name>   # new password, keeps the authenticator
microb2b users reset-totp <name>       # new authenticator, keeps the password
microb2b users reset <name>            # both

Each prints a new setup link. See Account recovery.

password login is off for <name>

The user signs in at an identity provider, or their password login was turned off. Turn it on with microb2b users password-login <name> on. It prints a setup link when one is needed.

<name> is the last user who can sign in

You tried to disable or delete the last user who can sign in, or turn off their password login. Nobody could sign in afterwards. Create another user first. If you are sure, repeat the command with --force.

You are sent back to the sign-in page again and again

The browser does not keep the session cookie. Check that:

• You use https. Plain http works only for localhost.
• The address in the browser is the same as PUBLIC_URL.
• Your reverse proxy does not remove Set-Cookie headers.
• Every MicroB2B behind one address has the same SESSION_KEY.
• SESSION_TTL is not very short.

A form fails with CSRF token invalid or CSRF token missing

The page’s security token is gone. The page may be older than two hours, MicroB2B restarted, or the browser blocks cookies. Reload the page and submit again.

Two instances under one host name, on different ports, overwrite each other’s cookies. Give each its own host name.

Signing in with an identity provider

The sign-in page has no Sign in with button

No identity provider is enabled, or PUBLIC_URL is not set. Without PUBLIC_URL, Access > Identity providers shows a warning.

The button answers The identity provider cannot be reached. Please try again in a moment.

MicroB2B could not use that provider (HTTP 502). The log line Identity provider cannot be used names the provider and the reason. Common reasons:

• The issuer URL is wrong, or unreachable from the MicroB2B server.
• The issuer URL does not match the provider’s own exactly. A trailing slash counts.
• The client secret could not be opened.

Test from the MicroB2B server: curl <issuer URL>/.well-known/openid-configuration. Password sign-in and other providers keep working. MicroB2B tries the provider again after 30 seconds, or at once when you save it.

The provider says Invalid redirect_uri or “redirect URI mismatch”

Register the exact redirect URI that Access > Identity providers shows at the provider. It is <PUBLIC_URL>/ui/auth/<provider name>/callback. Scheme, host, port and the provider’s name must all match. Renaming the provider or changing PUBLIC_URL changes it.

The login did not start in this browser or took too long

The sign-in cookie did not come back from the provider. Possible causes:

• The browser blocks cookies.
• The address in the browser is not the same as PUBLIC_URL.
• More than 10 minutes passed.
• The sign-in started on another MicroB2B with a different SESSION_KEY.

The identity provider's answer could not be verified

The provider refused the sign-in, or its answer failed the checks. Often the client secret is wrong, or the clocks of the two servers differ. Enter the client secret again on the provider’s page. The log line Login refused gives the reason.

The identity provider could not be reached after signing in at the provider

MicroB2B could not reach the provider to finish the sign-in. The provider is down, or unreachable from the MicroB2B server.

Your account is disabled in MicroB2B.

The MicroB2B user of that identity is disabled. Enable it on Access > Users, or with microb2b users enable <name>.

A provider’s user shows up as alice-2

The name alice was already taken, so MicroB2B added a number. Users are matched to the provider by its own ID for them, never by name. The name is only how MicroB2B shows them.

The REST API

Every API error has a code. It tells you what to fix. See API basics.

401 with MISSING_AUTH_HEADER

The request has no Authorization header. Send Authorization: Bearer <token>. Make a token on Access > Service accounts: create an account, open it and choose Make token. See Service accounts.

401 with INVALID_TOKEN

MicroB2B does not accept the token. The answer never says why, so an attacker learns nothing. The server logs a warning, API request refused, with a reason. Common causes:

• The API token was revoked or mistyped, or its service account is disabled or deleted.
• An identity provider’s token whose issuer matches no enabled provider. The issuer URL must match the token’s exactly.
• A token for another audience than the provider’s API audience.
• A token without the provider’s required API scopes.
• A machine client that is not registered as a federated service account.

401 with TOKEN_EXPIRED

Get a new token. For an identity provider’s token, check that the clocks of the provider and MicroB2B agree. An API token that expired needs a new token from its service account.

400 with INVALID_INPUT

The message is Validation failed. The details name each rejected field. The rules and wording are the same as in the web form.

A web application on another site cannot read API answers

Set ALLOWED_ORIGINS to that site’s origin. See Environment variables.

Live parts of the web UI do not update behind a proxy

The message list, history and Logs page update live. The reverse proxy buffers these streams. Turn off buffering for MicroB2B. See Reverse proxy.