Skip to main content

Extension points

Take over the post-verification flow​

Rebind the authenticator contract:

use EmailMagicLink\Contracts\MagicLinkAuthenticator;

$this->app->bind(MagicLinkAuthenticator::class, MyAuthenticator::class);

The contract returns a response, so it — not an event — is where login-versus-two-factor is decided.

React to events​

Events are observability only — they must not drive flow control:

  • MagicLinkRequested($user, $channel, $request) — the request endpoint issued a link or code for a known user. The Mint API does not fire it.
  • MagicLinkVerified($user, $request) — a token was verified and consumed, before the authenticator runs.
  • MagicLinkAuthenticated($user, $guard, $request) — the user was actually logged in (fires only on a completed login, never for a two-factor handoff). A two-factor user's login completes inside Fortify, which fires Laravel's Login but not this event, so an audit log listens for TwoFactorChallengeRequired and Login as well.
  • MagicLinkConsumptionFailed($reason, $request) — a consume attempt failed; $reason is a ClaimFailure, so you can log every failure and alert specifically on LockedOut (a brute-force lockout) or repeated InvalidCode.
  • TwoFactorChallengeRequired($user, $request) (fired by the bridge) — a user whose two-factor authentication Fortify counts as enabled is being handed to the challenge.

Each carries the Request, so a listener can record the IP address and user agent. The response stays generic and enumeration-resistant regardless of which failure reason fired. Successful logins also fire Laravel's own Illuminate\Auth\Events\Login.

The full payloads and the ClaimFailure cases are in the event reference.

Swap collaborators​

Eleven config keys each take a class of yours:

KeyContractWhat you control
notification— (extend MagicLinkNotification)Branding, channels, and copy of the delivered mail
mail_identityMailIdentityThe application's name and the greeting in the sign-in mail, per account
user_lookupUserLookupHow a submitted email resolves to a user
eligibilitySignInEligibilityWhether an account may be handed a session at all
guard_resolverGuardResolverWhich guard a request signs in to, instead of its guard field
token_storeTokenStorePersistence, hashing, and the atomic claim
captchaCaptchaGuardA pre-issue challenge
invalid_response.viaInvalidLinkResponderThe response to an invalid or expired link
ui.script_nonceScriptNonceThe CSP nonce on every tag the bundled screens emit
invitations.storeInvitationStorePersistence, hashing, supersession and the atomic claim of invitations
invitations.handlerInvitationHandlerWhat accepting an invitation means — required when invitations are on

notification is the one entry that is not a contract: it takes a class extending MagicLinkNotification, and a class that does not is ignored without raising.

What each contract guarantees is in the contract reference.

Gate requests with a CAPTCHA​

Point the captcha config at a class implementing EmailMagicLink\Contracts\CaptchaGuard:

final class TurnstileGuard implements CaptchaGuard
{
public function passes(Request $request): bool
{
// Verify the challenge token (e.g. cf-turnstile-response) with the provider.
return Http::asForm()->post('https://challenges.cloudflare.com/turnstile/v0/siteverify', [
'secret' => config('services.turnstile.secret'),
'response' => $request->input('cf-turnstile-response'),
])->json('success') === true;
}
}

It runs before any user lookup, so a failed challenge rejects the request identically whether or not the email exists — it can never become an enumeration oracle. A failure returns the captcha_failed JSON error (or a form error) and issues nothing.

The guard checks a token the browser posts, so the widget that writes the token has to sit inside the request form. Name a view of yours in captcha_view, and both bundled request forms, the WireKit one and the plain one, include it inside the <form>, before the submit button:

// config/email-magic-link.php
'captcha' => App\Auth\TurnstileGuard::class,
'captcha_view' => 'auth.turnstile',
{{-- resources/views/auth/turnstile.blade.php --}}
<div class="cf-turnstile" data-sitekey="{{ config('services.turnstile.key') }}"></div>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

A name that resolves to no view stops the form with a CaptchaMisconfiguredException that names the key, rather than rendering a form whose every request the guard would refuse.

Because it runs first, it is also the mitigation for the availability trade-off of the per-account send cap — see the hourly cap and availability.

Refuse a suspended account a session​

Point the eligibility config at a class implementing EmailMagicLink\Contracts\SignInEligibility:

final class NotSuspended implements SignInEligibility
{
public function allows(Authenticatable $user, string $guard): bool
{
return $user->suspended_at === null;
}
}

It is asked twice, and the second time is why this exists as a contract rather than as middleware. A middleware that logs a suspended account out runs on the request after the one that signed it in; by then a session was opened. Gating only the issuing endpoint is no better, because a link handed out a minute before the suspension is still a valid credential afterwards and nothing looks the address up when it comes back. So the package asks when the request endpoint issues and again on every redemption. The Mint API takes the user you resolved and leaves the first question to you.

On issue, a refused account resolves to nothing and the endpoint answers for it exactly as it answers for an address nobody registered — same status, same redirect, same bytes. That is deliberate: a distinguishable refusal would let somebody send one link and learn both that the account exists and that it is suspended. On redemption the token is consumed and the sign-in refused, and MagicLinkConsumptionFailed carries ClaimFailure::Ineligible.

Listen for that event rather than logging inside allows(). The issuing path calls the method for accounts an attacker merely guessed at, so a log line there records somebody else's typing; the event fires only where a genuine token was presented.

Decide from the account, never from the request — the request that asks for a link is not the one that redeems it, and a decision that depended on the first could not be repeated on the second.

Invitation acceptance is outside this gate. It runs through your own InvitationHandler, which is the thing deciding what an account becomes.

Choose the guard by host​

By default a request names its guard in a guard field, and guards lists the ones it may name. Listing a guard there lets every request pick it, on every host. An application with two kinds of account often wants the guard to follow the host instead: the readers of a site sign in on the site's host, its own domain included, and the team signs in on the application's host.

Point the guard_resolver config at a class implementing EmailMagicLink\Contracts\GuardResolver, and list every guard it may answer in guards:

final class GuardByHost implements GuardResolver
{
public function guardFor(Request $request, ?string $requested): string
{
return $request->getHost() === 'app.example.com' ? 'web' : 'reader';
}
}
'guard' => 'web',
'guards' => ['reader'],
'guard_resolver' => GuardByHost::class,

The resolver decides when a link or a code is issued and again when one is redeemed. A reader's link redeemed on the application's host asks it with the guard reader, gets web back, and is refused before any user is looked up, so the reader provider is never asked on a host where it has no tenant. The guard field of the request changes nothing the resolver does not read itself.

Its answer has to be guard or one listed in guards; any other answer throws a LogicException when a link or a code is requested and when a code is entered. Invitations do not ask it, because their signed URL already binds them to the host they were made for.

Name the tenant and greet by name​

Point the mail_identity config at a class implementing EmailMagicLink\Contracts\MailIdentity:

final class TenantMailIdentity implements MailIdentity
{
public function applicationName(Authenticatable $user): string
{
return $user->tenant->name;
}

public function greeting(Authenticatable $user): ?string
{
return $user->name === null ? null : __('Hello :name,', ['name' => $user->name]);
}
}

The name replaces app.name wherever the mail uses it, in the subject, the introduction and the sign-off of the link mail and of the code mail. A null greeting keeps the bundled one. The mail that goes out is still MagicLinkNotification, so tests that assert on it stay as they are.

Both are set as text, so a name typed as [Sign in](https://…) reaches the inbox as those characters and not as a link. A greeting returned as an Htmlable is set as it is.

It is asked in the request that issues the link, with the account, and the answers travel with the queued notification, so a tenant the request resolved is at hand and the greeting is in the request's language. Keep it to what the account and the request already hold: it runs only for addresses that belong to an account, and an exception from it is reported while the mail goes out under the bundled name and greeting.

invalid_response.via accepts the class-string of your own EmailMagicLink\Contracts\InvalidLinkResponder when none of the four built-in strategies fits. See Invalid or expired links.

Customize the screens​

Publish the Blade views and edit them:

php artisan vendor:publish --tag=email-magic-link-views

See The WireKit screens for how the WireKit variants are selected and styled.