zenstruck / signed-url-bundle
Helpers for signing and verifying urls with support for temporary and single-use urls.
Fund package maintenance!
kbond
Installs: 595
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 1
Forks: 1
Open Issues: 3
Type:symfony-bundle
Requires
- php: >=7.4
- symfony/framework-bundle: ^4.4|^5.0|^6.0
- symfony/polyfill-php80: ^1.15
Requires (Dev)
- matthiasnoback/symfony-dependency-injection-test: ^4.3
- symfony/browser-kit: ^4.4|^5.0|^6.0
- symfony/phpunit-bridge: ^5.3
README
Helpers for signing and verifying urls with support for temporary and single-use urls. Some common use cases include:
use Zenstruck\SignedUrl\Generator; public function sendPasswordResetEmail(User $user, Generator $generator) { $resetUrl = $generator->build('password_reset_route', ['id' => $user->getId()]) ->expires('+1 day') ->singleUse($user->getPassword()) ; // create email with $resetUrl and send }
use Zenstruck\SignedUrl\Verifier; use Zenstruck\SignedUrl\Exception\UrlVerificationFailed; public function resetPasswordAction(User $user, Verifier $urlVerifier) { try { $urlVerifier->verifyCurrentRequest(singleUseToken: $user->getPassword()); } catch (UrlVerificationFailed $e) { $this->flashError($e->messageKey()); // safe reason to show user return $this->redirect(...); } // continue }
Why This Bundle?
Symfony includes a UriSigner
(in fact, this bundle uses this) but it doesn't have out of the
box support for temporary/single-use urls. Symfony 5.2 introduced
login links that has these features
but is restricted to these type of links only.
tilleuls/url-signer-bundle
is
another bundle that provides expiring signed urls but not single-use (out of the box).
Additionally, this bundle provides the following features:
SignedUrl
Object that contains metadata about the created signed url.- Explicit exceptions so you can know exactly why verification failed and optionally relay this to the user (ie the url has already been used or the url has expired)
Installation
composer require zenstruck/signed-url-bundle
NOTE: If not added automatically by symfony/flex
, enable ZenstruckSignedUrlBundle
.
Generate
The Zenstruck\SignedUrl\Generator
is an auto-wireable service that is used to generate signed urls
for your Symfony routes. By default, all generated urls are absolute.
Standard Signed Urls
Generator
service is an instance of Symfony\Component\Routing\Generator\UrlGeneratorInterface
.
Calling Generator::generate()
creates a standard signed url (no expiration). These are
absolute by default.
use Zenstruck\SignedUrl\Generator; /** @var Generator $generator */ $generator->generate('route1'); // http://example.com/route1?_hash=... $generator->generate('route2', ['parameter1' => 'value']); // http://example.com/route2/value?_hash=... $generator->generate('route3', [], Generator::ABSOLUTE_PATH); // /route2/value?_hash=...
Signed URL Builder
You can create a signed, temporary and/or single-use
URL using Generator::build()
.
/** @var Zenstruck\SignedUrl\Generator $generator */ (string) $generator->build('reset_password', ['id' => $user->getId()]) ->expires('+1 hour') ->singleUse($user->getPassword()) ;
SignedUrl
Object
Generator::build()
creates a signed URL builder, calling create()
on this returns
a SignedUrl
object with context for the url:
/** @var Zenstruck\SignedUrl\Generator $generator */ $signedUrl = $generator->build('reset_password', ['id' => $user->getId()]) ->expires('+1 hour') ->singleUse($user->getPassword()) ->create() ; /** @var Zenstruck\SignedUrl $signedUrl */ (string) $signedUrl; // the actual URL $signedUrl->expiresAt(); // \DateTimeImmutable $signedUrl->isTemporary(); // true $signedUrl->isSingleUse(); // true
Temporary Urls
These urls expire (cannot be verified) after a certain time. They are also signed so cannot be tampered with.
/** @var Zenstruck\SignedUrl\Generator $generator */ (string) $generator->build('route1')->expires('+1 hour'); // http://example.com/route1?__expires=...&_hash=... (string) $generator->build('route2', ['parameter1' => 'value'])->expires('+1 hour'); // http://example.com/route2/value?__expires=...&_hash=... // use # of seconds (string) $generator->build('route1')->expires(3600); // http://example.com/route2/value?__expires=...&_hash=... // use an explicit \DateTime (string) $generator->build('route1')->expires(new \DateTime('+1 hour')); // http://example.com/route2/value?__expires=...&_hash=...
Verification
The Zenstruck\SignedUrl\Verifier
is an auto-wireable service that is used to verify signed urls.
use Zenstruck\SignedUrl\Exception\UrlVerificationFailed; /** @var Zenstruck\SignedUrl\Verifier $verifier */ /** @var string $url */ /** @var Symfony\Component\HttpFoundation\Request $request */ // simple usage: return true if valid and non-expired (if applicable), false otherwise $verifier->isVerified($url); $verifier->isVerified($request); // can pass Symfony request object $verifier->isCurrentRequestVerified(); // verifies the current request (fetched from RequestStack) // try/catch usage: catch exceptions to provide better feedback to users try { $verifier->verify($url); $verifier->verify($request); // alternative $verifier->verifyCurrentRequest(); // alternative } catch (UrlVerificationFailed $e) { $e->url(); // the url used $e->getMessage(); // Internal message (ie for logging) $e->messageKey(); // Safe message with reason to show the user (or use with translator) }
NOTE: See Verification Exceptions for more information on the thrown exception.
Single-Use Urls
These urls are generated with a token that should change once the url has been used.
CAUTION: It is up to you to determine this token and depends on the context. This value MUST change after the token is successfully used, else it will still be valid.
A good example is a password reset. For these urls, the token would be the current user's password. Once they successfully change their password the token wouldn't match so the url would become invalid.
NOTE: The URL is first hashed with this token, then hashed again with the app-level secret to ensure it hasn't been tampered with.
/** @var Zenstruck\SignedUrl\Generator $generator */ // !! This will be the single-use token that changes once "used" !! $password = $user->getPassword(); $url = $generator->build('reset_password', ['id' => $user->getId()]) ->singleUse($password) ->create() ;
Single-Use Verification
For validating single-use urls, you need to pass a token to the Verifier's verify methods:
use Zenstruck\SignedUrl\Exception\UrlVerificationFailed; /** @var Zenstruck\SignedUrl\Verifier $verifier */ /** @var string $url */ /** @var Symfony\Component\HttpFoundation\Request $request */ // !! This is the single-use token. If the url was generated with a different password verification will fail !! $password = $user->getPassword(); $verifier->isVerified($url, $password); $verifier->isVerified($request, $password); $verifier->isCurrentRequestVerified($password); // try/catch usage: catch exceptions to provide better feedback to users try { $verifier->verify($url, $password); $verifier->verify($request, $password); // alternative $verifier->verifyCurrentRequest($password); // alternative } catch (UrlVerificationFailed $e) { $e->messageKey(); // "URL has already been used." (if failed for this reason) }
Token Objects
The single-use token is required for both generating and verifying the url. These are likely
done in different parts of your application. To avoid duplicating the generation of your
token, it is recommended to wrap the logic into simple token objects that are \Stringable
:
final class ResetPasswordToken { public function __construct(private User $user) {} public function __toString(): string { return $this->user->getPassword(); } }
Generate the url using this token object:
/** @var Zenstruck\SignedUrl\Generator $generator */ $generator->build('reset_password', ['id' => $user->getId()])->singleUse(new ResetPasswordToken($user));
When verifying, use the token object here as well:
/** @var Zenstruck\SignedUrl\Verifier $verifier */ $verifier->isVerified($url, new ResetPasswordToken($user)); $verifier->verify($url, new ResetPasswordToken($user)); $verifier->isCurrentRequestVerified(new ResetPasswordToken($user)); $verifier->verifyCurrentRequest(new ResetPasswordToken($user));
Auto-Verify Routes
You can auto-verify specific routes using a routing option or attribute. Before
these controllers are called, an event listener verifies the route and throws
an HttpException
(403
by default) on failure. You do not have the option
to intercept and provide a friendly message to the user. Additionally, single-use
URL verification is not possible.
This feature needs to be enabled:
# config/packages/zenstruck_signed_url.yaml zenstruck_signed_url: route_verification: true
Add the Zenstruck\SignedUrl\Attribute\Signed
attribute to the controller you
want auto-verified (can be added to the class to mark all methods as signed):
use Zenstruck\SignedUrl\Attribute\Signed; #[Signed] #[Route(...)] public function action1() {} // throws a 403 HttpException if verification fails #[Signed(status: 404)] #[Route(...)] public function action1() {} // throw a 404 exception instead
Alternatively, a signed
route option can be added to your route definition:
# config/routes.yaml action1: path: /action1 options: { signed: true } # throws a 403 HttpException if verification fails action2: path: /action2 options: { signed: 404 } # throw a 404 exception instead
Verification Exceptions
Verification can fail for the following reasons (in this order):
- Signature missing or invalid (URL has been tampered with).
- If the URL has an expiration and has expired.
- Single-use URL has been used.
Each of the above reasons has a corresponding exception that can be caught separately
(all exceptions are instances of Zenstruck\SignedUrl\Exception\UrlVerificationFailed
):
use Zenstruck\SignedUrl\Exception\UrlVerificationFailed; use Zenstruck\SignedUrl\Exception\UrlHasExpired; use Zenstruck\SignedUrl\Exception\UrlAlreadyUsed; /** @var Zenstruck\SignedUrl\Verifier $verifier */ try { $verifier->verifyCurrentRequest($user->getPassword()); } catch (UrlHasExpired $e) { // this exception makes the expiration available $e->expiredAt(); // \DateTimeImmutable $e->messageKey(); // "URL has expired." $e->url(); // the URL that failed verification } catch (UrlAlreadyUsed $e) { $e->messageKey(); // "URL has already been used." $e->url(); // the URL that failed verification } catch (UrlVerificationFailed $e) { // must be last as a "catch all" $e->messageKey(); // "URL Verification failed." $e->url(); // the URL that failed verification }
Full Default Configuration
zenstruck_signed_url: # The secret key to sign urls with secret: '%kernel.secret%' # Enable auto route verification (trigger with "signed" route option or "Zenstruck\SignedUrl\Attribute\Signed" attribute) route_verification: false
Cookbook
The following are pseudo-code recipes for possible use-cases for this bundle:
Stateless Password Resets
Generate a password-reset link that has a 1 day expiration and is considered used when the password changes:
/** @var \Zenstruck\SignedUrl\Generator $generator */ /** @var \Zenstruck\SignedUrl\Verifier $verifier */ // REQUEST PASSWORD RESET ACTION (GENERATE URL) $url = $generator->build('reset_password', ['id' => $user->getId()]) ->expires('+1 day') ->singleUse($user->getPassword()) // current password is the token that changes once "used" ->create() ; // send email to user with $url // PASSWORD RESET ACTION (VERIFY URL) try { $verifier->verifyCurrentRequest($user->getPassword()); // current password as the token } catch (\Zenstruck\SignedUrl\Exception\UrlVerificationFailed $e) { $this->flashError($e->messageKey()); return $this->redirect(...); } // proceed with the reset, once a new password will be set/saved, this URL will become invalid
Stateless Email Verification
After a user registers, send a verification email. These emails don't expire
but are considered used once $user->isVerified() === true
. Since these
links do not expire, you'll likely want some kind of cron job that removes
users that haven't verified after a time.
final class VerifyToken { public function __construct(private User $user) {} public function __toString(): string { return $this->user->isVerified() ? 'verified' : 'unverified'; } } /** @var \Zenstruck\SignedUrl\Generator $generator */ /** @var \Zenstruck\SignedUrl\Verifier $verifier */ // REGISTRATION CONTROLLER ACTION (GENERATE URL) $url = $generator->build('verify_user', ['id' => $user->getId()]) ->singleUse(new VerifyToken($user)) // this token's value will be "unverified" ->create() ; // send email to user with $url // VERIFICATION ACTION (VERIFY URL) try { $verifier->verifyCurrentRequest(new VerifyToken($user)); // this token's value should be "unverified" but if not, it is invalid } catch (\Zenstruck\SignedUrl\Exception\UrlVerificationFailed $e) { $this->flashError($e->messageKey()); return $this->redirect(...); } $user->verify(); // marks the user as verified and invalidates the URL // save user & login user immediately or redirect to login page
Stateless Verified Change Email
If your app requires all users have a verified email, a system to allow users to change their email requires verification as well. You can use this bundle to enable this in a stateless way. First, when a user requests an email change, send a link to the new email. This link includes the new email within it so when they click it, the app knows the new verified email to set.
/** @var \Zenstruck\SignedUrl\Generator $generator */ /** @var \Zenstruck\SignedUrl\Verifier $verifier */ // REQUEST EMAIL CHANGE ACTION (GENERATE URL) $url = $generator->build('reset_password', ['id' => $user->getId(), 'new-email' => $newEmailRequested]) ->expires('+1 day') ->singleUse($user->getEmail()) // the user's current email ->create() ; // send verification email to $newEmailRequested with $url // EMAIL CHANGE ACTION (VERIFY URL) try { $verifier->verify($request, $user->getEmail()); // the user's current email } catch (\Zenstruck\SignedUrl\Exception\UrlVerificationFailed $e) { $this->flashError($e->messageKey()); return $this->redirect(...); } $user->setEmail($request->query->get('new-email')); // changes the user email and invalidates the URL // save user
NOTE: Since the new email is included in the query string, this could be considered
a PII leak (as it will appear in logs).
An option to avoid this is to encrypt/decrypt the new-email
value.