About a year ago, I began looking for new ways to deal with my users.  I really hated creating user tables and taking care of the security of my users.  I came across Stormpath via an ad and decided to give it a try.  I instantly fell in love with the product they were offering.  There was one thing missing from my development for this though.  I wanted to be able to use the usual Laravel 4 commands for Auth, Things like

[php] Auth::attempt()
Auth::logout()
Auth::check()
[/php]

After about 6 months of just ignoring what I wanted to do, I set out to build my own auth driver.  I had no idea where to start.  After a LOT of googling and reading many different articles of how to create service providers, I got discouraged  and gave up.  Today, I am happy to announce that I finally created a drop in auth driver that uses Stormpath.  I am now writing this article to let you know what I have done.

Begining the package

Workbench

I use the built in workbench package generation that laravel’s artisan gives us.  If you have never used workbench before in Laravel, You will need to set up a few config options.  Open /app/config/workbench.php and fill out your name and email address.  This is what will appear in the composer.json file.  The next step is to run the following command in your terminal

php artisan workbench lamarus/stormpath --resources

lamarus/stormpath is your vendor/package  and --resources will add the laravel resources you may need.

File Structure

I know some of you do not like to use the command line for this so here is what it will create for you.

/workbench
   /lamarus
      /stormpath
         /public
         /src
            /config
            /Lamarus
               /Stormpath
                  StormpathServiceProvider.php
            /lang
            /migrations
            /views
         /tests
         .travis.yml
         composer.json
         phpunit.xml

The Provider

Here is where I ran into some troubles. A lot if not all of the tutorials I found said that I had to edit the /app/start/global.php file to be able to add a new auth driver. This was just not acceptable for me as I knew I wanted to release this to the public and make it very simple for people to install. After a lot of frustration and searching, I found a way.

Base Provider

The base provider has a few things that were set up in the workbench command that we ran earlier. Here is what the file should currently look like.

workbench/lamarus/stormpath/src/Lamarus/Stormpath/StormpathServiceProvider.php

[php] <?php namespace LamarusStormpath;

use IlluminateSupportServiceProvider;

class StormpathServiceProvider extends ServiceProvider {

/**
* Indicates if loading of the provider is deferred.
*
* @var bool
*/
protected $defer = false;

/**
* Bootstrap the application events.
*
* @return void
*/
public function boot()
{
$this->package(‘lamarus/stormpath’);
}

/**
* Register the service provider.
*
* @return void
*/
public function register()
{

}

/**
* Get the services provided by the provider.
*
* @return array
*/
public function provides()
{
return array();
}

}
[/php]

Extend the Auth

We have some work to do in this file. At the top of the file, we need to tell it to use IlluminateAuthGuard; which is what takes care of all the auth commands. After we have this set up to use Guard, we need to add some data to the boot method. Here is where we will actually define the new driver.

workbench/lamarus/stormpath/src/Lamarus/Stormpath/StormpathServiceProvider.php in boot()

[php] Auth::extend(‘stormpath’, function() {

});
[/php]

Return a Guard

Now we have extended the Auth to allow for a stormpath driver. Now we need to return a Guard, which will give us access to all the Auth:: commands.

[php] Auth::extend(‘stormpath’, function() {
return new Guard(new ProvidersStormpathUserProvider, App::make(‘session’));
});
[/php]

We add the callback to return a new Guard with our custom User Provider. This is a file that we will create next. I am not 100% sure what the App::make(‘session’) does but I believe it gives the guard access to the sessions so we can actually log in and stay logged in.

User Provider

The StormpathUserProvider is a class we need to set up to help the guard know where to look for the user information. This is the core of the whole driver. This file needs to use the UserProviderInterface so we will set up the class as follows:

workbench/lamarus/stormpath/src/Lamarus/Stormpath/StormpathUser.php

[php] <?php namespace LamarusStormpathProviders;
use IlluminateAuthUserProviderInterface;
use IlluminateAuthGenericUser;

class StormpathUserProvider implements UserProviderInterface {

public function retrieveById($identifier)
{

}

public function retrieveByCredentials(array $credentials)
{

}

public function validateCredentials(IlluminateAuthUserInterface $user, array $credentials)
{

}
}
[/php]

This will give us the base of our driver. Now we need to make it do something.

Setting up retrieveByCredentials

This is another point which threw me for a loop. This method is the main method for logging in the user. Here is where I do all of the calls to the stormpath api, which I am not going to get into in this tutorial. The main thing that this has to do is return some representation of the user logging in as a UserInterface Object. So after we make the call to the API, I get the URL of the user if they are successfully logged in. Then I have the following for the method.

[php] public function retrieveByCredentials(array $credentials)
{
// Do stuff here to get the user href

$user = $response[‘account’][‘href’];
return new LamarusStormpathStormpathUser($user);
}

[/php]

Setting up validateCredentials

After setting up the method above. We need to do something that makes validateCredentials return true if they are good to log in. Though it is not the intended use of the method, This is where I am getting all of the information about the user and storing it in a session to use later, It is also where I can do one final check to make sure the user is allowed to log in, and not a disabled account. If all is ok, You then return true.

[php] public function validateCredentials(IlluminateAuthUserInterface $user, array $credentials)
{
if(ALLOWED_TO_LOGIN) {
return true;
else {
return false;
}
}
[/php]

Setting up retrieveById

The last method to set up is pretty basic. This is used when you run Auth::loginUsingId(). In this auth driver, it is where you would pass in the id of the account you want to login as without a password. This could be used for testing or admin purposes. The method would only return a StormpathUser Object

[php] public function retrieveById($identifier)
{
return new LamarusStormpathStormpathUser(‘https://api.stormpath.com/v1/accounts/’.$identifier);
}
[/php]

The StormpathUser Class

In the previous steps, we set up the User Provider. Now we need to set up what a StormpathUser looks like. Well first off, it will implement the UserInterface and cause our file to look like this.

[php] <?php namespace LamarusStormpath;

use IlluminateAuthUserInterface;

class StormpathUser implements UserInterface {
protected $url;

public function __construct($url) {
$this—>url = $url;
}

/**
* Get the unique identifier for the user.
*
* @return mixed
*/
public function getAuthIdentifier() {
return $this->url;
}

/**
* Get the password for the user.
*
* @return string
*/
public function getAuthPassword() {

}
}
[/php]

The only thing you will see here is that we have access to what the AuthIdentifier is which is the URL to the account on the stormpath api. This will allow the rest of the stormpath auth driver to work.

Package Up and Publish

Configuration

In this project, We have two configuration items that are being used in the UserProvider class. These are not shown in this tutorial but they are there. In order to allow a user to edit these configuration options, They will need to be able to publish them. Create a file at workbench/lamarus/stormpath/config/config.php and set your configuration array here. These will be accessable via the command Config::get('stormpath::key') or if you named your config file something else, lets say myconfig, you can get access to them via Config::get('stormpath::myconfig.key') After you publish your plugin, all the user will have to do is run php artisan config:publish lamarus/stormpath in the command line and then the configuration files will be at /app/config/packages/Lamarus/Stormpath where they can edit.

Publish

After you are done with your file, Publish your package on packagist.org and the world will be able to see them.

What is Stormpath?

Stormpath

Stormpath is the first easy and secure user management and authentication service for developers.  With a simple REST API integration, developers can reduce development and operations costs, while protecting users with best-in-class security.

The stormpath package in this article is available at https://packagist.org/packages/lamarus/stormpath and you can find installation details on Github