VATUSA ULS Handling for Laravel 5.x

About

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

Installation

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

Configuration

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')
];

Lumen

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

$app->configure('uls');

Usage

Using laravel-uls is fairly easy.

1. Get your JSON Web Key from your facility's Technical Configuration page. https://www.vatusa.net/mgt/facility (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:

   $uls->redirectUrl()

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

   $uls->redirectUrl(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:

   $uls->getInfo();

   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 https://www.vatusa.net.

License

Released under the GNU Public License 3.0, see LICENSE.