authkit2/docs/LARAVEL_USAGE.md

authkit2 - Laravel Usage

How to use authkit2 in your Laravel project.

This requires that you have installed and configured authkit2.

Basic Usage

For basic usage in a new application there's nothing more to do. authkit2 integrates with the default Laravel authentication system and will work out of the box to sign users in and out of your application.

You can explicitly trigger a login or logout by redirecting to:

• /auth/login and
• /auth/logout

Events

Your application will be notified of logins, logins, and new users (to your application) through Laravel Events.

• UserRegistration
• UserLogin
• UserLogout

UserRegistration

This event is fired when a user authenticated that has not previously authenticated through the OIDC provider. The event is passed the fields returned by the OIDC provider (e.g., email, name).

If a listener is registered, it is expected to return an instance of your User model, initialized and saved, that will be tied to the OIDC ID the user has authenticated with.

For example, a minimal implementation to recreate the default behaviour would be:

	public function handle($event)
	{
		$user = new \App\Models\User();
		$user->name = $event->fields['name'];
		$user->email = $event->fields['email'];
		$user->save();
		return $user;
	}

If you wanted an implementation to help migrate existing users to OIDC users, something like the following may work:

	public function handle($event)
	{
		// Try and load an existing user with the given email address
		$user = \App\Models\User::where('email', $event->fields['email'])->first();

		if (!isset($user))
		{
			// If that user wasn't found, this is an entirely new user
			$user = new \App\Models\User();
			$user->name = $event->fields['name'];
			$user->email = $event->fields['email'];
			$user->save();
			return $user;
		}
		else
		{
			// If the user was found, then we can tie them to the OIDC
			// user.
			$user->name = $event->fields['name'];
			$user->email = $event->fields['email'];
			// Clear the user's password to prevent non-OIDC logins going
			// forward.
			$user->password = null;
			$user->save();
			return $user;
		}
	}

UserLogin

This event is fired when a user is authenticated (whether an existing user, or after a UserRegistration event). The event is passed the user model and the fields returned by the OIDC provider (e.g., email, name).

If a listener is registered, it is expected to update the user model with any updated fields returned by the OIDC provider.

For example, a minimal implementation to recreate the default behaviour would be:

	public function handle($event)
	{
		$user = $event->user;
		$user->name = $event->fields['name'];
		$user->email = $event->fields['email'];
		$user->save();
	}

UserLogout

This event is fired when the user tries to log out of your application. The event is fired before the user is logged out of the Laravel authentication system or redirected to the OIDC provider to logout.