Update UserProvider API

[evansims]

Changes

This PR includes changes to the UserProvider API to ease host applications in implementing their own User model types. The new default user model provided by the library only includes the normalized user data returned with the authenticated session or provided access token. The StateInstance now keeps track of associated tokens, scopes and expiration states.

To implement your own UserProvider:

1. Update your Laravel 8+ application's config/auth.php file. Within the Auth0 provider, assign a custom repository value pointing to your user provider class. For example:

    'providers' => [
        //...

        'auth0' => [
            'driver' => 'auth0',
            'repository' => App\Auth\CustomUserRepository::class
        ],
    ],

3. Your application's custom user provider should look something like this:

<?php

declare(strict_types=1);

namespace App\Auth;

class CustomUserRepository implements \Auth0\Laravel\Contract\Auth\User\Repository
{
    /**
     * @inheritdoc
     */
    public function fromSession(
        array $user
    ): ?\Illuminate\Contracts\Auth\Authenticatable {
        return new \App\Models\User([
            'id' => $user['sub'] ?? $user['user_id'] ?? null,
            'name' => $user['name'],
            'email' => $user['email']
        ]);
    }

    /**
     * @inheritdoc
     */
    public function fromAccessToken(
        array $user
    ): ?\Illuminate\Contracts\Auth\Authenticatable {
        // Simliar to above. Used for stateless application types.
        return null;
    }
}

4. Your application's user model must implement Illuminate\Contracts\Auth\Authenticatable to be compatible with Laravel's Guard API, and this library. It must also implement either Auth0\Laravel\Contract\Model\Stateful\User or Auth0\Laravel\Contract\Model\Stateless\User depending on your application use case. For example:

<?php

declare(strict_types=1);

namespace App\Models;

use Auth0\Laravel\Contract\Model\Stateful\User as StatefulUser;
use Illuminate\Auth\Authenticatable;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableUser;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Notifications\Notifiable;

class User extends \Illuminate\Database\Eloquent\Model implements StatefulUser, AuthenticatableUser
{
    use HasFactory, Notifiable, Authenticatable;

    /**
     * The primary identifier for the user.
     *
     * @var string
     */
    protected $primaryKey = 'id';

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'id',
        'name',
        'email',
    ];

    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array<int, string>
     */
    protected $hidden = [];

    /**
     * The attributes that should be cast.
     *
     * @var array<string, string>
     */
    protected $casts = [];
}

Note: As state request data has been moved out of the returned user model, you should now query the StateInstance from within your application for this data. For example:

$state = app()->make(\Auth0\Laravel\StateInstance::class);
echo $state->getAccessToken();