Download the PHP package grantholle/laravel-powerschool-auth without Composer

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

Configuration

First publish the config file, config/powerschool-auth.php.

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.

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

Use the PowerSchool documentation 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

First, let's make the OpenID 2.0 authentication controller:

After the controller is generated, we need to add the trait that handles all the authentication boilerplate.

Now let's add the applicable routes to your web.php file:

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.

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:

You will notice that these are shared with the grantholle/powerschool-api to avoid duplication.

Next, we'll need to create another controller:

After the controller is generated, we need to add the trait that handles all the authentication boilerplate.

Now let's add the applicable routes to your web.php file:

Now when users visit /auth/powerschool/oidc in your application, the OAuth flow begins with PowerSchool. If the user is already logged in to PowerSchool, it seamlessly logs in without interruption. If they aren't logged in to PowerSchool, they are brought to a prompt in PowerSchool to log in via admin, teachers, parents, or students, depending on your configuration in your plugin. Be sure to read the docs on the allow-persona sub elements in the docs for the ability to restrict the user types that can authenticate. You may also pass a persona or _persona query variable to tell PowerSchool the type of user that is authenticating. This will allow PowerSchool to bypass the user type prompt and go directly to the desired login page. For example:

The above link will tell PowerSchool that a parent is authenticating, so it can take them directly to the /public login page. You can also allow for longer authenticated sessions by adding a remember query variable with a truthy value, such as 1 or true. By default, it is false. For example:

Just like the OpenID 2.0 "hook" functionality, the OIDC trait has the same ability to modify user attributes and other behavior.

Caveats

Right now there is no SAML integration because it's considerably more complicated to include. There also is the question, why add it if OpenID works? It's more configurable, but also adds a lot more complexity. I'm willing to add it once I have the bandwidth and will certainly entertain a pull request to include it.

That being said, PowerSchool doesn't support the <identityAttribute/> configuration to customize the user's identity attribute. For OpenID 2.0, as far as I can tell, it defaults to {url}/oid/{usertype}/{username}. In our company we have experienced unwanted behavior if the username contains weird characters. For example, it's valid in PowerSchool to have Chinese/Korean usernames. The identifier that gets sent is just encoded spaces, i.e. {url}/oid/guardian/%20%20%20. For some reason email addresses work ok, thankfully.

This also means that if a user's username changes who has already authenticated in your application, they will be authenticated as a new user because their OpenID identifier has also changed. For this reason you may want to configure a different attribute, such as email, to be used as the identifying attribute. It depends on whether you expect emails or usernames to change more often.

For OpenID Connect, there is an included sub attribute. According to the docs:

It is the unique and unchanging identifier for the authenticated user, which will never be reused for any future users.

This sounds as if it will always be unique despite the username, as is the problem with OpenID 2.0. However, if there are shared user accounts (staff have a parent account), those accounts would be separate. This is why often times I will use email despite the potential risks. OpenID Connect also excludes student IDs for guardians and admin schools for staff, which is unfortunate. You will have to provide your own PowerQuery for getting that information based on the user.

If you do use email, I would suggest leaving the entry for email in attribute_transformers that returns the email address in a lowercase format. This way, it doesn't matter how the format it came to our application as it will be normalized in our own database.

The attribute_transformers classes only need to have an __invoke() magic method that accepts the original value as the argument.

Example data

Here are examples of the attribute exchange from PowerSchool:

OpenID 2.0:

OpenID Connect:

License

MIT