README

Easily sign-in and poll users and groups in Microsoft Entra, built using Laravel Microsoft Graph.

Setup

1. Install this library using Composer:

   composer require networkrailbusinesssystems/entra

2. Publish the Entra configuration file using Artisan:

   php artisan vendor:publish --tag="entra"

3. Publish the MsGraph configuration file

   php artisan vendor:publish --provider="Dcblogdev\MsGraph\MsGraphServiceProvider" --tag="config"

   • Set scopes as required
   • More information is available in the Laravel Microsoft Graph documentation
4. Publish the MsGraph migration file

   php artisan vendor:publish --provider="Dcblogdev\MsGraph\MsGraphServiceProvider" --tag="migrations"

   • Consider adding a foreign key to the user_id column for greater efficiency
5. Adjust the entra.php configuration file to suit your needs
6. Setup your authenticatable User model
   • Implement the EntraAuthenticatable interface on your chosen Model
   • Add the AuthenticatesWithEntra trait on your chosen Model for a standard fetch and sync setup, or implement the methods yourself
7. Add the Entra authentication routes to your routes/web.php using the macro:

   Route::entra();
   
   Route::middleware('EntraAuthenticated')->group(function () {
       // Your authenticated routes here...
   }

Configuration

create_users

Whether to allow Users without an account in the system already to sign-in.

When set to true, Entra will automatically create a new User record for anyone who successfully signs in.

When set to false, Users must be manually added before they can sign-in, even with a valid SSO session.

messages

Customise any of the error messages thrown by Entra.

sync_attributes

Any attributes set here will automatically be filled when signing in, keeping the User up to date with any changes in Entra.

The array should contain a key-value pair in entra => laravel format.

'sync_attributes' => [
    'mail' => 'email',
],

user_model

The fully qualified class name of the Model used for Laravel authentication.

use App/Models/User;

'user_model' => User::class,

emulator

These attributes controls the Entra emulator, and the mock data available to it.

See the "Emulator" section further on for more information.

Signing in and out

Users will automatically be redirected to the Microsoft Azure login page whenever they attempt to access an authenticated route as a guest.

The EntraServiceProvider automatically registers the relevant event listeners for authentication.

Automatic

If you wrap all of your system's endpoints in the EntraAuthenticated middleware, Users will be automatically kicked to the Entra login page.

Should they become signed out for whatever reason, they will be kicked to the Entra login screen.

This may or may not be desirable based on how much of the system should be available to non-users.

Manual sign-in and out

You can allow users to manually login by providing a link to the login route, which will take them to the Entra login page.

Users can logout by calling the logout route, which will take them to the Entra logout page.

Middleware

The EntraAuthenticated middleware has been provided to replace the base MsGraphAuthenticated middleware.

This works in the same way as the base middleware, adding support for Laravel's intended destination route handling.

Querying Entra

You can use the Laravel Microsoft Graph library as normal.

Entra queries on routes outside of the EntraAuthenticated middleware must connect to Entra first, otherwise the request will hit a 302 redirect and fail.

Service Accounts

Calling MsGraph will access Entra using the currently signed-in user's credentials.

Calling MsGraphAdmin will access Entra as the application, without a signed-in user.

MsGraphAdmin should be used for any calls to Entra which are performed in the background, such as queues, jobs, and commands.

Any calls using the models provided by this library will automatically fall back to the MsGraphAdmin account if there is no signed-in user.

MsGraph

A drop-in alias for the MsGraph facade has been provided which adds docblocks for IDE support.

The connect method has been partially overridden to add support for Laravel's inbuilt intended route handling.

MsGraphAdmin

A drop-in alias for the MsGraphAdmin facade has been provided which adds docblocks for IDE support.

EntraGroup

Get

Search for and return a specific group.

List

Search for groups which start with a term.

EntraGroupMembers

Get

Retrieve a list of users for a group by the group's ID.

Entra will be polled until all of the group's users have been loaded.

EntraUser

Get

Search for and return a specific user.

List

Search for users which start with a term.

Import

Search for and import a specific user to the database.

If the user already exists they will be updated.

Commands

The following Artisan commands are available for use:

Rules

UserExistsInEntra

Ensure that the given User exists in Entra.

// Request data
[
    'email' => 'joe.bloggs@networkrail.co.uk',
];

// FormRequest rules()
'email' => [
    new UserExistsInEntra('mail'),
];

You may provide the field to match the value to as the first parameter of the Rule.

Emulator

It is unlikely that your unit tests will ever be connected to a live Entra instance.

You can mock MsGraph for specific calls, however you may prefer to re-use a defined list of results.

The emulator only works with the models provided by this library.

Setting entra.emulator.enabled = true in your config will enable the emulator.

You may also use the AssertsEntra trait on your base TestCase class to make the useEntraEmulator() method available in your tests.

Emulation does not support signing in or out.

EntraGroup and EntraGroupMembers

Defining a list of groups on the entra.emulator.groups key will allow you to create a custom list of groups with members which you can re-use.

Performing an EntraGroup::get will return a matching group from the list.

Performing an EntraGroup::list will return a matching set of results from the list.

Performing an EntraGroupMembers::get will return a matching group's members from the list.

EntraUser

Defining a list of users on the entra.emulator.users key will allow you to create a custom list of users which you can re-use.

Performing an EntraUser::get or EntraUser::import will return a matching user from the list.

Performing an EntraUser::list will return a matching set of results from the list.

Sample Entra responses

Sample responses are provided on the relevant EntraModel.

Roadmap

• Add 302 handler to MsGraph facade

Help and support

You are welcome to raise any issues or questions on GitHub.

If you wish to contribute to this library, raise an issue before submitting a forked pull request.

Licence

Published under the MIT licence.