README

A Laravel authentication guard for validating Microsoft Entra ID (Azure AD) JWT bearer tokens.

Requirements

• PHP 8.2+
• Laravel 11.0+

Installation

composer require acato/ms-entra-guard

The service provider is auto-discovered. Publish the config file:

php artisan vendor:publish --tag=entra-guard-config

Configuration

1. Add a guard to config/auth.php

'guards' => [
    // ...
    'api' => [
        'driver' => 'entra',
        'provider' => null,
    ],
],

2. Configure trusted providers in config/entra-guard.php

'providers' => [
    [
        'iss' => 'https://login.microsoftonline.com/{tenant-id}/v2.0',
        'alg' => \Lcobucci\JWT\Signer\Rsa\Sha256::class,
        'claims' => [
            'aud' => 'your-client-id',
        ],
    ],
],

3. Implement the interface on your User model

use Acato\EntraGuard\Contracts\ResolvesFromEntraToken;
use Acato\EntraGuard\Concerns\ResolvesEntraUser;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements ResolvesFromEntraToken
{
    use ResolvesEntraUser;
}

The ResolvesEntraUser trait provides a default updateOrCreate implementation. Customize the field mapping with static properties:

class User extends Authenticatable implements ResolvesFromEntraToken
{
    use ResolvesEntraUser;

    // Map DB columns to JWT claims for the unique key
    protected static array $entraUniqueBy = [
        'uuid' => 'oid',
    ];

    // Map DB columns to JWT claims for update values
    // Use '|' for fallback (tries left-to-right), null inserts now()
    protected static array $entraUpdateAttributes = [
        'name' => 'name',
        'email' => 'email|upn',
        'last_login_at' => null,
    ];
}

Alternative: custom user resolver

Instead of implementing the interface, you can provide a closure in the config:

'user_resolver' => function (array $payload) {
    return \App\Models\User::where('azure_id', $payload['oid'])->first();
},

Usage

Protect routes with the guard:

Route::middleware('auth:api')->group(function () {
    Route::get('/me', fn () => auth()->user());
});

Testing

Use actingAs in your tests:

use Acato\EntraGuard\EntraGuard;

EntraGuard::actingAs($user, 'api');

Config Options

License

Apache-2.0. See LICENSE for details.