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
- In the Google Cloud console, pick (or create) a project.
- APIs & Services → OAuth consent screen: user type External, app name, support email,
the authorized domain
extractit.dev, and the scopesopenid,emailandprofile(no other scope is needed). Publish the app when it is ready (while it is in Testing only test users can sign in). - APIs & Services → Credentials → Create credentials → OAuth client ID, type Web
application. Authorized redirect URI:
https://app.extractit.dev/auth/callback(in generalDX_PUBLIC_URL+/auth/callback). No JavaScript origin is needed. - 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
- In the Microsoft Entra admin center: Identity → Applications → App registrations → New registration.
- Supported account types: Accounts in any organizational directory and personal Microsoft
accounts (
"tenant": "common"), or Accounts in any organizational directory only ("tenant": "organizations"). - Redirect URI: platform Web,
https://app.extractit.dev/auth/callback. - 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.
- API permissions: Microsoft Graph, delegated
openid,emailandprofile(the defaultUser.Readcan stay or go). - Token configuration → Add optional claim → ID: tick
xms_edov(andemail). Without it every Microsoft email counts as unverified: Entra lets a tenant administrator put any address inemail, so the claim alone proves nothing (the nOAuth account-takeover pattern).xms_edov=truesays 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. - 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.
Sign-in links
POST /auth/email/start {"email", "redirect"?, "locale"?}always answers202(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'sPOST /auth/email/confirmdoes, once, and it needs the application'sOrigin. 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 andRefererfrom access logs. The confirmation page sendsCache-Control: no-storeandReferrer-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).