README

Authenticate users with Entra Single Sign On

Limitations

Due to Network Rail policies, Entra applications cannot be given application level access.

As such, we cannot poll Entra directly with guest users.

Since our systems require guests to be able to poll the directory, Entra can only be used for authentication.

Installation

1. Install using Composer:

   composer require networkrailbusinesssystems/entra

2. Publish the entra.php config file:

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

   • You may skip this step if your User model's FQN is App\Models\User
   • Set the entra.models.user setting to your User model:

     return [
         ...
         'models' => [
             'user' => User::class,
         ],
         ...
     ];

3. Adjust your .env to include the required settings
4. Implement the AuthenticatesWithEntra interface on your User
5. Add the Entra routes to your routes/web.php using the macro:

   Route::entra();

6. Secure your other routes using the EntraAuthenticated middleware:

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

7. Use the EntraTokenExists middleware on routes which require an access token:

   Route::middleware('EntraTokenExists')->group(function () {
       // Your authenticated token routes here...
   }

Configuration

The following settings can be changed in your .env:

The following additional settings are available in the entra.php configuration file:

Usage

There are two main ways to use this library:

1. Automatic login
2. User initiated login

Automatic login

To automatically login Users across the entire system, simply wrap all your web routes in EntraAuthenticated.

User initiated login

If some pages should be available without a login, only wrap the needed web routes in EntraAuthenticated.

When users attempt to access those pages they will be logged in automatically.

You could also provide a Sign in or Login button someone on your interface which points to the entra.login route.

Signing out

Users can visit the entra.logout route to sign out.

This will only sign them out of the local system, not their Entra browser session.

Preventing Users being created

Some systems do not allow User models to be created automatically.

To prevent this, call abort() or throw an exception in your AuthenticatesWithEntra implementation.

Access Token

You can find the current EntraAccessToken for the logged in User in their session:

/** @var ?EntraAccessToken $token */
$token = Session::get(Entra::ENTRA_TOKEN);

Entra may be expanded in the future with endpoints for use.