acato/ms-entra-guard

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

0.3.0 2026-02-24 14:51 UTC

Requires

• php: ^8.2
• illuminate/auth: ^11.0 || ^12.0
• illuminate/cache: ^11.0 || ^12.0
• illuminate/contracts: ^11.0 || ^12.0
• illuminate/http: ^11.0 || ^12.0
• illuminate/support: ^11.0 || ^12.0
• lcobucci/clock: ^2.0 || ^3.0
• lcobucci/jwt: ^4.3 || ^5.0

Requires (Dev)

• orchestra/testbench: ^9.0 || ^10.0
• phpunit/phpunit: ^11.0 || ^12.0

Apache-2.0

• Corné Guijt
• Yoeri Dekker

• Authentication
• laravel
• microsoft
• jwt
• guard
• azure-ad
• entra

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

Key	Type	Default	Description
model	class-string	App\Models\User	Eloquent model implementing ResolvesFromEntraToken
user_resolver	?Closure	null	Custom resolver (takes precedence over model)
token_cache_ttl	int	10	Minutes to cache decoded tokens
key_cache_ttl	int	4	Hours to cache public signing keys
timezone	string	app timezone	Timezone for JWT time validation
providers	array	[]	Trusted issuer configurations

License

Apache-2.0. See LICENSE for details.