Identity providers (single sign-on)

This page explains how people sign in to MicroB2B with an identity provider you already use, such as Keycloak or JumpCloud. MicroB2B supports any provider that speaks OpenID Connect (OIDC), the common single sign-on standard.

How it works

You register MicroB2B at your identity provider, and you add the provider in MicroB2B. Then:

The login page shows a Sign in with <display name> button for the provider, beside the password form.
A user clicks it, signs in at the provider and comes back signed in to MicroB2B.
Who may sign in is decided at the provider. Assign the MicroB2B application to the right users or groups there.

You can add any number of providers. Each has its own button and its own users. Password login keeps working beside them.

Users of a provider

The first time a person signs in at a provider, MicroB2B creates a user for them:

The user is enabled and has password login off.
The name comes from the preferred_username claim, else the part of the e-mail before the @, else user. Characters a user name cannot hold become -. If the name is taken, MicroB2B adds -2, -3 and so on.
The display name comes from name, else preferred_username, else the e-mail address.

Later sign-ins find the same user by the provider and the person’s subject (sub), a fixed id at the provider. MicroB2B never matches by name or e-mail. So a name at the provider cannot take over an existing MicroB2B user. The same person at two providers is two users.

A user disabled in MicroB2B is refused after signing in at the provider. They see “Your account is disabled in MicroB2B.”

MicroB2B asks a provider’s users for no second factor. The provider handles that.

MicroB2B stores no password, refresh token or session of the provider. It only keeps the user record.

Before you start

PUBLIC_URL must be set. MicroB2B builds the provider’s redirect URI from it. Without it, no provider appears on the login page. See required settings.
SECRETS_KEY must be set. MicroB2B encrypts the client secret with it. See secrets.
You need a user who can sign in with a password, to add the first provider. Keep that user as your break-glass account. See users.

Adding a provider

Choose a name for the provider in MicroB2B, for example keycloak. The redirect URI is then <PUBLIC_URL>/ui/auth/<name>/callback, for example https://b2b.example.com/ui/auth/keycloak/callback.
At the provider, register MicroB2B as a confidential client (a client with a secret). Use the authorization code flow with PKCE method S256, and the redirect URI from step 1. Copy the client ID and client secret.
In MicroB2B, go to Access > Identity providers and click New identity provider.
Fill in the name, display name, issuer URL, client ID and client secret. Save.
Sign out and click the new Sign in with <display name> button. Your first sign-in creates your user.

The provider list shows each provider’s redirect URI, ready to copy.

Step-by-step examples: Keycloak and JumpCloud.

You can also add a provider over the REST API:

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"keycloak","display_name":"Company login","enabled":true,
       "issuer_url":"https://keycloak.example.com/realms/b2b",
       "client_id":"microb2b","client_secret":"..."}' \
  https://b2b.example.com/api/v1/oidc-providers

Provider settings

Setting	What it does	Default
Name	Lower case letters, digits, `_` and `-`. Part of the redirect URI. If you change it, register the new redirect URI at the provider.	required
Display Name	The button text: Sign in with <display name>.	required
Enabled	A disabled provider shows no button and its tokens are refused. Its users stay.	on
Offer sign-in	Shows the button on the login page. Turn it off for a provider that only issues tokens to service accounts.	on
Issuer URL	The provider’s issuer, exactly as its discovery document says, trailing slash included. Must be `https` (`http` only on `localhost`). Each issuer can be used by one provider only.	required
Client ID	MicroB2B’s client ID at the provider.	needed for sign-in
Client Secret	The client secret. Never shown again. Leave it empty to keep the stored one. You must enter it again when you change the issuer URL.	needed for sign-in
Sign-in scopes	Scopes requested at sign-in, separated by spaces. Must include `openid`.	`openid profile email`
API Audience	The audience (`aud`) a REST API access token must carry.	the client ID
Required API scopes	Scopes every REST API access token must carry, separated by spaces.	none
Accept tokens without an audience	Accepts an API token without `aud`, but only from a registered federated service account.	off

To find the issuer URL, open <issuer>/.well-known/openid-configuration in a browser. The issuer value there must match exactly.

The last three settings are about the REST API. See service accounts.

Changes take effect at the next sign-in

You do not need to restart MicroB2B. It reads the enabled providers each time someone signs in. After you save a provider, MicroB2B contacts it again at the next use.

When a provider cannot be reached

A broken provider never stops MicroB2B. This covers a provider that is down, an issuer URL that does not match, or a provider without PKCE S256 support. MicroB2B then:

logs a warning Identity provider cannot be used, naming the provider,
answers its button with 502 “The identity provider cannot be reached. Please try again in a moment.”,
keeps password login and the other providers working.

It tries the provider again 30 seconds later, or as soon as you save it.

Deleting a provider

Open the provider and use the danger zone at the bottom of its page. Its users stay in MicroB2B, but they cannot sign in at it any more. Give them password login, or delete them on Access > Users.

Creating, changing and deleting providers are recorded in the audit log. The client secret is never recorded.

Several providers

Providers work side by side. Each has its own button, redirect URI and users. Examples are staff at one provider and a partner portal at another, or a move from one provider to the next.

Session length and logout

A session that began at a provider is a normal MicroB2B session. It lasts SESSION_TTL (8 hours by default). Choose a length that suits your risk. See signing in.

Disabling a person at the provider does not end their MicroB2B session. It ends when it expires. To end it at once, disable the user in MicroB2B or click Sign out everywhere on their page.

Logout ends only the MicroB2B session. The session at the provider stays. While it lasts, clicking Sign in with signs the user in again without asking. To end it, sign out at the provider.

Access tokens for the REST API

Scripts and other systems can call the REST API with an access token from your provider. The token must be a JWT (opaque tokens are not supported). Send it as Authorization: Bearer <access token>.

MicroB2B checks the token against the provider’s published keys. It checks the issuer, the audience (the provider’s API Audience), the expiry and the required scopes. The caller is then either:

the MicroB2B user of that person at the provider, or
a federated service account registered for the token’s subject.

A valid token of any other subject is refused. Register machines as service accounts first.

A refused request gets 401. The codes and what to do about them are in service accounts and troubleshooting sign-in.

Behind a reverse proxy

MicroB2B builds the redirect URIs from PUBLIC_URL only. It ignores Host and X-Forwarded-* headers. Keep the redirect URI registered at each provider in step with PUBLIC_URL. A provider rejects an unregistered redirect URI before MicroB2B sees the request. See reverse proxy.

Account recovery Keycloak