mddb / docs

Appearance

Authentication ​

mddb accepts email and password accounts on every server. Google, GitHub, and Microsoft sign-in appear only after you configure their OAuth clients.

Anyone who reaches the server can register ​

The sign-in page offers registration with a name, an email address, and a password. Password registration stops at the user quota on /settings/server, 50 users by default. Limit who reaches mddb with Tailscale or allow_origins.

With SMTP configured, mddb sends a verification link to new addresses.

Configure an OAuth provider ​

Each provider takes a client ID and a client secret in config.toml. Set both or neither; a lone value stops startup. Restart mddb after the change.

toml
[oauth.google]
client_id = "your-client-id"
client_secret = "your-client-secret"

Each provider's redirect URI is <base_url>/api/v1/auth/oauth/<provider>/callback, with the provider google, github, or microsoft. Set server.base_url to your public origin first. For example, https://mddb.example.com/api/v1/auth/oauth/github/callback.

Google ​

  1. Create a project in the Google Cloud console.
  2. Configure the consent screen on the branding page.
  3. Create an OAuth client for a Web application on the clients page.
  4. Add the Google redirect URI.
  5. Set oauth.google.client_id and oauth.google.client_secret.

Google accepts http://localhost redirect URIs, so Google sign-in also works on a local-only server.

GitHub ​

  1. Open OAuth Apps in GitHub developer settings and create an app.
  2. Set Authorization callback URL to the GitHub redirect URI.
  3. Generate a client secret.
  4. Set oauth.github.client_id and oauth.github.client_secret.

mddb uses the account's primary email address when GitHub verified it, else another verified address.

Microsoft ​

Microsoft sign-in uses Microsoft Entra ID. mddb accepts work, school, and personal Microsoft accounts.

  1. Register an application.
  2. Under supported account types, select Accounts in any organizational directory and personal Microsoft accounts.
  3. Add a Web redirect URI with the Microsoft redirect URI.
  4. Under Certificates & secrets, create a client secret. Copy its Value immediately; Microsoft shows it only once. The Secret ID is not the secret.
  5. Set oauth.microsoft.client_id to the Application (client) ID from the overview page, and oauth.microsoft.client_secret to the secret value.
  6. Under Branding, set the terms of service URL to <base_url>/terms and the privacy statement URL to <base_url>/privacy.
  7. Under Token configuration, add the optional ID token claims email and xms_edov. When asked, turn on the Microsoft Graph email permission.

mddb trusts a Microsoft email address only when the ID token's xms_edov claim is true: the domain owner verified it. Personal accounts and tenant-verified domains qualify. The Graph mail and userPrincipalName values are not proof, because a tenant admin can set them to any address. Microsoft explains this in Migrate away from email claims.

Publisher verification requires /.well-known/microsoft-identity-association.json on your domain. mddb does not serve this file; serve it from your reverse proxy.

Provider sign-in needs a verified email ​

The first sign-in with a provider matches its verified email address:

  • No account holds the address: mddb creates an account.
  • A verified account holds the address: mddb links the provider to it.
  • An unverified password account holds the address: mddb refuses. Verify that account's email, or change it, then retry.
  • The provider reports no verified address: mddb refuses with EMAIL_NOT_VERIFIED. Sign in another way, then link the provider.

After the first sign-in, the provider identity signs in directly.

Open Settings, then Personal. Linked Accounts connects or disconnects each configured provider. The same page adds or changes a password and changes your email. mddb keeps at least one sign-in method on each account.

Sign in from another device ​

The sign-in page has Sign in with another device. It shows a 12-character code and the address <base_url>/device. On a device where you are signed in, open that address, check the requesting browser's details, and approve the code. The new browser receives a normal session with your permissions.

Use this flow when a provider refuses to sign in inside an app, such as the Go Mode Android shell. Settings → Personal lists your sessions and signs them out.