Magic link
The magiclink plugin signs a user in with a link sent to their email address. There is no password. The user asks for a link, opens it, and your page hands the link's token back to Behemoth, which creates the session.
The plugin does not send email. It hands the link to the mail sender you give Behemoth at Boot.
How it works #
| Step | Who | What happens |
|---|---|---|
| 1 | client | posts an email to POST /sign-in/magic-link |
| 2 | plugin | finds the user, issues a single-use token, and hands the link to your mail sender |
| 3 | you | send the message |
| 4 | user | opens the link, which is a page of your application: https://app.example.com/auth/magic?token=... |
| 5 | your page | posts the token to POST /magic-link/verify |
| 6 | plugin | consumes the token and creates a session |
The link points at your page and not at Behemoth, and step 5 is a POST. Mail scanners and link previews open the links in a message. If opening the link were enough to sign in, the scanner would use it up before the user got to it.
Setup #
Pass the plugin to Prepare. It uses the core users, sessions, and tokens tables and has none of its own.
import "github.com/go-behemoth/behemoth/plugins/magiclink"
plugin := magiclink.New(magiclink.Options{
LinkURL: "https://app.example.com/auth/magic",
})
app, err := engine.Prepare([]core.Plugin{plugin}, engine.PrepareConfig{})
// ...
ac, err := engine.Boot(ctx, app, db, engine.BootConfig{
Router: httpapi.RouterConfig{
TrustedOrigins: []string{"https://app.example.com"},
},
Mail: core.MailConfig{
Sender: core.MailSenderFunc(
func(ctx context.Context, msg core.MailMessage) error {
return mailQueue.Enqueue(
ctx,
msg.To,
"Your sign-in link",
msg.URL,
)
},
),
},
// ...
})The plugin's name is magiclink (magiclink.PluginName). It works next to the emailpassword plugin or without it.
examples/init runs the plugin end to end: a sender that prints the link (mail.go) and the page the link opens (pages.go).
Options #
| Field | Default | Meaning |
|---|---|---|
WaitForSend | false | Whether the request waits for the mail sender. See Send the link. |
LinkURL | required | The page of your application the link points to. Absolute, http or https. The plugin adds the token as the token query parameter and keeps any query the URL already has. |
TTL | 15 minutes | How long a link works. TokenConfig.TTLOverrides[core.TokenKindMagicLink] takes precedence. |
RequestLimit | 5 per 15 minutes | Link requests allowed per email. See Rate limits. |
LeaveEmailUnverified | false | Set it to stop a verified link from marking the email as verified. See What a link does. |
A missing mail sender (BootConfig.Mail.Sender), a LinkURL that is not an absolute URL, and a negative TTL are configuration errors from Boot.
Send the link #
The link is handed to your mail sender as a core.MailMessage with Kind set to core.MailMagicLink. Mail describes the message and the sender.
Metadata on the message is whatever the request carried under metadata. The plugin passes it through without reading or storing it. Use it for what your message needs: a locale, a template name, the name of the device that asked.
Sending behaves as follows:
- From the route,
Metadatais what the client sent. Treat it like any other request input. A handler onauth.magicLink.beforeRequestcan set or remove entries before the sender sees them. - By default the request does not wait for your sender. It returns once the message is queued. A send that fails later is logged by the mailer. The link stays valid until it expires or the user's next request replaces it.
- With
WaitForSendthe request waits. A returned error revokes the link. The route still answers200(see below), and the error is logged at Error level under themagiclinkcomponent. The sender is only called for an email that has an account, so a slow sender makes that request slower than one for an unknown email, and the difference shows which addresses are registered. Choose this when your sender only puts the message on a queue.
Routes #
The routes sit directly under the router's base path.
| Route | Body | Result |
|---|---|---|
POST /sign-in/magic-link | email, and optionally redirect_url and metadata (an object) | 200 with {"status": "ok"} |
POST /magic-link/verify | token | 200 with {"user": {...}, "redirect_url": "..."}, or {"status": "requires_second_factor", "redirect_url": "..."} when a second factor is pending. It is the body every sign-in answers with, plus the redirect, and the session token arrives by the configured delivery; see Sessions. |
The request route answers the same whether or not the email has an account. An unknown email, a link that could not be issued, and a failed send are all a 200 with the same body, so the response does not show which addresses are registered. The plugin does not create accounts: an unknown email gets no link.
Error responses #
| Route | When | Status | Code |
|---|---|---|---|
| both | the body is not valid JSON | 400 | request_validation_error |
| request | email is missing or not an email address | 400 | email_invalid_input |
| request | redirect_url is not allowed | 400 | redirect_url_invalid_input |
| request | metadata is not an object | 400 | metadata_invalid_input |
| verify | token is missing | 400 | token_invalid_input |
| verify | the link is unknown, expired, already used, or replaced by a newer one | 401 | invalid_magic_link |
| both | too many requests | 429 with Retry-After | rate_limited |
| both | a hook handler rejected the request with a typed error | the error's status | the error's code |
Verify gives one answer for every link it refuses, so the response does not tell an expired link from one that never existed.
The redirect URL #
A request can say where the user should land after signing in. The plugin checks the URL when the link is requested, keeps it with the token, and returns it from verify. Your page does the redirect.
Two forms are accepted:
- a path on your own site, starting with one
/:/dashboard?tab=1 - an absolute
httporhttpsURL whose origin is inRouterConfig.TrustedOrigins
Anything else is a 400, including //other.example.com and a URL with credentials in it. An origin is a scheme, a host, and an optional port, and it is matched exactly: https://app.example.com does not cover http://app.example.com or https://www.app.example.com. List each one. An entry that is not an origin is a configuration error from Boot.
Without the check, anyone could mail your users a real sign-in link that ends on a site of their choosing.
What a link does #
A link has these properties:
- It works once. The token is consumed at verify, also when a later step refuses the sign-in (a second-factor handler's rejection, a session limit). The user asks for a new link.
- A new link replaces the old one. A user has one live link. Requesting again revokes the earlier ones.
- It marks the email as verified. Following the link shows the user controls the address, so
EmailVerifiedis set on a user who did not have it. SetLeaveEmailUnverifiedif verified should only mean that your own verification passed. The link then signs the user in and leaves the flag as it was. With the email verification plugin'sRequireVerified, such a sign-in is refused until the address is verified. - It is tied to the address it was sent to. If the user's email changes before the link is used, the link is refused.
- It goes with the user.
Store.DeleteUserremoves a user's links.
Call the flows from code #
Both flows are exported for a CLI, a job, or another plugin.
result, err := plugin.RequestLink(ctx, magiclink.LinkRequest{
Email: "ada@example.com",
RedirectURL: "/dashboard",
Metadata: behemoth.M{"locale": "fr"},
})
signIn, err := plugin.Verify(ctx, rawToken)
// signIn.User, signIn.Session, signIn.RawToken, signIn.RedirectURLThe flows behave as follows:
RequestLinkreports what the route hides. It returnsmagiclink.ErrNoAccountfor an unknown email (check witherrors.Is), and the error of a failed issue or send.Verifyreturns the raw session token and delivers nothing. From a route of your own, handsignIn.SignInResulttohttpapi.WriteSignIn, which is what the plugin's route does.- Pass the context of the request being handled when there is one, so sessions record the client's address and handlers get the request.
- Called before
Boot, both return a configuration error.
Hooks #
Verifying a link is a sign-in. It fires the same points as a password sign-in, so a handler written for one sees the other:
| Point | What the handler gets |
|---|---|
auth.signIn.before | payload method ("magiclink") and, when the token names one, email. Veto only. The token is not in the payload. |
auth.signIn.credentialsVerified | HookValueUserID, and HookValueFactor with the value email. Set HookValueRequireStepUp to make the session pending. |
auth.signIn.after | a *core.SignInResult with Method set to "magiclink" |
auth.signIn.failed | codes invalid_magic_link, user_not_found, email_changed, rejected_by_hook |
The plugin declares three points of its own around a link request:
| Point | Phase | What the handler gets |
|---|---|---|
auth.magicLink.beforeRequest (magiclink.HookRequestBefore) | before | payload email, redirect_url, metadata. The returned payload becomes the request's input. |
auth.magicLink.afterRequest (magiclink.HookRequestAfter) | after | a *magiclink.LinkResult: user id, email, token id, expiry. Not the token. |
auth.magicLink.requestFailed (magiclink.HookRequestFailed) | failed | codes user_not_found, issue_failed, send_failed, rejected_by_hook |
The after and failed points are audited under their point names. A captcha check belongs on auth.magicLink.beforeRequest: read the answer from payload["metadata"] and return an error to refuse.
Issuing and consuming the token also fire the token manager's points (token.beforeIssue, token.afterIssue, token.consumed, token.failed) with the kind magic_link.
Rate limits #
The plugin declares two rules.
| Rule | Limits | Default |
|---|---|---|
magiclink.RuleRequestAddress | link requests per client address | 10 a minute |
magiclink.RuleRequestEmail | link requests per email | Options.RequestLimit, 5 per 15 minutes |
Verifying a link is a sign-in, which core limits to 10 attempts a minute per client address and sign-in method (engine.RuleSignInAddress). The magic link method counts apart from password sign-ins. Change a limit, or turn a rule off, by its name with RateLimitConfig; see Hooks.
Both rules are attached to auth.magicLink.beforeRequest and not to the route, so they also hold for RequestLink called from code. The rule per email keeps one address from being sent link after link. It counts requests for unknown emails too, so a 429 does not show whether the address has an account.
Limits #
The plugin has these limits:
- No sign-up by link. An unknown email gets no link and no account.
- No wildcards in trusted origins. List each origin.