PHPackages grantholle/laravel-powerschool-auth - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. grantholle/laravel-powerschool-auth ActiveLibrary[Authentication & Authorization](/categories/authentication) grantholle/laravel-powerschool-auth =================================== Authenticate your Laravel app with PowerSchool 3.2.0(1y ago)0657MITPHPPHP ^8.2 Since Aug 18Pushed 1y ago1 watchersCompare [ Source](https://github.com/grantholle/laravel-powerschool-auth)[ Packagist](https://packagist.org/packages/grantholle/laravel-powerschool-auth)[ RSS](/packages/grantholle-laravel-powerschool-auth/feed)WikiDiscussions main Synced 3w ago READMEChangelog (1)Dependencies (6)Versions (25)Used By (0) Laravel PowerSchool Auth ======================== [](#laravel-powerschool-auth) Use PowerSchool as an identity provider for your Laravel app, supporting the original OpenID 2.0 implementation, as well as OpenID Connect that was introduced in PowerSchool 20.11. OpenID 2.0 are links that are within PowerSchool that are sent to your application to perform a data exchange. It can only be performed from PowerSchool to your app. OpenID Connect is a way for users to authenticate against PowerSchool directly from your application and provides a better user experience overall. Installation ------------ [](#installation) ``` composer require grantholle/laravel-powerschool-auth ``` Configuration ------------- [](#configuration) First publish the config file, `config/powerschool-auth.php`. ``` php artisan vendor:publish --provider="GrantHolle\PowerSchool\Auth\PowerSchoolAuthServiceProvider" ``` The configuration is separated by the different user types, `staff`, `guardian`, and `student`. The OpenID Connect OAuth flow supports four types (`staff`, `teacher`, `parent`, `student`), but for the sake of flexibility `staff` and `teacher` will be merged into the singular `staff` type. The `parent` OIDC persona will reference the `guardian` key in the config. ``` return [ // These are required for OpenID Connect 'server_address' => env('POWERSCHOOL_ADDRESS'), 'client_id' => env('POWERSCHOOL_CLIENT_ID'), 'client_secret' => env('POWERSCHOOL_CLIENT_SECRET'), // User type configuration 'staff' => [ // Setting to false will prevent this user type from authenticating 'allowed' => true, // This is the model to use for a given type // Theoretically you could have different models // for the different user types 'model' => \App\User::class, // These attributes will be synced to your model // PS attribute => your app attribute // Put either OpenID implementation in this // The app will parse whether the key exists in // the response. 'attributes' => [ // These attributes are from OpenID 2.0 'firstName' => 'first_name', 'lastName' => 'last_name', // Shared with 2.0 and Connect 'email' => 'email', // These are OpenID Connect attributes 'given_name' => 'first_name', 'family_name' => 'last_name', ], // The guard used to authenticate your user 'guard' => 'web', // These is the properties used to look up a user's record // OpenID identifier so they can be identified // You will need to have this column already added to // the given model's migration/schema. 'identifying_attributes' => [ 'openid_claimed_id' => 'openid_identity', ], // The path to be redirected to once they are authenticated 'redirectTo' => '', ], // 'guardian' => [ ... // 'student' => [ ... ]; ``` Usage ----- [](#usage) This assumes you have a plugin installed on your instance of PowerSchool with something similar to the following in your `plugin.xml` file. The ``` staff teacher ``` Use the [PowerSchool documentation](https://support.powerschool.com/developer/#/page/three-legged-oauth) for more details on tag and attribute meaning. In short, the `oauth` tag supports configuration about an OpenID Connect OAuth flow, while the `openid` tag has details about OpenID 2.0 authentication. Installing that plugin will inject links in the application popout menu for only staff. Now we need to create a controller that handles authentication with PowerSchool. ### OpenID 2.0 [](#openid-20) First, let's make the OpenID 2.0 authentication controller: ``` php artisan make:controller Auth/PowerSchoolOpenIdLoginController ``` After the controller is generated, we need to add the trait that handles all the authentication boilerplate. ``` namespace App\Http\Controllers\Auth; use App\Http\Controllers\Controller; use GrantHolle\PowerSchool\Auth\Traits\AuthenticatesUsingPowerSchoolWithOpenId; class PowerSchoolOpenIdLoginController extends Controller { use AuthenticatesUsingPowerSchoolWithOpenId; } ``` Now let's add the applicable routes to your `web.php` file: ``` // These paths can be whatever you want; the key thing is that they path for `authenticate` // matches what you've configured in your plugin.xml file for the `path` attribute Route::get('/auth/powerschool/openid', [\App\Http\Controllers\Auth\PowerSchoolOpenIdLoginController::class, 'authenticate']); Route::get('/auth/powerschool/openid/verify', [\App\Http\Controllers\Auth\PowerSchoolOpenIdLoginController::class, 'login']) ->name('openid.verify'); ``` By default, the verification route back to PowerSchool is expected to be `/auth/powerschool/openid/verify`, but that can be changed by overwriting `getVerifyRoute()` as discussed below. Once the user opens your SSO link in PowerSchool, there will be the OpenID exchange and data will be given to your app from PowerSchool. There are several "hooks" where you can change the behavior without having to modify the underlying behavior itself. Here is a snippet of the functions and their default behavior you can overwrite in your controller. ``` namespace App\Http\Controllers\Auth; use App\Http\Controllers\Controller; use GrantHolle\PowerSchool\Auth\Traits\AuthenticatesUsingPowerSchoolWithOpenId; class PowerSchoolOpenIdLoginController extends Controller { use AuthenticatesUsingPowerSchoolWithOpenId; /** * This will get the route to the `login` function after * the authentication request has been sent to PowerSchool * * @return string */ protected function getVerifyRoute(): string { return url('/auth/powerschool/openid/verify'); } /** * This will get the route that should be used after successful authentication. * The user type (staff/guardian/student) is sent as the parameter. * * @param string $userType * @return string */ protected function getRedirectToRoute(string $userType): string { $config = config("powerschool-auth.{$userType}"); return isset($config['redirectTo']) && !empty($config['redirectTo']) ? $config['redirectTo'] : '/home'; } /** * If a user type has `'allowed' => false` in the config, * this is the response to send for that user's attempt. * * @return \Illuminate\Http\Response */ protected function sendNotAllowedResponse() { return response('Forbidden', 403); } /** * Gets the default attributes to be filled for the user * that wouldn't be included in the data exchange with PowerSchool * or that need some custom logic that can't be configured. * The attributes set in the config's `attributes` key will overwrite * these if they are the same. `$data` in this context is the data * received from PowerSchool. For example, you may want to store * the dcid of the user being authenticated. * * @param \Illuminate\Http\Response $request * @param \Illuminate\Support\Collection $data * @return array */ protected function getDefaultAttributes($request, $data): array { return []; } /** * The user has been authenticated. * You can return a custom response here, perform custom actions, etc. * Otherwise, you can change the route in `getRedirectToRoute()`. * * @param \Illuminate\Http\Request $request * @param mixed $user * @param \Illuminate\Support\Collection $data * @return mixed */ protected function authenticated($request, $user, $data) { // } } ``` ### OpenID Connect [](#openid-connect) **Note**: This requires a PowerSchool version of 20.11 or newer. OpenID Connect (OIDC) provides a better experience from your application to use PowerSchool as an Identity Provider. You can send a user from your app to their PowerSchool server to authenticate, then back to your app with some information. For OIDC to work, you must include these keys in your `.env`: ``` POWERSCHOOL_ADDRESS= POWERSCHOOL_CLIENT_ID= POWERSCHOOL_CLIENT_SECRET= ``` You will notice that these are shared with the [grantholle/powerschool-api](https://github.com/grantholle/powerschool-api) to avoid duplication. Next, we'll need to create another controller: ``` php artisan make:controller Auth/PowerSchoolOidcLoginController ``` After the controller is generated, we need to add the trait that handles all the authentication boilerplate. ``` namespace App\Http\Controllers\Auth; use App\Http\Controllers\Controller; use GrantHolle\PowerSchool\Auth\Traits\AuthenticatesUsingPowerSchoolWithOidc; class PowerSchoolOidcLoginController extends Controller { use AuthenticatesUsingPowerSchoolWithOidc; } ``` Now let's add the applicable routes to your `web.php` file: ``` // These paths can be whatever you want; the key thing is that they path for the `login` route action to // match what you've configured in your plugin.xml under `oauth`'s `redirect-uri` attribute file for the `path` attribute Route::get('/auth/powerschool/oidc', [\App\Http\Controllers\Auth\PowerSchoolOidcLoginController::class, 'authenticate']); Route::get('/auth/powerschool/oidc/verify', [\App\Http\Controllers\Auth\PowerSchoolOidcLoginController::class, 'login']); //