aaronosher / php-uls
Adds VATUSA ULS authentication support to your application
Requires
- php: >=7.1.0
- namshi/jose: ^7.0
- psr/log: ^1.0
- web-token/jwt-checker: ^1.0
- web-token/jwt-core: ^1.0
- web-token/jwt-key-mgmt: ^1.0
- web-token/jwt-signature: ^1.0
Requires (Dev)
- phpunit/phpunit: ^4.8|^5.2
- squizlabs/php_codesniffer: ^2.3
This package is not auto-updated.
Last update: 2025-03-02 06:08:11 UTC
README
About
Provides a wrapper around the web-token libraries for use with VATUSA's Unified Login Scheme.
Installation
- Require the
vatusa/php-uls
package in yourcomposer.json
and update your dependencies:$ composer require vatusa/laravel-uls
- Generate the configuration file
Configuration
For php-uls to work you need to configure your jwk, uls version, and facility id. These are set through an options array in the constructor:
$options = [ "version" => 2, "jwk" => $jwk, "facility" => "ZZZ" ]; $uls = new \Vatusa\Uls\Uls($options);
Usage
Using laravel-uls is fairly easy.
-
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)
-
Store the JWK, unedited, in the config above (or, recommended quoted with single quotes in the .env file as ULS_JWK='... JWK from VATUSA...')
-
To generate the redirect url, use:
$uls->redirectUrl()
To handle the developmental returns, specify a boolean argument of true
$uls->redirectUrl(true)
-
To verify a token, assume $token is the full token received from VATUSA's ULS endpoint
$uls = new Uls($options); 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
-
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.