Implement a custom driver for Laravel Socialite

Laravel Socialite is an official Laravel package to authenticate with OAuth providers. It supports authentication with Facebook, Twitter, LinkedIn, Google, GitHub, and Bitbucket. But, what if you want to use a different driver?

In our case we want to use AWS Cognito as an authentication provider. AWS Cognito allows you to authenticate using different providers, and stores centralized user data which you can use for different applications.

So, the first thing is to install Laravel Socialite, like this:

composer require laravel/socialite

Now, we create a CognitoProvider class which extends from \Socialite\Two\AbstractProvider. We need to implement the next methods, so the driver work as expected:

// ...
use Laravel\Socialite\Two\AbstractProvider;
 
class SocialiteCognitoProvider extends AbstractProvider
{
 
    protected function getAuthUrl($state)
    {
        // TODO: Implement getAuthUrl() method.
    }
 
    protected function getTokenUrl()
    {
        // TODO: Implement getTokenUrl() method.
    }
 
    protected function getUserByToken($token)
    {
        // TODO: Implement getUserByToken() method.
    }
 
    protected function mapUserToObject(array $user)
    {
        // TODO: Implement mapUserToObject() method.
    }
}

From the Laravel Socialite docs, we have to create a redirect route, which basically calls the redirect() method from the selected driver, like this:

use Laravel\Socialite\Facades\Socialite;
 
Route::get('/auth/redirect', function () {
    return Socialite::driver('cognito')->redirect();
});

This redirect() method calls getAuthUrl() method under the hood where the user is redirected to the third-party provider authentication page. So, we need to provide this url in this method. We also extract how we get the base url in a different method, as we are going to use it in different places:

/**
 * @return string
 */
public function getCognitoUrl()
{
    return config('services.cognito.base_uri') . '/oauth2';
}
 
/**
 * @param string $state
 *
 * @return string
 */
protected function getAuthUrl($state)
{
    return $this->buildAuthUrlFromBase($this->getCognitoUrl() . '/authorize', $state);
}

The internal buildAuthUrlFromBase() method builds the authentication url with all the necessary parameters.

Once the user is authenticated on the third-party provider, they are redirected to the callback url that we define in our application. It depends on what you want to do on this controller method, but you will probably call the user() socialite method, like this:

Route::get('/auth/callback', function () {
    $user = Socialite::driver('cognito')->user();
 
    // $user->token
});

When you call this method, it calls the getTokenUrl() method to get the access token with the given code from the callback url params. So we need to provide this url:

/**
 * @return string
 */
protected function getTokenUrl()
{
    return $this->getCognitoUrl() . '/token';
}

Now that we have the access token we can get the authenticated user, which we'll do in the getUserByToken() method. In our case, we need to do a POST request like this:

/**
 * @param string $token
 *
 * @throws GuzzleException
 *
 * @return array|mixed
 */
protected function getUserByToken($token)
{
    $response = $this->getHttpClient()->post($this->getCognitoUrl() . '/userInfo', [
        'headers' => [
            'cache-control' => 'no-cache',
            'Authorization' => 'Bearer ' . $token,
            'Content-Type' => 'application/x-www-form-urlencoded',
        ],
    ]);
 
    return json_decode($response->getBody()->getContents(), true);
}

Finally, we get a user object from the previous method, and we need to map this object into a new User class. In our case, we use Laravel\Socialite\Two\User, and map to the User with mapUserToObject(), like this:

/**
 * @return User
 */
protected function mapUserToObject(array $user)
{
    return (new User())->setRaw($user)->map([
        'id' => $user['sub'],
        'email' => $user['email'],
        'username' => $user['username'],
        'email_verified' => $user['email_verified'],
        'family_name' => $user['family_name'],
    ]);
}

Now, in your callback() method, you could do something like this:

Route::get('/auth/callback', function () {
    try {
        $cognitoUser = Socialite::driver('cognito')->user();
        $user = User::query()->whereEmail($cognitoUser->email)->first();
 
        if (!$user) {
            return redirect('login');
        }
 
        Auth::guard('web')->login($user);
 
        return redirect(route('home'));
    } catch (Exception $exception) {
        return redirect('login');
    }
});

Depending on the provider, you might need to add some scopes to the authentication request. The scopes are a mechanism to limit the access of an user to an application.

In AWS Cognito, there are system reserved scopes, these scopes are openid, email, phone, profile, and aws.cognito.signin.user.admin. To know more about these scopes, check here. You can also create custom scopes in Cognito, check here for more information.

In the SocialiteCognitoProvider class, you can define custom scopes by overriding the $scopes and $scopeSeparator internal variables like this:

class SocialiteCognitoProvider extends AbstractProvider
{
    /**
    * @var string[]
    */
    protected $scopes = [
        'openid',
        'profile',
        'aws.cognito.signin.user.admin',
    ];
 
    /**
    * @var string
    */
    protected $scopeSeparator = ' ';
 
    // ...
}

To know more about the AWS Cognito scopes, check the official docs here.

The final class will look like this:

// ...
 
use Laravel\Socialite\Two\User;
use GuzzleHttp\Exception\GuzzleException;
use Laravel\Socialite\Two\AbstractProvider;
 
class SocialiteCognitoProvider extends AbstractProvider
{
    /**
     * @var string[]
     */
    protected $scopes = [
        'openid',
        'profile',
        'aws.cognito.signin.user.admin',
    ];
 
    /**
     * @var string
     */
    protected $scopeSeparator = ' ';
 
    /**
     * @return string
     */
    public function getCognitoUrl()
    {
        return config('services.cognito.base_uri') . '/oauth2';
    }
 
    /**
     * @param string $state
     *
     * @return string
     */
    protected function getAuthUrl($state)
    {
        return $this->buildAuthUrlFromBase($this->getCognitoUrl() . '/authorize', $state);
    }
 
    /**
     * @return string
     */
    protected function getTokenUrl()
    {
        return $this->getCognitoUrl() . '/token';
    }
 
    /**
     * @param string $token
     *
     * @throws GuzzleException
     *
     * @return array|mixed
     */
    protected function getUserByToken($token)
    {
        $response = $this->getHttpClient()->post($this->getCognitoUrl() . '/userInfo', [
            'headers' => [
                'cache-control' => 'no-cache',
                'Authorization' => 'Bearer ' . $token,
                'Content-Type' => 'application/x-www-form-urlencoded',
            ],
        ]);
 
        return json_decode($response->getBody()->getContents(), true);
    }
 
    /**
     * @return User
     */
    protected function mapUserToObject(array $user)
    {
        return (new User())->setRaw($user)->map([
            'id' => $user['sub'],
            'email' => $user['email'],
            'username' => $user['username'],
            'email_verified' => $user['email_verified'],
            'family_name' => $user['family_name'],
        ]);
    }
}

But, how does Socialite recognize the driver? We need to add some code in the AppServiceProvider:

// ...
use Laravel\Socialite\Contracts\Factory;
 
/**
 * @throws BindingResolutionException
 */
public function boot()
{
    $socialite = $this->app->make(Factory::class);
 
    $socialite->extend('cognito', function () use ($socialite) {
        $config = config('services.cognito');
 
        return $socialite->buildProvider(SocialiteCognitoProvider::class, $config);
    });
}

In the boot method, we register our driver in the Socialite manager, so when we call Socialite::driver('cognito') it instantiates our SocialiteCognitoProvider class.

And that’s it! This is how you implement a new custom driver for Laravel Socialite. To make your life easier, we created a small package for the custom Cognito driver, that you can check here.