Required settings

MicroB2B will not start without three settings: PUBLIC_URL, SESSION_KEY and SECRETS_KEY. This page explains each one, how to generate the keys, and how to create the first user.

The three settings

Set them as environment variables, for example in /etc/microb2b.env (see install). For each key, set either the variable itself or its _FILE variant, never both. A _FILE variable names a file that holds the key. That works well with Docker or Kubernetes secrets.

PUBLIC_URL

PUBLIC_URL is the address of the web UI as your users see it, for example https://b2b.example.com.

• It must use https. The only exceptions are localhost, 127.0.0.1 and ::1, for a trial on your own machine.
• It has no path. MicroB2B cannot run under a path such as https://example.com/b2b.
• It must match the address your reverse proxy serves.

MicroB2B uses it to build setup links for new users and the sign-in addresses for identity providers.

SESSION_KEY

SESSION_KEY protects the cookies that keep people signed in. It is base64 or hex of at least 32 random bytes. Generate one:

openssl rand -base64 32

Keep it secret and keep it the same. If you change it, everybody is signed out.

A related, optional setting is SESSION_TTL: how long a sign-in lasts. The default is 8h. You can set 5 minutes (5m) to 72 hours (72h).

SECRETS_KEY

SECRETS_KEY is the master key. MicroB2B uses it to encrypt everything secret it stores: the private keys of your certificates, passwords for partners, webhook addresses and the users’ authenticator secrets. It is base64 or hex of exactly 32 random bytes. Generate one:

openssl rand -base64 32

Keep a copy of this key in a safe place, apart from the database. If you lose it, every private key and every stored secret is lost with it. A backup of the database cannot bring them back. See secrets for how to keep it safe and how to replace it.

The first start ties the database to this key. After that, MicroB2B refuses to start with any other key.

An example

mkdir -p /etc/microb2b/secrets
openssl rand -base64 32 > /etc/microb2b/secrets/session_key
openssl rand -base64 32 > /etc/microb2b/secrets/secrets_key
chmod 600 /etc/microb2b/secrets/*

Then, in /etc/microb2b.env:

PUBLIC_URL=https://b2b.example.com
SESSION_KEY_FILE=/etc/microb2b/secrets/session_key
SECRETS_KEY_FILE=/etc/microb2b/secrets/secrets_key
DB_URL=file:/var/lib/microb2b/microb2b.db

Make sure the user MicroB2B runs as can read the key files.

If a setting is missing or wrong, MicroB2B stops and names every variable that has a problem. It never prints the key itself.

Create the first user

There is no default user and no default password. You create the first user on the command line, on the server. You can do this before or after you start MicroB2B. The command needs the same database settings as MicroB2B:

PUBLIC_URL=https://b2b.example.com DB_URL=file:/var/lib/microb2b/microb2b.db \
  microb2b users create admin --display-name "Ada Admin"

The command prints a setup link. It is valid for 24 hours and works once.

1. Open the setup link in your browser.
2. Choose a password of at least 12 characters.
3. Scan the QR code with an authenticator app on your phone, and type in a code from the app.
4. Save the recovery codes it shows you. You see them only once.
5. Sign in.

From then on, you create other users in the web UI under Access > Users. See users.

Optional settings

Other settings have working defaults. The most common ones are:

• DB_TYPE and DB_URL: which database to use.
• HTTP_PORT: the port of the web UI, default 8080.
• AUDIT_KEY: makes the audit log tamper-evident. Recommended.

The environment variables page lists them all.