authkit2/docs/LARAVEL_USAGE.md

# authkit2 - Laravel Usage

How to use authkit2 in your Laravel project.

This requires that you have [installed](LARAVEL_INSTALL.md) and
[configured](LARAVEL_CONFIG.md) 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](https://laravel.com/docs/master/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:

```php
	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:

```php
	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:

```php
	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.