Laravel Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require stormpath/laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="Stormpath\Laravel\StormpathServiceProvider"
   

2. Configure .env Add your Stormpath API key (from the Stormpath Console):

   STORMPATH_CLIENT_API_KEY_FILE=/path/to/your/keyfile
   STORMPATH_CLIENT_APPLICATION_HREF=https://api.stormpath.com/v1/applications/YOUR_APP_HREF
   

3. First Use Case: Authenticate a User Use the auth helper or facade to log in a user:

   use Stormpath\Laravel\Facades\Stormpath;
   
   // Login with email/password
   $user = Stormpath::auth()->login('user@example.com', 'password123');
   
   // Or via Stormpath's built-in auth middleware
   Route::get('/dashboard', 'DashboardController@index')->middleware('stormpath.auth');
   

4. Verify Installation Check if the Stormpath service is registered:

   php artisan tinker
   >>> \Stormpath\Laravel\Facades\Stormpath::getClient();
   

Implementation Patterns

Core Workflows

1. Authentication

   • Login/Logout:

     // Login
     $user = Stormpath::auth()->login($email, $password);
     
     // Logout
     Stormpath::auth()->logout();
     

   • Middleware: Use stormpath.auth to protect routes:

     Route::group(['middleware' => 'stormpath.auth'], function () {
         // Protected routes
     });
     

   • Remember Me:

     $user = Stormpath::auth()->login($email, $password, true); // true = remember
     

2. User Management

   • Create Users:

     $user = Stormpath::users()->create([
         'email' => 'user@example.com',
         'password' => 'password123',
         'givenName' => 'John',
         'surname' => 'Doe',
     ]);
     

   • Fetch Users:

     $user = Stormpath::users()->getByEmail('user@example.com');
     $users = Stormpath::users()->getAll();
     

   • Update Users:

     $user->setPassword('newPassword123')->save();
     

3. Groups and Roles

   • Assign Groups:

     $group = Stormpath::groups()->getByName('Admins');
     $user->groups()->add($group);
     

   • Check Group Membership:

     if ($user->isInGroup('Admins')) {
         // Grant admin privileges
     }
     

4. Password Reset

   • Trigger Reset:

     Stormpath::passwordResets()->sendResetEmail('user@example.com');
     

   • Handle Reset:

     $token = request('token');
     $newPassword = request('password');
     Stormpath::passwordResets()->reset($token, $newPassword);
     

5. Integration with Laravel Auth

   • Retrieve the authenticated Stormpath user in Laravel's auth system:

     $stormpathUser = Stormpath::auth()->getUser();
     $laravelUser = \Auth::user(); // If using StormpathUser model
     

Advanced Patterns

1. Custom User Model Extend Laravel's User model to include Stormpath data:

   class User extends \Illuminate\Foundation\Auth\User implements \Stormpath\Laravel\StormpathUserContract
   {
       public function getStormpathAccount()
       {
           return Stormpath::users()->getByEmail($this->email);
       }
   }
   

2. Stormpath Events Listen to Stormpath events (e.g., login, registration):

   Stormpath::events()->listen('account.created', function ($account) {
       // Send welcome email
   });
   

3. Custom Claims Attach custom attributes to users:

   $user->customData()->set('premium', true)->save();
   

4. Social Logins Configure Stormpath social providers (e.g., Google, Facebook) via the Stormpath Console and use:

   Stormpath::auth()->loginWithSocial('google', $token);
   

5. Multi-Tenancy Use Stormpath's tenant features to manage multiple applications:

   Stormpath::setApplication('https://api.stormpath.com/v1/applications/NEW_APP_HREF');
   

Gotchas and Tips

Common Pitfalls

1. API Key File Permissions

   • Ensure the key file has restrictive permissions (e.g., 600):

     chmod 600 /path/to/your/keyfile
     

   • Error: Invalid API key file may appear if permissions are too open.

2. Application HREF Mismatch

   • Double-check the STORMPATH_CLIENT_APPLICATION_HREF in .env matches your Stormpath app.
   • Error: Application not found or Unauthorized errors often stem from incorrect HREFs.

3. Caching Issues

   • Stormpath caches data aggressively. Clear Laravel cache after changes:

     php artisan cache:clear
     php artisan config:clear
     

4. Deprecated Methods

   • Some methods (e.g., Stormpath::auth()->attempt()) may not work as expected. Prefer:

     Stormpath::auth()->login($email, $password);
     

5. Timeouts and Rate Limits

   • Stormpath enforces rate limits. Handle Stormpath\Exception\RateLimitExceededException gracefully:

     try {
         $user = Stormpath::users()->getByEmail('user@example.com');
     } catch (\Stormpath\Exception\RateLimitExceededException $e) {
         // Retry or notify admin
     }
     

6. Laravel 5.5+ Compatibility

   • The package is outdated for newer Laravel versions. Use a compatibility layer or fork:

     // Example: Override the service provider
     Stormpath::extend(function ($app) {
         return new \Stormpath\Laravel\StormpathServiceProvider($app);
     });
     

Debugging Tips

1. Enable Stormpath Debugging Add to .env:

   STORMPATH_DEBUG=true
   

   Logs will appear in storage/logs/laravel.log.

2. Check HTTP Requests Use Laravel's debug bar or dd() to inspect Stormpath responses:

   $response = Stormpath::getClient()->getAccountStore()->getAccount($accountHref);
   dd($response->getRawContent());
   

3. Stormpath Console Logs Monitor activity in the Stormpath Console under Logs.

4. Common HTTP Errors

   • 401 Unauthorized: Invalid API key or application HREF.
   • 404 Not Found: User/group not found (check HREFs).
   • 500 Server Error: Stormpath API issue (check their status page).

Extension Points

1. Custom Auth Guards Extend Laravel's auth system to use Stormpath:

   // config/auth.php
   'guards' => [
       'stormpath' => [
           'driver' => 'session',
           'provider' => 'stormpath',
       ],
   ],
   
   'providers' => [
       'stormpath' => [
           'driver' => 'stormpath',
           'model' => \App\User::class,
       ],
   ],
   

2. Stormpath Events Listen to Stormpath-specific events:

   Stormpath::events()->listen('account.created', function ($account) {
       // Trigger custom logic (e.g., send email)
   });
   

3. Override User Model Replace the default StormpathUser model:

   // config/stormpath.php
   'user_model' => \App\Models\CustomStormpathUser::class,
   

4. Custom API Clients Extend the Stormpath client for additional functionality:

   Stormpath::extendClient(function ($client) {
       $client->setCustomHeader('X-Custom-Header', 'value');
       return $client;
   });
   

5. Webhook Integration Use Stormpath webhooks to trigger Laravel jobs:

   Route::post('/stormpath-webhook', function () {
       $payload = request()->all();
       // Process webhook (e.g., user.created)
       dispatch(new HandleStormpathWebhook($payload));
   });
   

Migration Notes (Stormpath → Ok