This package is not installable via Composer 1.x, please make sure you upgrade to Composer 2+. Read more about our Composer 1.x deprecation policy.

Adds ULS authentication support to your application

v1.0.5 2018-02-21 08:40 UTC

This package is auto-updated.

Last update: 2021-07-17 12:28:38 UTC


PHP from Packagist Latest Stable Version Total Downloads GitHub license GitHub issues


Provides a wrapper around the web-token libraries for use with VATUSA's Unified Login Scheme.


  1. Require the vatusa/laravel-uls package in your composer.json and update your dependencies:
    $ composer require vatusa/laravel-uls
  2. Generate the configuration file


The defaults are set in config/uls.php. Copy this file to your own config directory to modify the values. You can publish the config using this command:

$ php artisan vendor:publish --provider="VATUSA\Uls\UlsServiceProvider"
return [
    | Laravel ULS

     * ULS Version to use
     * By default we'll use 2
    'version' => env('ULS_VERSION', 2),

     * Set the JSON Web Key retrieved from VATUSA's Facility Management
    'jwk' => json_decode(env('ULS_JWK', []), true),

     * Facility 3 letter identifier
    'facility' => env('ULS_FACILITY', 'ZZZ')


On Laravel Lumen, load your configuration file manually in bootstrap/app.php:



Using laravel-uls is fairly easy.

  1. Get your JSON Web Key from your facility's Technical Configuration page. (NOTE: You must hold a ATM, DATM or WM role for that facility to generate/see the generated JSON Web Key)

  2. Store the JWK, unedited, in the config above (or, recommended quoted with single quotes in the .env file as ULS_JWK='... JWK from VATUSA...')

  3. To generate the redirect url, use:


    To handle the developmental returns, specify a boolean argument of true

  4. To verify a token, assume $token is the full token received from VATUSA's ULS endpoint

    $uls = new Uls();
    if ($uls->verifyToken($token)) {
       // Token was true

    The laravel-uls library conducts header verifications to ensure that the accepted algorithms are received. Additionally, it conducts the following claims checks, including:

    • Ensures the audience is you (IE, the token isn't meant for another facility)
    • The token is not expired
    • The Issued at time is logical (ie, not in the future)

    Because of this, a number of exceptions may be thrown:

    • InvalidArgumentException
    • Jose\Component\Checker\InvalidClaimException
    • Jose\Component\Checker\InvalidHeaderException
  5. To get the information of the user associated with the token, use:


    This will return an array of the decoded JSON from ULS. Details of the array can be found in the VATUSA Technical Manual M1022 at


Released under the GNU Public License 3.0, see LICENSE.