Emailed magic link

Emailed magic link#

Sign people in with a single-use link sent to their address. There is no external provider: this site mints and checks the token itself.

Note

Verified against the demo stack on 2026-09-05.

1. Check the site can send mail#

This is the step that gets skipped, and it fails in a way that reads as a bug in the login flow.

The site's mail settings must be filled in—Mail control panel, SMTP host and "From" address. plone.api.portal.send_email refuses to run at all while they are empty, so the magic-link endpoint fails before any mail is attempted, and the error says nothing about mail.

Send a test message from the Mail control panel before continuing.

2. Add the provider#

Open the Identity providers control panel.
Add a provider and choose Email (email).
On the Settings tab:

Field

Default

What it does

Title

what the form is labelled

Token lifetime (seconds)

900

how long a link stays usable

Rate limit per hour

5

sends allowed per address and per IP each hour
Set Show on the login screen on, so the form appears.
Save.

Important

The magic-link form appears on /login only when the email provider is shown on the login screen, not merely enabled. The login page builds itself from the providers @login-providers returns, and that endpoint filters on exactly this flag.

An email provider that is enabled and hidden still verifies addresses and can still be linked to an account. It just has no button.

There is no client ID and no secret. Nothing is registered anywhere.

Verify#

The audit log has a magic-link-sent entry, then magic-link-confirmed.
Following the same link twice fails the second time.
/identities lists an identity for the address.

What the token guarantees#


Lifetime	at most 15 minutes, whatever you configure
Reuse	burned server side after one use
Rate limit	per address and per IP
Enumeration	the send endpoint answers identically whether or not the address has an account

The last one is the reason the endpoint never says "no such user": that answer would turn the login page into a way to test which addresses have accounts here.

Known quirks#

Configured lifetime is a ceiling, not a promise. Setting the token lifetime above 900 seconds does not extend it past 15 minutes.
There are no account or group settings. IEmailSettings carries only the two fields above. No trust switch, no link-by-email switch, no account-creation switch, no group claim. An email provider always creates accounts.
Its verification is this site's own. An address that answered a link from this site is verified by this site, which is the strongest form of the claim this package has—so there is nothing to decide whether to trust.

Field	Default	What it does
Title		what the form is labelled
Token lifetime (seconds)	`900`	how long a link stays usable
Rate limit per hour	`5`	sends allowed per address and per IP each hour