Laravel Authentication with AWS Cognito

Introduction

Laravel already comes with a powerful authentication feature which we all know and love right? You simply execute the following command, and have authentication working:

1
2php artisan make:auth
3

That's super easy and will not require any actual programming. For most projects, this will be enough. You can register, login, have your password reset and you have a remember me feature. Actually, that's enough for most use cases, but let's start by defining a use case where it is not enough: What if we want to give a user, registered in Project A, access to Project B or the other way round? Well, sadly Laravel doesn't come with a built-in Single Sign-On feature (check Laravel Socialite for authentication with Facebook, Twitter, LinkedIn, Google, GitHub and Bitbucket), but its actually pretty easy to implement one ourselves.

During this post, we will dive into the authentication functionality and how it works behind the scene. We will also implement a Single Sign On, which will solve our use case.

AWS Cognito

Cognito is a powerful Authentication handler provided by AWS. We will use it in the background to store all of our user credentials and identifications.

To set up a Cognito user pool, log into your management console and navigate to Cognito. Oh, great news by the way. Cognito is 100% free for up to 50.000 monthly active users.

Once you are on the Cognito page, click Create a user pool. It is actually pretty easy to set up, so we won't walk through the whole process here.

IMPORTANT: Don't forget to activate the checkbox to Enable sign-in API for server-based Authentication.
The Auth Flow is called: ADMIN_NO_SRP_AUTH

So now that we have set up a valid Cognito Pool we can go into our Laravel project.

At this point, we cannot communicate with AWS. We could implement their API by ourselves using Guzzle or Zttp as a Guzzle wrapper, but this would be too much work for our task.

Luckily AWS provides a PHP SDK which we can require using composer:

1
2composer require aws/aws-sdk-php
3

Once installed the SDK will give us a Client which we can use for the API communication: CognitoIdentityProviderClient.

By implementing the authentication functionality we will build a CognitoClient which we can then easily use in our controller.

Laravel Authentication Setup

Okay, so as already mentioned in the introduction, it is pretty easy to get authentication up and running in Laravel. Let's dive into it.

What does the make:auth command actually do? First of all, it creates the needed directories were it will store the authentication files which we can edit later.

They are located in the following directories:

• resources/views/auth
• resources/views/layouts

All files you get from those two directories are copied from the make:auth command.

Additionally, we get a HomeController plus some AuthControllers.

To activate the new routes, Laravel automatically appends an Auth::routes() call to your routes/web.php file. Now we got all the scaffolding done and our authentication is up and running.

With just one call from the command line, we created views, a controller, and routes. That's just awesome. Let's have a deeper look at the registration process.

Registration

As we all know, the registration process starts in the RegistrationController we have previously created. Normally, after the user enters valid credentials into the form, we will create the new User object and store it into the database. Ok, you might ask yourself, how am I able to push the user into our Cognito Pool?

The answer is easy. We need to add a little programming logic of our own.

First, we create a class called CognitoClient under app\Cognito. Once it's developed, it will look like this:

1<?php
2namespace App\Cognito;
3
4use Aws\CognitoIdentityProvider\CognitoIdentityProviderClient;
5use Aws\CognitoIdentityProvider\Exception\CognitoIdentityProviderException;
6use Illuminate\Support\Facades\Password;
7use Illuminate\Support\Str;
8
9class CognitoClient
10{
11    const NEW_PASSWORD_CHALLENGE = 'NEW_PASSWORD_REQUIRED';
12    const FORCE_PASSWORD_STATUS  = 'FORCE_CHANGE_PASSWORD';
13    const RESET_REQUIRED         = 'PasswordResetRequiredException';
14    const USER_NOT_FOUND         = 'UserNotFoundException';
15    const USERNAME_EXISTS        = 'UsernameExistsException';
16    const INVALID_PASSWORD       = 'InvalidPasswordException';
17    const CODE_MISMATCH          = 'CodeMismatchException';
18    const EXPIRED_CODE           = 'ExpiredCodeException';
19
20    /**
21     * @var CognitoIdentityProviderClient
22     */
23    protected $client;
24
25    /**
26     * @var string
27     */
28    protected $clientId;
29
30    /**
31     * @var string
32     */
33    protected $clientSecret;
34
35    /**
36     * @var string
37     */
38    protected $poolId;
39
40    /**
41     * CognitoClient constructor.
42     * @param CognitoIdentityProviderClient $client
43     * @param string $clientId
44     * @param string $clientSecret
45     * @param string $poolId
46     */
47    public function __construct(
48        CognitoIdentityProviderClient $client,
49        $clientId,
50        $clientSecret,
51        $poolId
52    ) {
53        $this->client       = $client;
54        $this->clientId     = $clientId;
55        $this->clientSecret = $clientSecret;
56        $this->poolId       = $poolId;
57    }
58
59    /**
60     * Checks if credentials of a user are valid
61     *
62     * @see http://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html
63     * @param string $email
64     * @param string $password
65     * @return \Aws\Result|bool
66     */
67    public function authenticate($email, $password)
68    {
69        try
70        {
71            $response = $this->client->adminInitiateAuth([
72                'AuthFlow'       => 'ADMIN_NO_SRP_AUTH',
73                'AuthParameters' => [
74                    'USERNAME'     => $email,
75                    'PASSWORD'     => $password,
76                    'SECRET_HASH'  => $this->cognitoSecretHash($email)
77                ],
78                'ClientId'   => $this->clientId,
79                'UserPoolId' => $this->poolId
80            ]);
81        }
82        catch (CognitoIdentityProviderException $exception)
83        {
84            if ($exception->getAwsErrorCode() === self::RESET_REQUIRED ||
85                $exception->getAwsErrorCode() === self::USER_NOT_FOUND) {
86                return false;
87            }
88
89            throw $exception;
90        }
91
92        return $response;
93    }
94
95    /**
96     * Registers a user in the given user pool
97     *
98     * @param $email
99     * @param $password
100     * @param array $attributes
101     * @return bool
102     */
103    public function register($email, $password, array $attributes = [])
104    {
105        $attributes['email'] = $email;
106
107        try
108        {
109            $response = $this->client->signUp([
110                'ClientId' => $this->clientId,
111                'Password' => $password,
112                'SecretHash' => $this->cognitoSecretHash($email),
113                'UserAttributes' => $this->formatAttributes($attributes),
114                'Username' => $email
115            ]);
116        }
117        catch (CognitoIdentityProviderException $e) {
118            if ($e->getAwsErrorCode() === self::USERNAME_EXISTS) {
119                return false;
120            }
121
122            throw $e;
123        }
124
125        $this->setUserAttributes($email, ['email_verified' => 'true']);
126
127        return (bool) $response['UserConfirmed'];
128    }
129
130    /**
131     * Send a password reset code to a user.
132     * @see http://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html
133     *
134     * @param  string $username
135     * @return string
136     */
137    public function sendResetLink($username)
138    {
139        try {
140            $result = $this->client->forgotPassword([
141                'ClientId' => $this->clientId,
142                'SecretHash' => $this->cognitoSecretHash($username),
143                'Username' => $username,
144            ]);
145        } catch (CognitoIdentityProviderException $e) {
146            if ($e->getAwsErrorCode() === self::USER_NOT_FOUND) {
147                return Password::INVALID_USER;
148            }
149
150            throw $e;
151        }
152
153        return Password::RESET_LINK_SENT;
154    }
155
156    # HELPER FUNCTIONS
157
158    /**
159     * Set a users attributes.
160     * http://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html
161     *
162     * @param string $username
163     * @param array  $attributes
164     * @return bool
165     */
166    public function setUserAttributes($username, array $attributes)
167    {
168        $this->client->AdminUpdateUserAttributes([
169            'Username' => $username,
170            'UserPoolId' => $this->poolId,
171            'UserAttributes' => $this->formatAttributes($attributes),
172        ]);
173
174        return true;
175    }
176
177
178    /**
179     * Creates the Cognito secret hash
180     * @param string $username
181     * @return string
182     */
183    protected function cognitoSecretHash($username)
184    {
185        return $this->hash($username . $this->clientId);
186    }
187
188    /**
189     * Creates a HMAC from a string
190     *
191     * @param string $message
192     * @return string
193     */
194    protected function hash($message)
195    {
196        $hash = hash_hmac(
197            'sha256',
198            $message,
199            $this->clientSecret,
200            true
201        );
202
203        return base64_encode($hash);
204    }
205
206    /**
207     * Get user details.
208     * http://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html
209     *
210     * @param  string $username
211     * @return mixed
212     */
213    public function getUser($username)
214    {
215        try {
216            $user = $this->client->AdminGetUser([
217                'Username' => $username,
218                'UserPoolId' => $this->poolId,
219            ]);
220        } catch (CognitoIdentityProviderException $e) {
221            return false;
222        }
223
224        return $user;
225    }
226
227    /**
228     * Format attributes in Name/Value array
229     *
230     * @param  array $attributes
231     * @return array
232     */
233    protected function formatAttributes(array $attributes)
234    {
235        $userAttributes = [];
236
237        foreach ($attributes as $key => $value) {
238            $userAttributes[] = [
239                'Name' => $key,
240                'Value' => $value,
241            ];
242        }
243
244        return $userAttributes;
245    }
246}

Now we have a client, which can actually talk to Cognito. since we have some dependencies in this, we want to turn it into a singleton service, so what we are going to do, is create a CognitoAuthServiceProvider.

1<?php
2namespace App\Providers;
3
4use App\Auth\CognitoGuard;
5use App\Cognito\CognitoClient;
6use Illuminate\Support\ServiceProvider;
7use Illuminate\Foundation\Application;
8use Aws\CognitoIdentityProvider\CognitoIdentityProviderClient;
9
10class CognitoAuthServiceProvider extends ServiceProvider
11{
12    public function boot()
13    {
14        $this->app->singleton(CognitoClient::class, function (Application $app) {
15            $config = [
16                'credentials' => config('cognito.credentials'),
17                'region'      => config('cognito.region'),
18                'version'     => config('cognito.version')
19            ];
20
21            return new CognitoClient(
22                new CognitoIdentityProviderClient($config),
23                config('cognito.app_client_id'),
24                config('cognito.app_client_secret'),
25                config('cognito.user_pool_id')
26            );
27        });
28  
29    }
30}

‍And finally, add this ServiceProvider to your config\app.php file to activate it. Now that we have our Cognito Client available in the application, we want to use it in the RegisterController. So let's copy the register function from the trait, and slightly adjust it to fit our needs.

1public function register(Request $request)
2    {
3        $this->validator($request->all())->validate();
4
5        $attributes = [];
6
7        $userFields = ['name', 'email'];
8
9        foreach($userFields as $userField) {
10
11            if ($request->$userField === null) {
12                throw new \Exception("The configured user field $userField is not provided in the request.");
13            }
14
15            $attributes[$userField] = $request->$userField;
16        }
17
18        app()->make(CognitoClient::class)->register($request->email, $request->password, $attributes);
19
20        event(new Registered($user = $this->create($request->all())));
21
22        return $this->registered($request, $user)
23            ?: redirect($this->redirectPath());
24    }

‍We first validate the user post data, go through the user fields we want to store in Cognito, and extract them from our request. Then create a new CognitoClient Singleton and call its register with the values.

When you register now in your Laravel App you should have the first user in your Cognito pool. Congratulations!

Let's move on to the Login logic.

Login

To be able to let the user login via Cognito, we need to adjust the way Laravel authenticates the user. You will be able to adjust it in the config\auth.php file. Currently, it looks like this:

1'guards' => [
2        'web' => [
3            'driver' => 'session',
4            'provider' => 'users',
5        ],
6
7        'api' => [
8            'driver' => 'token',
9            'provider' => 'users',
10        ],
11    ],

Laravel works with so-called Guards. One guard has the responsibility to authenticate the user by its given credentials and perform the login process, so the user can access the application.

What we want to do now is create a new AuthenticationGuard, so we can use our own Cognito driver.

This can be achieved quite easily.

Let's create a folder called Auth and place it underneath the app directory and create a class called CognitoGuard. This class should extend the SessionGuard from Laravel, and implement the StatefulGuard interface.

In our case it will look like this:

1<?php
2namespace App\Auth;
3
4use App\Cognito\CognitoClient;
5use App\Exceptions\InvalidUserModelException;
6use App\Exceptions\NoLocalUserException;
7use Aws\Result;
8use Illuminate\Auth\SessionGuard;
9use Illuminate\Contracts\Auth\Authenticatable;
10use Illuminate\Contracts\Auth\StatefulGuard;
11use Illuminate\Contracts\Auth\UserProvider;
12use Illuminate\Contracts\Session\Session;
13use Illuminate\Database\Eloquent\Model;
14use Symfony\Component\HttpFoundation\Request;
15
16class CognitoGuard extends SessionGuard implements StatefulGuard
17{
18    /**
19     * @var CognitoClient
20     */
21    protected $client;
22
23    /**
24     * CognitoGuard constructor.
25     * @param string $name
26     * @param CognitoClient $client
27     * @param UserProvider $provider
28     * @param Session $session
29     * @param null|Request $request
30
31     */
32    public function __construct(
33        string $name,
34        CognitoClient $client,
35        UserProvider $provider,
36        Session $session,
37        ?Request $request = null
38    ) {
39        $this->client = $client;
40        parent::__construct($name, $provider, $session, $request);
41    }
42
43    /**
44     * @param mixed $user
45     * @param array $credentials
46     * @return bool
47     * @throws InvalidUserModelException
48     */
49    protected function hasValidCredentials($user, $credentials)
50    {
51        /** @var Result $response */
52        $result = $this->client->authenticate($credentials['email'], $credentials['password']);
53
54        if ($result && $user instanceof Authenticatable) {
55            return true;
56        }
57
58        return false;
59    }
60
61    /**
62     * Attempt to authenticate a user using the given credentials.
63     *
64     * @param  array  $credentials
65     * @param  bool   $remember
66     * @throws
67     * @return bool
68     */
69    public function attempt(array $credentials = [], $remember = false)
70    {
71        $this->fireAttemptEvent($credentials, $remember);
72
73        $this->lastAttempted = $user = $this->provider->retrieveByCredentials($credentials);
74
75        if ($this->hasValidCredentials($user, $credentials)) {
76            $this->login($user, $remember);
77            return true;
78        }
79
80        $this->fireFailedEvent($user, $credentials);
81
82        return false;
83    }
84}

‍‍This looks pretty straightforward and should do the job. What we are doing here is, we are taking the credentials from the login and using the provider to retrieve a user by its credentials. You now see the combination. The guard uses a provider. That's what we saw in the guard config array some lines above.

And this is what a provider definition looks like:

1'providers' => [
2   'users' => [
3       'driver' => 'eloquent',
4       'model' => App\User::class
5   ],
6],

‍The Provider has a driver, which is currently set to eloquent and a model definition, which tells Laravel about the model class it needs to use.

Now we need to make our guard visible to the application and as you might have guessed, we can do so by adapting our boot method from our CognitoAuthServiceProvider.

1<?php
2namespace App\Providers;
3
4use App\Auth\CognitoGuard;
5use App\Cognito\CognitoClient;
6use Illuminate\Support\ServiceProvider;
7use Illuminate\Foundation\Application;
8use Aws\CognitoIdentityProvider\CognitoIdentityProviderClient;
9
10class CognitoAuthServiceProvider extends ServiceProvider
11{
12    public function boot()
13    {
14       // ...
15        $this->app['auth']->extend('cognito', function (Application $app, $name, array $config) {
16            $guard = new CognitoGuard(
17                $name,
18                $client = $app->make(CognitoClient::class),
19                $app['auth']->createUserProvider($config['provider']),
20                $app['session.store'],
21                $app['request']
22            );
23
24            $guard->setCookieJar($this->app['cookie']);
25            $guard->setDispatcher($this->app['events']);
26            $guard->setRequest($this->app->refresh('request', $guard, 'setRequest'));
27
28            return $guard;
29        });
30    }
31}
32

‍Here we are going to extend the Authentication internals from Laravel and create a new driver which we can use in our application. The first parameter is the name we have to set as a driver.

Now set the new driver so your auth config looks like this:

1<?php
2
3return [
4
5    /*
6    |--------------------------------------------------------------------------
7    | Authentication Defaults
8    |--------------------------------------------------------------------------
9    |
10    | This option controls the default authentication "guard" and password
11    | reset options for your application. You may change these defaults
12    | as required, but they're a perfect start for most applications.
13    |
14    */
15
16    'defaults' => [
17        'guard' => 'web',
18        'passwords' => 'users',
19    ],
20
21    /*
22    |--------------------------------------------------------------------------
23    | Authentication Guards
24    |--------------------------------------------------------------------------
25    |
26    | Next, you may define every authentication guard for your application.
27    | Of course, a great default configuration has been defined for you
28    | here which uses session storage and the Eloquent user provider.
29    |
30    | All authentication drivers have a user provider. This defines how the
31    | users are actually retrieved out of your database or other storage
32    | mechanisms used by this application to persist your user's data.
33    |
34    | Supported: "session", "token"
35    |
36    */
37
38    'guards' => [
39        'web' => [
40            'driver' => 'cognito', <--- This is the important line
41            'provider' => 'users',
42        ],
43        'api' => [
44            'driver' => 'token',
45            'provider' => 'users',
46        ],
47    ],
48    'providers' => [
49        'users' => [
50            'driver' => 'eloquent',
51            'model' => App\User::class
52        ]
53    ],
54];

The last step is to adjust the LoginController. For our task, we need to overwrite the basic login functionality as we did in the registration process.

Go to your LoginController and add those to methods:

1public function login(Request $request)
2{
3        $this->validateLogin($request);
4
5        if ($this->hasTooManyLoginAttempts($request)) {
6            $this->fireLockoutEvent($request);
7
8            return $this->sendLockoutResponse($request);
9        }
10
11        try
12        {
13            if ($this->attemptLogin($request)) {
14                return $this->sendLoginResponse($request);
15            }
16        }
17        catch(CognitoIdentityProviderException $c) {
18            return $this->sendFailedCognitoResponse($c);
19        }
20        catch (\Exception $e) {
21            return $this->sendFailedLoginResponse($request);
22        }
23
24        return $this->sendFailedLoginResponse($request);
25    }
26
27    private function sendFailedCognitoResponse(CognitoIdentityProviderException $exception)
28    {
29        throw ValidationException::withMessages([
30            $this->username() => $exception->getAwsErrorMessage(),
31        ]);
32    }
33

Now when you use your credentials, you can log in your user with the new Cognito driver. That's cool!

You can see that it takes quite a bit of time to implement this! Remember our original use case? We wanted to create a single sign-on, so we have to repeat this at least one more time. Now, take a step back and imagine you have 5 projects you want to connect with a single sign-on. This is not maintainable!

So, we decided to create a package which solves all of this work for you, and cut it down to just 5 minutes of work to get it up and running!

Laravel Package to easily manage authentication with AWS Cognito

Let's throw all the work away we have done so far and start from scratch, and I'll show you how easy it is to implement a single sign-on.

To get started you will need to require our package using composer:

1
2composer require black-bits/laravel-cognito-auth
3

Once installed you can go on and publish the config and the view:

1
2php artisan vendor:publish --provider="BlackBits\LaravelCognitoAuth\CognitoAuthServiceProvider"
3

Now move on to your config\auth.php file and activate the new cognito driver like we did before:

1'guards' => [
2    'web' => [
3        'driver' => 'cognito', // This line is important 
4        'provider' => 'users',
5    ],
6    'api' => [
7        'driver' => 'token',
8        'provider' => 'users',
9    ],
10],

‍Add the following fields to your .env file:

1AWS_COGNITO_KEY=
2AWS_COGNITO_SECRET=
3AWS_COGNITO_REGION=
4AWS_COGNITO_CLIENT_ID=
5AWS_COGNITO_CLIENT_SECRET=
6AWS_COGNITO_USER_POOL_ID=

‍Now you walk through the AuthControllers and swap out the Laravel specific traits with our traits. Don't be afraid to do something wrong, they are just called like the ones in Laravel.

1BlackBits\LaravelCognitoAuth\Auth\AuthenticatesUsers
2BlackBits\LaravelCognitoAuth\Auth\RegistersUsers
3BlackBits\LaravelCognitoAuth\Auth\ResetsPasswords
4BlackBits\LaravelCognitoAuth\Auth\SendsPasswordResetEmails

‍And that's it. You have implemented our package and enabled AWS Cognito authentication. Last but not least we want to take care of the Single Sign-On.

Single Sign On

With our package and AWS Cognito, we provide you a simple way to use Single Sign On's. To enable it just go to the cognito.php file in the config directory and set USE_SSO=true. But how does it work?

When you have SSO enabled in your config, and a user tries to log into your application, the cognito client will check if he exists in your Cognito pool. If the user exists he will be created automatically in your database and is logged in simultaneously.

That's what we need the fields sso_user_model and sso_user_fields for. In sso_user_model you define the class of your user model. In most cases, this will simply be App\User.

With sso_user_fields you can define the fields which should be stored in Cognito. Pay attention here! If you define a field which you do not send with the Register Request, it will throw an InvalidUserFieldException and you won't be able to register.

So now you have registered your user with its attributes in the Cognito pool and your local database, and you want to attach a second app which uses the same pool. Well, that's actually pretty easy. You set up your project like you are used to and install our laravel-cognito-auth package. On both sites set USE_SSO=true. Also be sure you entered exactly the same pool id. Now when a user is registered in your other app but not in your second and wants to login he gets created. And that's all you need to do.

Conclusion

Today you've learned how simple it is to spread a single user database over multiple projects.

In the future, we will work on this package to make it even better and more customizable. For the moment you can only log in with an email address, but in the future, we want to make it customizable to be any field of choice.

Let us know what you think.

https://github.com/black-bits/laravel-cognito-auth

‍