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.