README

Entra SSO for Laravel

A simple, reusable Microsoft Entra (Azure AD) Single Sign-On package for Laravel 12+ with automatic user creation, role mapping, group sync, token refresh, and custom claims support.

Features
Quick Start
Requirements
Installation
Usage
Documentation
Troubleshooting
Development
License

Features

✅ Simple Setup - Interactive installation wizard handles everything
✅ Azure AD/Entra Authentication - Secure OAuth2/OIDC implementation
✅ Auto-Create Users - Users created automatically on first login
✅ Role Mapping - Map Azure AD groups to application roles
✅ Group Sync - Sync user groups from Azure AD
✅ Token Refresh - Automatic token refresh for long sessions
✅ Custom Claims - Extract additional user attributes from Azure AD
✅ Built-in Dashboard - Default landing page with user info and examples
✅ Framework Agnostic - Works with Blade, Livewire, Inertia (React/Vue)
✅ Starter Kit Support - Auto-configuration for Breeze/Jetstream/Fortify

Quick Start

# 1. Install package
composer require dcplibrary/entra-sso

# 2. Run interactive wizard
php artisan entra:install

# 3. Add login button to your views
<a href="{{ route('entra.login') }}">Sign in with Microsoft</a>

That's it! The wizard handles Azure AD configuration, environment setup, User model updates, and migrations.

Requirements

PHP 8.2 or higher
Laravel 12.0 or higher
Azure AD tenant with admin access (Setup Guide)
Any session driver (database, redis, file, etc.)

Compatibility

Works with all Laravel frontend stacks and starter kits:

Stack	Status	Notes
Blade	✅ Full support	Zero conflicts
Livewire	✅ Auto-configurable	Use `--fix-starter-kit` flag
Inertia (Vue/React)	✅ Auto-configurable	Use `--fix-starter-kit` flag
Breeze/Jetstream	✅ Auto-configurable	Use `--fix-starter-kit` flag

Starter kit conflicts? The entra:install --fix-starter-kit command automatically detects and resolves authentication conflicts. See Starter Kit Configuration for details.

Installation

Interactive Installation (Recommended)

composer require dcplibrary/entra-sso
php artisan entra:install

Notes:

Redirect URI default: the installer sets ENTRA_REDIRECT_URI to "${APP_URL}/auth/entra/callback" so your current port (e.g., :8000) is preserved.
Group-to-role mapping: enter values without quotes (e.g., IT Admins:admin,Developers:developer). The installer will add the surrounding quotes in .env for you.

The wizard will guide you through:

Azure AD credentials setup
Environment configuration
User model updates
Database migrations
Starter kit conflict resolution (if needed)

Command options:

# Auto-fix starter kit conflicts
php artisan entra:install --fix-starter-kit

# Skip specific steps
php artisan entra:install --skip-user-model
php artisan entra:install --skip-env

Manual Installation

For manual installation steps, see the Installation Guide.

Usage

Basic Usage

Add login button:

<a href="{{ route('entra.login') }}">Sign in with Microsoft</a>

Protect routes:

// By role
Route::middleware(['auth', 'entra.role:admin'])->group(function () {
    Route::get('/admin', [AdminController::class, 'index']);
});

// By Azure AD group
Route::middleware(['auth', 'entra.group:IT Admins'])->group(function () {
    Route::get('/servers', [ServerController::class, 'index']);
});

Use helper methods:

$user = auth()->user();

// Check roles
$user->hasRole('admin');
$user->isAdmin();

// Check groups
$user->inGroup('IT Admins');
$user->getEntraGroups();

// Get custom claims
$user->getCustomClaim('department');

Configuration

Redirect after login:

ENTRA_REDIRECT_AFTER_LOGIN=/dashboard

Map groups to roles:

ENTRA_GROUP_ROLES="IT Admins:admin,Developers:developer,Staff:user"

Enable token refresh:

ENTRA_ENABLE_TOKEN_REFRESH=true

For more usage examples, see the default dashboard at /entra/dashboard after logging in.

Documentation

Comprehensive guides for all features:

Installation Guide - Detailed installation instructions
Azure AD Setup - Configure your Azure AD application
Starter Kit Configuration - Configure Breeze/Jetstream/Livewire/Inertia
Role Mapping - Map Azure AD groups to application roles
Custom Claims - Extract additional user attributes
Token Refresh - Automatic token refresh for long sessions
Troubleshooting - Common issues and solutions

Troubleshooting

Common issues:

Login redirects not working → Check session driver and APP_URL
"Invalid state parameter" → Clear session cache
User not created → Enable ENTRA_AUTO_CREATE_USERS=true
Groups not syncing → Check GroupMember.Read.All permission in Azure
Token refresh failures → User needs to log in again

📖 Full troubleshooting guide: Troubleshooting Guide

Need help? Open an issue on GitHub

Development

Local Package Development

For local development, add a path repository to your Laravel app's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../entra-sso"
        }
    ],
    "require": {
        "dcplibrary/entra-sso": "*"
    }
}

Then run:

composer update dcplibrary/entra-sso

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT

dcplibrary / entra-sso

Maintainers

Details