Skip to content

Self-service sign-up

By default a server has no self-service sign-up: the first Owner comes from DX_BOOTSTRAP_OWNER_EMAIL or python -m extractit.identity.admin grant-owner, and everybody else joins by invitation. That is the right setting for a self-hosted install.

With DX_SIGNUP=open (the managed service, app.extractit.dev) anyone can create an account at /signup with:

  • Continue with Google (OpenID Connect);
  • Continue with Microsoft (Microsoft Entra ID, work, school and personal accounts);
  • Email me a sign-in link (a single-use link valid for 15 minutes).

The first sign-in of a person whose email is verified creates their organization (named after the email, renamed later in Settings or with PATCH /v1/organization) with its default project, makes them its Owner and fires identity.owner_verified (the welcome credits of the commercial edition). If somebody already invited that email, the person joins that organization instead. The web then opens Home, where the onboarding starts.

1. Google: an OAuth client

  1. In the Google Cloud console, pick (or create) a project.
  2. APIs & Services → OAuth consent screen: user type External, app name, support email, the authorized domain extractit.dev, and the scopes openid, email and profile (no other scope is needed). Publish the app when it is ready (while it is in Testing only test users can sign in).
  3. APIs & Services → Credentials → Create credentials → OAuth client ID, type Web application. Authorized redirect URI: https://app.extractit.dev/auth/callback (in general DX_PUBLIC_URL + /auth/callback). No JavaScript origin is needed.
  4. Copy the client ID and the client secret into DX_OIDC_ISSUERS (below).

Google's email_verified claim is trusted as is.

2. Microsoft: an app registration in Entra ID

  1. In the Microsoft Entra admin center: Identity → Applications → App registrations → New registration.
  2. Supported account types: Accounts in any organizational directory and personal Microsoft accounts ("tenant": "common"), or Accounts in any organizational directory only ("tenant": "organizations").
  3. Redirect URI: platform Web, https://app.extractit.dev/auth/callback.
  4. Certificates & secrets → New client secret: copy its value (it is shown once) and note its expiry date: sign-in with Microsoft stops working the day it expires.
  5. API permissions: Microsoft Graph, delegated openid, email and profile (the default User.Read can stay or go).
  6. Token configuration → Add optional claim → ID: tick xms_edov (and email). Without it every Microsoft email counts as unverified: Entra lets a tenant administrator put any address in email, so the claim alone proves nothing (the nOAuth account-takeover pattern). xms_edov=true says the domain owner verified it. A person whose Microsoft email arrives unverified gets an account without organization and is asked to confirm the email with a sign-in link (same browser) before the organization is created.
  7. Copy the Application (client) ID from Overview.

How multi-tenant tokens are checked

The configured issuer (https://login.microsoftonline.com/common/v2.0) is only where discovery lives. Each token is issued by the user's own tenant: the server accepts it only when its tid claim is a tenant id (a lower-case GUID; listed in allowed_tenants when you set it) and its iss is exactly https://login.microsoftonline.com/{tid}/v2.0 with that tid. A token of any other issuer is 401 invalid-token. The account is keyed by that tenant issuer plus sub (the OIDC key: stable and unique per user for this application).

3. Mail: an SMTP account

Sign-in links (and invitations) go out by SMTP. Any provider works; providers with servers in the EU include Brevo, Mailjet and Scaleway Transactional Email (France), Amazon SES in eu-west-1/eu-central-1 and Mailgun or Postmark with their EU region. Verify the sending domain at the provider (SPF, DKIM and a DMARC policy) so links do not land in spam.

DX_SMTP_URL=smtps://USER:[email protected]:465     # or smtp://…:587?starttls=true
DX_MAIL_FROM="ExtractIt <[email protected]>"

4. Configuration

DX_PUBLIC_URL=https://app.extractit.dev
DX_SIGNUP=open
DX_TERMS_VERSION=2026-11-18
DX_OIDC_ISSUERS='[
  {"id": "google", "type": "google",
   "client_id": "…apps.googleusercontent.com", "client_secret": "…"},
  {"id": "microsoft", "type": "microsoft", "tenant": "common",
   "client_id": "…", "client_secret": "…"}
]'
Variable Default Meaning
DX_SIGNUP closed open: the first verified sign-in of a new person creates an organization. closed: as before, invitations only.
DX_TERMS_VERSION — (required with open) Version of the terms a person accepts by signing up; stored in the auth.signup audit event. Change it when the terms change.
DX_TERMS_URL, DX_PRIVACY_URL the pages of extractit.dev Links of the sign-up screen («By continuing you agree to the Terms and the Privacy Policy»).
DX_EMAIL_LINK on when DX_SMTP_URL is set Sign-in links by email. Refused in production without DX_SMTP_URL.
DX_EMAIL_LINK_LIMIT_EMAIL 5 per hour Links per email; beyond it the answer is the same 202 but no mail is sent.
DX_EMAIL_LINK_LIMIT_IP 20 per hour Links per client address (429).
DX_EMAIL_LINK_LIMIT_GLOBAL 60 per minute Links for the whole server (429).
DX_SMTP_URL, DX_MAIL_FROM — Mail (above).
DX_OIDC_ISSUERS [] Providers. type google or microsoft fills issuer, issuer_template, email_verified_claim and link_by_email; each can also be set by hand, plus allowed_tenants (Microsoft tenant ids) and name.

The sign-in buttons appear only for what is configured: no Google entry, no Google button; DX_EMAIL_LINK off, no email form. The per-email, per-IP and global limits all apply per replica, like the API's rate limits. To enforce a ceiling across the service, apply a rate limit at ingress that covers all replicas or use a shared limiter.

One person, one account

A person who signs in with Google, then with Microsoft, then with a sign-in link reaches the same account when the email is the same, but only when both sides are verified by a provider trusted to join accounts (link_by_email: Google, Microsoft with xms_edov, sign-in links). An unverified email never joins anything, a generic OIDC issuer does not join unless you set "link_by_email": true, and an organization's own SSO (commercial edition) never does. Each join is audited as auth.identity_linked.

  • POST /auth/email/start {"email", "redirect"?, "locale"?} always answers 202 (the same body whether the email has an account or not) and mails the link after the response. A new link invalidates the previous one.
  • The link opens a confirmation page («Sign in as …»). Opening it (a GET, which is what mail scanners do) never uses it; only the page's POST /auth/email/confirm does, once, and it needs the application's Origin. It works from any device: the link proves the mailbox, not the browser.
  • Exception: verifying an account whose provider email is unverified joins the link to that account only in the browser of that session. A link opened elsewhere signs in an account of its own, so somebody who claims your email at a provider cannot capture your mailbox by sending you a link.
  • The token is 32 random bytes and the database keeps only its HMAC. Application logs mask the email (a***@example.com), and the bundled web proxy omits query strings and Referer from access logs. The confirmation page sends Cache-Control: no-store and Referrer-Policy: no-referrer.

Proxies and ingress

Configure every external proxy, CDN and ingress to log the request path without the query string or Referer. Sign-in tokens pass through /login/link and /auth/email/link, and OIDC codes and state pass through /auth/callback. For Nginx use $uri or the path portion of $request_uri. Omit $request, $args, $http_referer, and the full $request_uri. Apply the same rules to error logs, request sampling and traces that capture the request or redirect URL. Keep the confirmation page's cache and referrer headers when serving it through another proxy.

Audit

Event When Where
auth.signup an organization is created by a sign-up the new organization; metadata has method, terms_version and terms_accepted_at
auth.email_link_sent a link is mailed to an email with an account the account's organization (an unknown email has none: only the masked log)
auth.identity_linked a new sign-in method joins an existing account the account's organization

The accepted terms are an audit event, not a column: the audit log is append-only and hash-chained, which is the evidence a consent record needs (who, which version, when).