tilleuls / url-signer-bundle
Create and validate signed URLs with a limited lifetime in Symfony
Installs: 226 956
Dependents: 0
Suggesters: 0
Security: 0
Stars: 77
Watchers: 16
Forks: 4
Open Issues: 0
Type:symfony-bundle
Requires
- php: >=8.1
- spatie/url-signer: ^2.0
- symfony/config: ^4.4 || ^5.1 || ^6.0 || ^7.0
- symfony/dependency-injection: ^4.4 || ^5.1 || ^6.0 || ^7.0
- symfony/event-dispatcher: ^4.4 || ^5.1 || ^6.0 || ^7.0
- symfony/http-kernel: ^4.4 || ^5.1 || ^6.0 || ^7.0
- symfony/routing: ^4.4 || ^5.1 || ^6.0 || ^7.0
Requires (Dev)
- behat/behat: ^3.8
- friends-of-behat/symfony-extension: ^2.2
- friendsofphp/php-cs-fixer: ^3.0
- infection/infection: ^0.27
- jangregor/phpstan-prophecy: ^1.0
- phpspec/prophecy-phpunit: ^2.0
- phpstan/phpstan: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^9.5
- psalm/plugin-phpunit: ^0.18
- psalm/plugin-symfony: ^5.0
- symfony/browser-kit: ^4.4 || ^5.0 || ^6.0 || ^7.0
- symfony/framework-bundle: ^4.4 || ^5.0 || ^6.0 || ^7.0
- vimeo/psalm: ^5.8
README
Create and validate signed URLs with a limited lifetime in Symfony.
This bundle is based on spatie/url-signer.
Installation
Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.
Open a command console, enter your project directory and execute:
composer require tilleuls/url-signer-bundle
If you're using Symfony Flex, all configuration is already done.
You can customize it in config/packages/url_signer.yaml
file.
Otherwise, enable the bundle by adding it to the list of registered bundles
in the config/bundles.php
file of your project:
// config/bundles.php return [ // ... CoopTilleuls\UrlSignerBundle\CoopTilleulsUrlSignerBundle::class => ['all' => true], ];
Configuration
Add a signature key (as environment variable):
# config/packages/url_signer.yaml coop_tilleuls_url_signer: signature_key: '%env(string:SIGNATURE_KEY)%'
In dev mode, you can use an .env
file:
# .env (or .env.local) SIGNATURE_KEY=your_signature_key
You can change the signer used to create the signature:
# config/packages/url_signer.yaml coop_tilleuls_url_signer: signer: 'md5' # 'sha256' by default
The default expiration time can be changed too.
In seconds:
# config/packages/url_signer.yaml coop_tilleuls_url_signer: default_expiration: 3600 # 86400 by default
With a date/time string:
# config/packages/url_signer.yaml coop_tilleuls_url_signer: default_expiration: '1 day'
You can also customize the URL parameter names:
# config/packages/url_signer.yaml coop_tilleuls_url_signer: expires_parameter: 'exp' # 'expires' by default signature_parameter: 'sign' # 'signature' by default
Usage
Generate a Signed URL
To create a temporary signed URL for a route, you first need to inject the URL signer to your service or controller:
// src/Controller/DocumentController.php namespace App\Controller; use CoopTilleuls\UrlSignerBundle\UrlSigner\UrlSignerInterface; class DocumentController { public function __construct( private UrlSignerInterface $urlSigner, ) {} }
If autowiring is enabled (the default Symfony configuration) in your application, you have nothing more to do.
Otherwise, inject the url_signer.signer
service in the configuration:
# config/services.yaml services: App\Controller\DocumentController: arguments: $urlSigner: '@url_signer.signer'
You can now use the URL signer to generate a signed path or a signed URL:
// src/Controller/DocumentController.php namespace App\Controller; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; class DocumentController extends AbstractController { private function generateSignedUrl(): string { // Or $url = $this->generateUrl('secured_document', ['id' => 42], UrlGeneratorInterface::ABSOLUTE_URL); $url = $this->generateUrl('secured_document', ['id' => 42]); // Will expire after one hour. $expiration = (new \DateTime('now'))->add(new \DateInterval('PT1H')); // An integer can also be used for the expiration: it will correspond to a number of seconds. For 1 hour: // $expiration = 3600; // Not passing the second argument will use the default expiration time (86400 seconds by default). // return $this->urlSigner->sign($url); // Will return a path like this: /documents/42?expires=1611316656&signature=82f6958bd5c96fda58b7a55ade7f651fadb51e12171d58ed271e744bcc7c85c3 // Or a URL depending on what has been signed before. return $this->urlSigner->sign($url, $expiration); } }
Validate Signed Route Requests
To deny access to a route if the signature is not valid,
add a _signed
extra parameter to the route configuration:
# config/routes.yaml secured_document: path: /documents/{id} controller: App\Controller\DocumentController::index defaults: _signed: true
If the signature is invalid (bad signature or expired URL), the request will receive a 403 response (access denied).
Custom Signer
If you need to use a specific hash algorithm for generating the signature, you can create your own signer.
Create a class extending the AbstractUrlSigner
class:
// src/UrlSigner/CustomUrlSigner.php namespace App\UrlSigner; use CoopTilleuls\UrlSignerBundle\UrlSigner\AbstractUrlSigner; class CustomUrlSigner extends AbstractUrlSigner { public static function getName(): string { return 'custom'; } protected function createSignature(string $url, string $expiration, string $signatureKey): string { return hash_hmac('algo', "{$url}::{$expiration}", $signatureKey); } }
If autoconfiguring is enabled (the default Symfony configuration) in your application, you are done.
Otherwise, register and tag your service:
# config/services.yaml services: App\UrlSigner\CustomUrlSigner: # You don't need to specify the arguments tags: ['url_signer.signer']
You can now use your custom signer:
# config/packages/url_signer.yaml coop_tilleuls_url_signer: signer: 'custom'
Credits
Created by Alan Poulain for Les-Tilleuls.coop.