Download the PHP package faithfm/laravel-auth0-pattern without Composer

laravel-auth0-pattern

An opinionated library/pattern for Laravel Authentication (AuthN) and Authorisation (AuthZ) - designed to improve consistency across our Faith FM Laravel/Vue projects.

Much of the functionality of our pattern is now delegated to 3x reusable packages. These child packages are less opinionated and will be of more widespread interest to other developers:

• laravel-simple-auth0 - simple session-based Authentication using Auth0.

• laravel-simple-auth-tokens - simple token-based Authentication using API keys (ie: ?api_token=XXXX).
• laravel-simple-permissions - simple Permissions / Authorization Gates using the 'user_permissions' table / Eloquent model.

In v4.0.0 we replaced the official Auth0 Laravel SDK with our own lightweight laravel-simple-auth0 package, and split other functionality into reusable packages. Our laravel-simple-auth0 uses Laravel's built-in Session-Guard and an Eloquent User model retrieved using the 'sub' identifier provided by a simple Auth0 PHP flow).[^1]

Structure:

Our pattern:

• Imports the 3x reusable packages.
• Publishes a number of opinionated templates that are re-used across our applications.
• Provides configuration and usage instructions and guidance.

The structure of the key files provided by this package (and each of the child packages) is:

Installation and Configuration:

• Apply the basic installation and configuration instructions.

• Configure external packages such as Laravel Nova and OwenIT Auditing.

• Configure Auth0 (including allowed callback routes) and add Auth0 settings to your .env file:

[!TIP]

(It's wise to update .env.example template too. See faithfm/laravel-simple-auth0 package for further details regarding Auth0 configuration, etc.)

• Define the list of allowable Permissions in config/auth.php:

• Assign permissions to users via the user_permissions table:

[!NOTE]

The 'restrictions' column is a JSON field that can optionally be used to define specific restrictions/qualifications to a privilege. Ie: our Media project uses 'filter' and 'fields' to restrict users to editing specific files/fields.

How It Works

• The /login, /logout, /callback routes that enable session-based authentication are documented in laravel-simple-auth0.

• The api_key=XXX token-based authentication is documented in laravel-simple-auth-tokens.
• The Authorization Gates automatically created for all 'defined_permissions' in config/auth.php are documented in laravel-simple-permissions.
• Our User and UserPermission models incorporate the owen-it/laravel-auditing package which is used to audit changes to models across our projects. (This package is a composer dependency.)
• Our learnings from developing an understanding of authentication + authorization - particularly in the context of Laravel + Auth0 have been documented here for what they're worth.

Usage

Our pattern uses non-standard Authentication Guard names for greater clarity and disambiguation:

• 'web' (Laravel default) --> 'web_guard' (v2.2.0) --> 'ffm-session-guard' (v3.0.0) [based on SessionGuard driver]

• 'api' (Laravel default) --> 'api_guard' (v2.2.0) --> 'ffm-token-guard' (v3.0.0) [based on TokenGuard driver]

Authentication Examples:

Apart from that our pattern supports all Laravel's normal authentication (AuthN) methods to check if logged in, protect routes, retrieve a user, etc:

When multiple alternative guards have been specified via middleware (ie: the last example above), all authentication calls inside this route are implicitly resolved using the first authenticated guard that was found: (The middleware calls the shouldUse() method which overrides the configured default guard.)

We also have created an extended auth_guards() helper that allows multiple guards to be specified, since unfortunately neither Laravel's guard() helper nor Auth::guard() facade support multiple guards outside of a middleware-protected-route - ie:

Authorization Examples:

Check for permissions (AuthZ) using the Authorization Gates that have been automatically created for all 'defined_permissions' in config/auth.php:

[!IMPORTANT]

Notice the special '|' character that can be used to test multiple (ORed) permissions in a single gate. This is an extension to Laravel's normal functionality.

More complex restrictions-field checking/filtering has currently only been implemented in the front-end (see next section)... but in the mean-time we could potentially use something like this: (UNTESTED)

Extended Usage: Vue front-end

LaravelUserPermissions.js is a helper library that allows permission-checks to be performed in the front-end.

This helper assumes that user permissions are passed from back-end to front-end using a global javascript LaravelAppGlobals variable (which is usually passed by the Blade file). Specifically it is looking for the existence of the global LaravelAppGlobals.user.permissions property.

Simple permission checks use the laravelUserCan() function:

More complex restrictions checks/filtering uses the laravelUserRestrictions() function:

In the 'restrictions' field example from our Media project above, the restrictions object returned by the laravelUserRestrictions() function would have been:

The value of the status field will be:

• NOT PERMITTED - if the requested permission (ie: "use-app") does not exist for the user.
• ALL PERMITTED - if the requested permission does exist... AND the 'restrictions' field is blank.
• SOME PERMITTED - if the requested permission does exist... AND the 'restrictions' field contains valid JSON data.

The remaining fields (ie: fields and filter in this example) are directly copied from the 'restrictions' JSON data in the database.

[!IMPORTANT]

REMINDER: according to good security practice you should not rely only upon front-end checks to enforce security, but should perform security checks in the back-end too.

Sample code to pass permissions via LaravelAppGlobals to front-end

[^1]: Rationale for moving away from the official Laravel SDK (auth0/login package) provided by Auth0: We developed our own simple Auth0 package for Laravel (in v4.0.0) after spending a many hours re-integrating this pattern (and all of our Laravel apps) to retain compatibility with the changing patterns used in each major update of Auth0's official Laravel package.

Our applications are stateful "PHP Web Applications" (rather than stateless "PHP Backend APIs" interfacing to an SPA with JWTs), and we did not need a lot of the advanced features included in the Laravel SDK - which tended to increase the compexity unnecessarily and proved a source of pain to reintegrate with each major update.

A significant source of pain has been that the "user provider" for the Auth0 package does not (by default) provide a regular Eloquent model... and we found the hard way that many packages (including Laravel Nova) tend to break when something other than a is returned by a user provider.

Recent versions of the Auth0 package have improved compatibiliy for providing genuine Eloquent models, and have removed the need for many of the hacks we had to apply in earlier versions, however after spending many hours creating v3.0.0 of our package to align with improved design patterns in Auth0's package we realised that our User Repository is still building layers of complexity on top of an already-complex solution.

Comparing these many complex layers with the simplicity of Auth0's PHP QuickStart, our laravel-simple-auth0 package now uses Auth0 only to validate a user and provide us a unique 'sub' identifier. This identifier is then used to retrieve a User model... which is passed to Laravel's built-in SessionGuard... which retrieves this same user model for subsequent authentication requests for the duration of a valid session.