Download the PHP package zenstruck/signed-url-bundle without Composer

zenstruck/signed-url-bundle

Helpers for signing and verifying urls with support for temporary and single-use urls. Some common use cases include:

• Stateless Password Resets
• Stateless Email Verification
• Stateless Verified Change Email

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:

1. SignedUrl Object that contains metadata about the created signed url.
2. 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

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.

Signed URL Builder

You can create a signed, single-use URL using Generator::build().

SignedUrl Object

Generator::build() creates a signed URL builder, calling create() on this returns a SignedUrl object with context for the url:

Temporary Urls

These urls expire (cannot be verified) after a certain time. They are also signed so cannot be tampered with.

Verification

The Zenstruck\SignedUrl\Verifier is an auto-wireable service that is used to verify signed urls.

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.

Single-Use Verification

For validating single-use urls, you need to pass a token to the Verifier's verify methods:

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:

Generate the url using this token object:

When verifying, use the token object here as well:

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:

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):

Alternatively, a signed route option can be added to your route definition:

Verification Exceptions

Verification can fail for the following reasons (in this order):

1. Signature missing or invalid (URL has been tampered with).
2. If the URL has an expiration and has expired.
3. 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):

Full Default Configuration

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:

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.

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.

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.