From 101cd5108962288d210c39e6e898a030f22602fc Mon Sep 17 00:00:00 2001 From: Konstantinos Kopanidis Date: Thu, 20 Aug 2026 16:08:32 +0300 Subject: [PATCH] docs(authentication): document email restrictions --- .../content/docs/modules/authentication.mdx | 12 +++++++++++- .../modules/authentication/config.mdx | 6 +++++- .../modules/authentication/configuration.mdx | 18 ++++++++++++++++++ .../modules/authentication/index.mdx | 1 + 4 files changed, 35 insertions(+), 2 deletions(-) diff --git a/apps/web/content/docs/modules/authentication.mdx b/apps/web/content/docs/modules/authentication.mdx index 9be00635..a238f404 100644 --- a/apps/web/content/docs/modules/authentication.mdx +++ b/apps/web/content/docs/modules/authentication.mdx @@ -55,6 +55,7 @@ Apps need sign-up, login, token lifecycle, and optional multi-tenant membership "User profile extension fields", "Anonymous users (optional)", "Account linking (same email across providers)", + "Email restrictions (disposable domains, plus-addressing, allow/block lists)", ]} /> @@ -114,6 +115,15 @@ Patch module config via MCP `patch_config_authentication`: | `twoFa.backUpCodes.enabled` | true | Expose backup-code generate/recover routes | | `magic_link.enabled` | false | Passwordless email login | | `anonymousUsers.enabled` | false | Anonymous user registration | +| `emailRestrictions.enabled` | false | Master switch | +| `emailRestrictions.blockDisposableEmails` | true | Bundled disposable-domain list (when enabled) | +| `emailRestrictions.blockPlusAddressing` | true | Reject any `+` in the local part (`user+tag@domain`) | +| `emailRestrictions.blockedAddresses` | [] | Exact emails | +| `emailRestrictions.allowedAddresses` | [] | Exact allowlist (wins, except reserved `@anonymous.com`) | +| `emailRestrictions.blockedDomains` | [] | Custom domains; suffix match (`evil.com` blocks `mail.evil.com`; not a bare TLD) | +| `emailRestrictions.allowedDomains` | [] | Domain allowlist, suffix match (wins, except reserved `@anonymous.com`) | + +Email restrictions apply when a new or changed email is accepted — local register, change-email, OAuth new accounts and anonymous upgrade, admin create/patch, gRPC `userCreate`, and team invites — not on login, forgot-password, or magic-link for existing users. Blocked addresses return `EMAIL_NOT_ALLOWED` (*This email address is not allowed*). Plus-addressing blocks any `+` in the local part; domain allowlists and blocklists use suffix matching (allowlists win, except reserved `@anonymous.com`). The disposable-domain list is bundled — no runtime network fetch. `@anonymous.com` and its subdomains are always reserved for Conduit anonymous users. Change-email verification links are not rechecked when redeemed. OAuth providers need `clientId` + `clientSecret` per provider under `config.{provider}.enabled`. @@ -149,7 +159,7 @@ Enable with `?modules=authentication` in your MCP server URL. | `post_authentication_users` | Create user (admin) | | `get_authentication_teams` | List teams | | `post_authentication_teams` | Create team | -| `patch_config_authentication` | Token, OAuth, team, and 2FA settings | +| `patch_config_authentication` | Token, OAuth, team, 2FA, and email restriction settings | For operator automation, prefer `cdt_` API tokens over legacy service-account config. See [MCP setup](/docs/getting-started/mcp-setup). diff --git a/documentation/versioned_docs/version-v0.16/modules/authentication/config.mdx b/documentation/versioned_docs/version-v0.16/modules/authentication/config.mdx index 47f8bd73..2754be26 100644 --- a/documentation/versioned_docs/version-v0.16/modules/authentication/config.mdx +++ b/documentation/versioned_docs/version-v0.16/modules/authentication/config.mdx @@ -50,4 +50,8 @@ Account linking is also supported, but only works for accounts using the same em Enable the Magic Link authentication strategy and specify the redirect URI to which the user will be redirected after signing in. -![Magic Link Configuration](/v0.16/modules/authentication/tutorials/enable_magic_link.png) \ No newline at end of file +![Magic Link Configuration](/v0.16/modules/authentication/tutorials/enable_magic_link.png) + +## Email Restrictions + +See [Configuration](./configuration#email-restrictions) for email allow/deny lists and disposable-domain blocking. diff --git a/documentation/versioned_docs/version-v0.16/modules/authentication/configuration.mdx b/documentation/versioned_docs/version-v0.16/modules/authentication/configuration.mdx index 3c2320f4..ee8ffe29 100644 --- a/documentation/versioned_docs/version-v0.16/modules/authentication/configuration.mdx +++ b/documentation/versioned_docs/version-v0.16/modules/authentication/configuration.mdx @@ -72,6 +72,24 @@ When enabled, users authenticating with the same email across different provider | Redirect URI | Where to send users after verification | | Link Expiry | How long magic links remain valid | +## Email Restrictions + +Block or allow email addresses when they are accepted: local registration, change-email, OAuth new accounts and anonymous upgrade, admin create/patch, gRPC `userCreate`, and team invites. Not enforced on login, forgot-password, or magic-link flows for existing users. Off by default. + +| Setting | Default | Description | +|---------|---------|-------------| +| Enabled | `false` | Master switch | +| Block Disposable Emails | `true` | Reject addresses on the bundled disposable-domain list | +| Block Plus Addressing | `true` | Reject `+` in the local part (`user+tag@domain`) | +| Blocked Addresses | `[]` | Exact email denylist | +| Blocked Domains | `[]` | Domain denylist; suffix match (`evil.com` also blocks `mail.evil.com`; not a bare TLD) | +| Allowed Addresses | `[]` | Exact allowlist; overrides blocks, not reserved `@anonymous.com` | +| Allowed Domains | `[]` | Domain allowlist; suffix match; overrides blocks, not reserved `@anonymous.com` | + +Rejected requests return `This email address is not allowed` (`EMAIL_NOT_ALLOWED`). The disposable list is bundled (~8k domains and wildcards); no runtime network fetch. + +`@anonymous.com` and its subdomains are always reserved for Conduit-created anonymous users and cannot be registered or invited. Change-email verification links are not rechecked when redeemed, so a token issued before restrictions were enabled still completes. + ## Token Configuration ### Access Tokens diff --git a/documentation/versioned_docs/version-v0.16/modules/authentication/index.mdx b/documentation/versioned_docs/version-v0.16/modules/authentication/index.mdx index 3b753b31..981a3094 100644 --- a/documentation/versioned_docs/version-v0.16/modules/authentication/index.mdx +++ b/documentation/versioned_docs/version-v0.16/modules/authentication/index.mdx @@ -11,6 +11,7 @@ The Authentication module provides user identity management for your application ## Features - **Local Authentication** - Email/password with optional verification +- **Email Restrictions** - Block disposable domains, plus-addressing, or custom deny/allow lists when emails are accepted - **OAuth Providers** - 13+ social login integrations - **Two-Factor Auth** - Phone OTP and authenticator app support - **Magic Links** - Passwordless login via email