DEV Community: Danny Festor

Laravel's most underrated security feature - What actually is a signed URL, and how do they work?

Danny Festor — Mon, 20 May 2024 07:47:43 +0000

This post was first released on my personal blog

Laravel comes with many fantastic security features out of the box and also has many 1st party packages that add security functionality to your application. We have Cross Site Scripting (XSS) protection, Cross Site Request Forgery (CSRF) protection, Roles and Permissions via Gates, SQL Injection protection, but also whole authentication scaffolding (Breeze) including 2 factor authorization (Jetstream)

One feature is very much overlooked in my opinion. Laravel comes with the ability to create signed urls. In this article I will not only show how to use signed URLs (Laravel makes this trivial), but also look on how this works under the hood so that you can implement the same functionality in other languages (or your own PHP framework).

What are signed URLs?

Signed URLs are unguessable URLs you can share with other people without the requirement of being logged in into the system. They are like normal URLs to your app, but have a cryptographically signed hash at the end of the URL.

# normal url
http://signed-url.test/file/29

# signed url
http://signed-url.test/file/29?signature=78e68c73c03586a5705442e86116c5169c8b64e4720b16766eece296ada49d5a

This makes the URLs temper-proof; Change one character in the URL and the hash will not match any longer. AWS S3 uses signed URLs to retrieve private images.

What can I actually use these for?

The Laravel Documentation actually has a fantastic use case for signed URLs: Unsubscribing a user from a newsletter. You get an email, click the unsubscribe button, and you can unsubscribe from the newsletter without logging in or send another confirmation email, because the email address cannot be changed. If you changed the email address the hash would not match any longer.

Another example would be a file sharing application. Upload the file, and get a signed url you can use to share the file with your friends or on the internet without anyone to register an account.

What are signed URLs not?

They are not one time use URLs, at least not by default. There is not default way to invalidate the signed URL, except for changing the application key, which would invalidate every single signed URL. Do not use signed URLs for security critical endpoints, if you don't have a strategy to invalidate the URLs.

There was a discussion on Reddit on this earlier this year.

Generating Signed URLs

Generating a signed URL in Laravel is super easy.

<?php
use Illuminate\Support\Facades\URL; // Import the URL facade

class NewsletterController extends Controller
{
    // ...
    public function unsubscribe()
    {
        // ...
        $unsubscription = NewsletterUnsubscriptions::create();
        $signedRoute = URL::signedRoute('newsletter.unsubscribe', ['unsubscription' => $unsubscription]);
        // http://signed-url.test/newsletter/unsubscriptions/29?signature=78e68c73c03586a5705442e86116c5169c8b64e4720b16766eece296ada49d5a
        // ...
    }
}

Invalidating a Signed URL

There is one way to invalidate a signed URL build into Laravel: The ability to add a time limit to a signed URL, making it temporary. When the current timestamp (on the server, of course) is after the timestamp specified in the signed URL, Laravel actually invalidates the URL automatically.

<?php
use Illuminate\Support\Facades\URL; // Import the URL facade

class NewsletterController extends Controller
{
    // ...
    public function unsubscribe()
    {
        // ...
        // To add a timestamp to a signed URL, just use the temporarySignedRoute method instead of signedRoute and add a timestamp
        $unsubscription = NewsletterUnsubscriptions::create();
        $signedRoute = URL::temporarySignedRoute('newsletter.unsubscribe', now()->addMinutes(10), ['unsubscription' => $unsubscription]);
        // http://signed-url.test/file/30?expires=1716185539&signature=fa1fcfa2f47270ef2ef55b20aa5990eacbf6fb11d45984828d7be3f87258cae9
    }
}

Notice the expires parameter? Laravel add that automatically when using temporarySignedRoute. How cool is that?

Actually checking the signed URL

Just adding the signature is of course not enough. At no point we are actually confirming that the hash is a legit one. Again, since Laravel supports signed URL out of the box, confirming the hash is super easy as well. It's just changing one line in your route file routes/web.php, by adding the signed middleware to your route.

Route::get(
    '/newsletter/unsubscriptions/{unsubscription}', 
    [\App\Http\Controllers\NewsletterController::class, 'unsubscribe'])
    ->name('newsletter.unsubscribe')]
    ->middleware('signed'); // add the signed middleware

It does not get easier than this!

So how does it work under the hood?

I firmly believe that just knowing that a feature exists is not enough. I want to know how these things work under the hood. Let's try to recreate the functionality in a basic way

Manually generating a signed URL

Manually generating a signed URL requires leveraging PHP's built-in hash function. If you are trying to port this functionality to another language, look up how to hash a string in your language of choice. For instance, I know Go does have this built in into the crypto package.

// put the timestamp into a variable so we can reuse it here
$expires = now()->addMinutes(10);
$signedRoute = URL::temporarySignedRoute('newsletter.unsubscribe', $expires, ['unsubscription' => $unsubscription]);  

$route = URL::route('newsletter.unsubscribe', ['unsubscription' => $unsubscription, 'expires' => $expires->timestamp]);  
$manualRoute = $route . '&signature=' . hash_hmac('sha256', $route, config('app.key'));  

dd(  
    'Result from $signedRoute:' . $signedRoute,  
    'Result from $manualRoute:' . $manualRoute  
);

// "Result from $signedRoute: http://signed-url.test/file/32?expires=1716187120&signature=b9aa919a8f4ce54e89e4270dbadc2bcab5e203304aacd1c4c95c9889f101e3f1"
// "Result from $manualRoute: http://signed-url.test/file/32?expires=1716187120&signature=b9aa919a8f4ce54e89e4270dbadc2bcab5e203304aacd1c4c95c9889f101e3f1"

How easy was that? Notice how we signed the hash with our app.key here. Signing urls with a different app key will result in a different hash

Manually Validating the Signature

By default the signed middleware sends the user to a 403 error page. To manually handle URL validation, you can make use of a nice little request helper.

public function show(Request $request, NewsletterUnsubscriptions $unsubscription)  
{  
    dd($request->hasValidSignature()); 
}

This helper function will check if the signature has not been tampered with, as well as if it has not yet expired.

Under the hood of the hasValidSignature function there is actually happening a lot:

// get the url without query string
$url = $request->url();

// get all query parameters except signature in [$key => $value] form
$query = $request->except('signature');

// join each array entry to a &key=&value string
$params = [];
foreach ($query as $key => $value) {  
    $params[] = $key . '=' . $value; 
}

// get the signature 
$urlsignature = $request->query('signature', ''); 

// reconstruct the original url without the signature
$original = $url . '?' . implode('&', $params); 

// generate a new signature based on the url without the signature
$signature = hash_hmac('sha256', $original, config('app.key'));  

// compare the signature in the url with the new signature
$equals = hash_equals($signature, (string) $request->query('signature', ''));

// handle what happens when the hash is not equal
dump($equals);

// check if the timestamp is expired
$expired = false;  
if (isset($query['expires'])) {  
    $expireTime = Carbon::createFromTimestamp($query['expires']);  
    $expired = now()->gt($expireTime);  
}  

// handle an expired timestamp
dd($expired);

We use hash_equals instead of normal string comparison here, because it is timing attack secure.

Why would you manually handling this?

The other day I had a client with a peculiar request. They wanted password reset to handle a completely invalid URL differently from an expired URL. On an invalid URL the program would throw an error, on an expired URL the app would redirect to the send password reminder page.

Homework

Making signed URLs actually one time usage

So one question remains: How to actually make a signed URL a one time thing? In the example above we took the example from the Laravel documentation. Imagine you want to handle newsletter unsubscriptions. There are several ways you could go about this.

Just add a flag to the NewsletterUnsubscription model; it could be a boolean is_used, an integer used_count or a timestamp used_at. After checking the validity of the signed URL (be it manually, or using Laravel's middleware) just check if the used flag was raised. In case of the integer, you could even restrict file downloads to an arbitrary number.
Add a flag to the cache of your choice on NewsletterUnsubscription creation. If the cache has an entry, the request is valid, show the page and delete the cache entry. If the cache does not have an entry, the request is invalid.
... even different solutions, I'm sure you can think of more strategies.

Acknoledgements

Laravel
Google Gemini, which I actually used to generate the banner...

Websockets with Laravel, Soketi and Laravel Echo

Danny Festor — Sat, 09 Mar 2024 02:32:59 +0000

This article was first released on my portfolio homepage

Everyone knows these pesky notification bell icons, which tell you in real-time whenever an event is triggered that is meant to... well... notify you.

There are many different ways to implement such a system.

Javascript pulling via setInterval
(Laravel Only) Livewire pulling via wire:poll
Server Sent Events
Websockets
Probably more?

With Laravel Reverb on the radar, releasing on March 12 2024, (as in 4 days, at the time of this article), I wanted to explore how to actually use Websockets; My projects so far have never needed them.

Up until now, Laravel recommends Pusher, Ably, or the self hosted Pusher alternative Soketi in the official documentation. Soketi on the other hand has Laravel baked into their documentation as well. So I did the only sane thing, and explored how to use Websockets with Soketi. I expect I can easily migrate to Reverb, once released.

In this article I will omit setting up the project, the models, and views. You can find the source code for this article in my Github repo. Follow the commit history to see changes to the various files. I used Laravel Breeze with the Alpine.js template to get Alpine and Tailwind.css installed and set up for me.

Updating Laravel Sail

Since Soketi is a self hosted solution, you will have to install it somewhere. The easiest way is by using Docker, so I went with Laravel Sail for this tutorial. Laravel Sail is not meant for production, but it is good enough for Localhost development and testing.

Add Soketi to Docker

First, you need to add the Soketi image to your docker-compose-file. Obviously skip this step when not using docker. As per their documentation

# docker-compose.yml
services:
    # ...
    soketi:  
        image: 'quay.io/soketi/soketi:latest-16-alpine'  
        environment:  
            SOKETI_DEBUG: '1'  
            SOKETI_METRICS_SERVER_PORT: '9601'  
        ports:  
            - '${SOKETI_PORT:-6001}:6001'  
            - '${SOKETI_METRICS_SERVER_PORT:-9601}:9601'  
        networks:  
            - sail
networks:
# ...

You also need to update your environment file. Soketi uses the Pusher protocol, so you need to update relevant Pusher parts

BROADCAST_DRIVER=pusher # was log

# As set in soketi
PUSHER_APP_ID=app-id
PUSHER_APP_KEY=app-key  
PUSHER_APP_SECRET=app-secret 
# Host is only soketi in docker. If you installed soketi locally, use 127.0.0.1, or the IP of your server
PUSHER_HOST=soketi  
PUSHER_PORT=6001  
PUSHER_SCHEME=http

# Browser does not run in docker, so using the value set in PUSHER_HOST won't work
VITE_PUSHER_HOST="127.0.0.1" # was "${PUSHER_HOST}"

Installing the needed packages

PHP side

You will have to install the Pusher Channels SDK for Laravel to be able to use the pusher driver

composer require pusher/pusher-php-server

After installing the driver, you need to tweak the configuration to enable broadcasting by uncommenting the BroadcastServiceProvider in config/app.php

// config/app.php
// ...
'providers' => ServiceProvider::defaultProviders()->merge([
    // ...
    App\Providers\BroadcastServiceProvider::class, // Enable the Service Provider, was commented out
    // ...

Frontend (Javascript) Side

You also need the Javascript for you client side code

npm install --save-dev laravel-echo pusher-js

After installing the packages you also have to uncomment the broadcasting related code in resources/js/bootstrap.js. Laravel makes it really easy, the code is already there!

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';
window.Pusher = Pusher;

window.Echo = new Echo({  
    broadcaster: 'pusher',  
    key: import.meta.env.VITE_PUSHER_APP_KEY,  
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER || 'mt1',  
    wsHost: import.meta.env.VITE_PUSHER_HOST ? import.meta.env.VITE_PUSHER_HOST : `ws-${import.meta.env.VITE_PUSHER_APP_CLUSTER}.pusher.com`,  
    wsPort: import.meta.env.VITE_PUSHER_PORT ?? 80,  
    wssPort: import.meta.env.VITE_PUSHER_PORT ?? 443,  
    // forceTLS: (import.meta.env.VITE_PUSHER_SCHEME ?? 'https') === 'https',  
    forceTLS: false, // I deactivated TLS for local testing
    enabledTransports: ['ws', 'wss'],  
    encrypted: true, // Soketi documentation adds this line
    disableStats: true, // as well as this line
});

Broadcasting an event to your users

Broadcasting channels for Websockets live in their own routing file. You are probably used to adding routes to routes/web.php or routes/api.php and have wondered what the other files were used for. Well, it's time to actually activate route/channels.php and add our Websocket Channel! The channel will actually be a private channel, which is scoped to your current user. You can actually add authorization to channels this way!

// routes/channels.php
// The channel always receives the current user, as well as optional arguments. We will connect to notifications.[user_id], which the callback receives as an argument as well
Broadcast::channel('notifications.{userId}', function (User $user, int $userId) {
    return $userId === $user->id; // users can only connect to this channel if true is returned
});

In Laravel, information is broadcasted over events, so let us create one.

php artisan make:event UserNotificationEvent

The event will receive a user id, because we scoped the channel to a user in the snippet above, as well as a notification (or whatever data you want to send).

// app/Events/UserNotificationEvent.php

// do not forget to implement the `Illuminate\Contracts\Broadcasting\ShouldBroadcast` interface, otherwise your event will not be broadcasted to your websocket server
class UserNotificationEvent implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;  

    // receive the data needed for the event. all public properties of the class will be sent on the event
    public function __construct(public int $userId, public Notification $notification)  
    {}  

    public function broadcastOn(): Channel // update return type from array to Channel  
    {  
        // broadcast over a private channel to the user!
        return new PrivateChannel('notifications.' . $this->userId);  
    }
}

For test purposed I also added a console command to quickly create notifications. This command will also dispatch the event. Usually, you would to everything in the command in your admin panel, but for a small test, a console command has to be sufficient.

php artisan make:command MakeNotificationCommand

class MakeNotificationCommand extends Command  
{  
    // run with php artisan make:notification, which accepts a number
    protected $signature = 'make:notification {num=1}';  

    public function handle()  
    {  
        // always prevent shenanigans by your users, even in a test application. I restricted input to 1-100 notifications... 
        $num = min(100, max((int)$this->argument('num'), 1));  

        // get all users
        // typically, you would select users in your admin panel
        $userIds = User::pluck('id')->all();

        // generate notifications. I'm using a factory here to create random data, but usually you would receive title, content etc through your admin panel
        $notifications = Notification::factory($num)->create();  

        $notifications->each(function (Notification $notification) use ($userIds) {  
            foreach(array_chunk($userIds, 100) as $chunk) {
                // add an entry into my notification_user pivot table for each user
                $insert = array_map(function ($userId) use ($notification) {  
                    return [  
                        'notification_id' => $notification->id,  
                        'user_id' => $userId,  
                    ];  
                }, $chunk);  
                NotificationUser::insert($insert);  

                foreach($chunk as $userId) {
                    // finally, dispatch the event to every user, passing the notification information
                    UserNotificationEvent::dispatch($userId, $notification);  
                }  
            }  
        });  
    }  
}

If everything went correctly (did you remember to implement the ShouldBroadcast interface? I was trying to figure that one out the longest time 😅)

Receiving events on the client side

The sending is good and well, but we want to actually see the notifications on the client side as well. I have the views for the notification bell, the unread count, and a notification list all ready. They are available in the git repository if you need inspiration. To receive notifications, you just have to connect to your channel route, and then handle the event!

First, let us get all existing notifications, and pass them to the user. Usually you would do this in a controller, or even a view service provider (since you probably want to show the notification bell on every page), but the routes/web.php file will do just fine for this demo

// routes/web.php
Route::get('/dashboard', function () {  
    $user = Auth::user();

    // get all new notifications for the current user which (as in, the seen_at column on the notification_user pivot table is null)
    $notifications = $user->notifications()->whereNull('seen_at')->get();  

    return view('dashboard', [  
        'user' => $user,  
        'notifications' => $notifications,  
    ]);  
})->middleware(['auth', 'verified'])->name('dashboard');

Route::post('/notifications', function (Request $request) {
    // mark all notifications as seen
    \App\Models\NotificationUser::query()  
        ->where('user_id', $request->user()->id)  
        ->update(['seen_at' => now()]);  

    return 'ok';  
})->middleware(['auth'])->name('notifications');

// resources/views/dashboard.blade.php
// add the notification component, if you have created one, and pass the data
<x-notification :user="$user" :notifications="$notifications" />

I am using Alpine.js for displaying the content. I expect the code can be easily ported to any Javascript framework and even vanilla JS. Just update the view logic, and bring the content from the init() method to your frameworks mounted hook (onMounted on Vue3, useEffect on React etc).

<!-- resources/views/components/notification.blade.php -->
@props(['user', 'notifications', 'eventName'])  

<div x-data="notification">  
    <div @click="markRead" class="relative w-6 h-6">  
        <x-bell />  
        <x-count />  
    </div>  
    <x-notification-dropdown />  
</div>  

@push('scripts')  
<script>  
    document.addEventListener('alpine:init', () => {  
        Alpine.data('notification', () => ({
            // this object will hold all notifications received at page load
            notifications: @json($notifications),  

            // a computed property to get the current notification count
            get count() {  
                return this.notifications.length;  
            },


            // on click of the bell, make a post request to mark all notifications as read. you probably want a better implementation, because you probably want the notifications to show in a popup. I leave the implementation to you
            async markRead() {  
                const { data } = await axios.post('{{ route('notifications') }}');  

                if (data !== undefined && data === 'ok') {  
                    this.notifications = [];  
                }  
            },

            // this is where we connect to the websocket. Do this on your mounted hook, be it document.addEvent('DOMContentLoaded') in vanilla JS, onMounted in Vue3, or useEffect() in React... 
            init() {  
                // connect to our socket. notice that we pass the user id here, just as we expected in routes/channels.php
                Echo.private('notifications.{{ $user->id }}')
                    // the event name we are listening to must exactly match the short/unqualified class name of our event (so, without namespace or the ::class suffix)
                    .listen('UserNotificationEvent', (e) => {  
                        if (e.notification !== undefined) {  
                            // if the event has a notification property, push the notification on the notifications object
                            this.notifications.push(e.notification);  
                        }  
                    });  
            },  
        }));  
    });  
</script>  
@endpush

My demo implementation is just an ordered list of all notifications. You probably want to pop it up on click, or something similar.

Conclusion

Laravel makes broadcasting to webcasts as well as receiving the events really easy. Most of the functionality comes out of the box and only a few files have to be adjusted to get started.

Bonus: Possible improvements as homework

The frontend part is really bare bones. Show it some love (and update us how you did it!)
Show a notification bell throughout your application. Try adding a View Composer to accomplish this
Try playing with public and presence channels as well. Laravels Broadcasting documentation explains what these are
Maybe build a small chat app that allows guest users to communicate

Bonus 2: Getting really cheeky using Reflection

Since we have to pass the short class name to the event, it might make sense to actually let PHP handle the event name. This way you can rename the event (using your IDE/language servers rename function (Intelephense etc), to automatically update references), without digging into the Javascript side again

// routes/web.php
Route::get('/dashboard', function () {  
    $user = Auth::user();  
    $notifications = $user->notifications()->whereNull('seen_at')->get();  
    $eventName = (new \ReflectionClass(\App\Events\UserNotificationEvent::class))->getShortName(); // get the short class name. This will automatically update, should you rename the event via IDE or language server 

    return view('dashboard', [  
        'user' => $user,  
        'notifications' => $notifications,  
        'eventName' => $eventName, // pass the eventName to your view. Don't forget to update the views to use the variable, instead of hardcoding the event name3
    ]);  
})->middleware(['auth', 'verified'])->name('dashboard');