Integration: Socialite: MS Entra ID

Author: iamacarpet

docs/entra-socialite.md

@@ -0,0 +1,210 @@
+# Entra ID Federated Authentication Provider
+
+## Overview
+
+The `EntraFederatedProvider` is a custom Laravel Socialite driver included in the `GServerlessSupportLaravel` library. It enables secure, secretless authentication against Microsoft Entra ID (formerly Azure AD) for Laravel applications running on Google Cloud Platform (GCP).
+
+This provider leverages **Workload Identity Federation**, allowing your GCP workload (e.g., Cloud Run, GKE, GCE) to authenticate with Microsoft's APIs using its own GCP service account identity, eliminating the need to manage and store client secrets.
+
+## How It Works
+
+Instead of a traditional client secret, this provider uses a short-lived OIDC token generated by the GCP metadata server. This token is sent to Entra ID as a `client_assertion` in the OAuth 2.0 token exchange. Entra ID, having been configured to trust your GCP service account, validates the token and issues an access token in return.
+
+This approach significantly enhances security by removing long-lived credentials from your application's environment.
+
+## Requirements
+
+Before you begin, ensure you have:
+1.  A Laravel 11+ application using the `GServerlessSupportLaravel` library.
+2.  The application is hosted on a GCP service with an attached service account.
+3.  Administrative access to a Microsoft Entra ID tenant to configure an App Registration.
+4.  The **Unique ID** of the GCP service account your application uses. You can find this in the GCP Console under `IAM & Admin` > `Service Accounts`.
+
+---
+
+## Setup and Configuration
+
+### Step 1: Microsoft Entra ID Configuration
+
+First, you must register an application in Entra ID and configure it to trust your GCP service account's identity.
+
+1.  **Navigate to App Registrations**
+    * Log in to the [Microsoft Entra admin center](https://entra.microsoft.com/).
+    * Go to **Identity** > **Applications** > **App registrations**.
+    * Click **+ New registration**.
+
+2.  **Register the Application**
+    * Give your application a descriptive **Name** (e.g., "My GCP Web App").
+    * For **Supported account types**, choose the option that fits your needs (typically "Accounts in this organizational directory only").
+    * Click **Register**.
+
+3.  **Configure Redirect URIs**
+    * On your app registration's page, go to the **Authentication** tab.
+    * Click **+ Add a platform** and select **Web**.
+    * Under **Redirect URIs**, add the full callback URL for each domain your application uses. The path must match the one defined in your Laravel routes.
+        * Example for production: `https://app.your-domain.com/auth/callback`
+        * Example for local development: `http://localhost:8000/auth/callback`
+    * Click **Configure**.
+
+4.  **Note Your IDs**
+    * Go to the **Overview** page and copy the **Application (client) ID** and the **Directory (tenant) ID**. These will be used as environment variables.
+
+5.  **Create the Federated Credential**
+    * Navigate to the **Certificates & secrets** tab.
+    * Click the **Federated credentials** tab and then **+ Add credential**.
+    * From the **Federated credential scenario** dropdown, select **Other issuer**.
+    * Complete the form with the following details:
+        * **Issuer**: `https://accounts.google.com`
+        * **Subject identifier**: The numeric **Unique ID** of your GCP Service Account.
+        * **Name**: A descriptive name for the credential (e.g., `gcp-workload-identity`).
+        * **Audience**: `api://AzureADTokenExchange`
+    * Click **Add**.
+
+### Step 2: Laravel Application Configuration
+
+Now, configure your Laravel application to use the `EntraFederatedProvider`.
+
+1.  **Configure `config/services.php`**
+    Add an `entra` key to your `services` configuration file to read the environment variables.
+
+    ```php
+    // config/services.php
+    'entra' => [
+        'client_id' => env('ENTRA_CLIENT_ID'),
+        'tenant'    => env('ENTRA_TENANT_ID'),
+    ],
+    ```
+
+2.  **Set Environment Variables**
+    You must provide the `client_id` and `tenant` you copied from Entra ID as environment variables to your application. For cloud environments like Google Cloud Run or App Engine, it is best practice to set these directly in the service's configuration instead of using a `.env` file.
+
+    **Required Variables:**
+    ```
+    ENTRA_CLIENT_ID=your-application-client-id
+    ENTRA_TENANT_ID=your-directory-tenant-id
+    ```
+    *In your local development environment, you can add these to your `.env` file for convenience.*
+
+3.  **Register the Provider in `bootstrap/app.php`**
+    To enable the `entra` Socialite driver, you must extend the Socialite factory. The ideal place for this in a Laravel 11+ application is the `booted` callback in `bootstrap/app.php`.
+
+    ```php
+    // bootstrap/app.php
+
+    // ... (existing Application::configure code)
+    ->withExceptions(function (Exceptions $exceptions) {
+        //
+    })
+
+    // ---- ADD THIS CODE ----
+    // Extend the Socialite service to add our custom Entra driver.
+    ->booted(function ($app) {
+        // This check prevents errors when running artisan commands where the
+        // request context and URL generator might not be available.
+        if (!$app->has('url')) {
+            return;
+        }
+        
+        $socialite = $app->make(\Laravel\Socialite\Contracts\Factory::class);
+
+        $socialite->extend('entra', function ($app) use ($socialite) {
+            $config = $app['config']['services.entra'];
+
+            // Dynamically set the redirect URI using its name.
+            $config['redirect'] = route('auth.callback'); // <-- Use your callback route's name here
+            
+            // This provider is secretless, but Socialite's builder requires the key.
+            $config['client_secret'] = null;
+
+            // Build the provider and set the tenant ID.
+            return $socialite->buildProvider(
+                \AffordableMobiles\GServerlessSupportLaravel\Integration\Socialite\EntraFederatedProvider::class, 
+                $config
+            )->setTenant($config['tenant']);
+        });
+    })
+    // ---- END OF ADDED CODE ----
+    ->create()
+    ```
+
+---
+
+## Usage Example
+
+With the configuration complete, you can use the `entra` driver like any other Socialite provider.
+
+### Routes
+
+Define the routes for your authentication flow in `routes/web.php`.
+
+```php
+// routes/web.php
+use App\Http\Controllers\AuthController;
+use Illuminate\Support\Facades\Route;
+
+// Routes for guests (not logged in)
+Route::middleware('guest')->group(function () {
+    Route::get('/login', [AuthController::class, 'login'])->name('login');
+    Route::get('/auth/redirect', [AuthController::class, 'redirect'])->name('auth.redirect');
+    Route::get('/auth/callback', [AuthController::class, 'callback'])->name('auth.callback');
+});
+
+// Routes for authenticated users
+Route::middleware('auth')->group(function () {
+    Route::get('/dashboard', fn() => 'Welcome, ' . auth()->user()->name)->name('dashboard');
+    Route::post('/logout', [AuthController::class, 'logout'])->name('logout');
+});
+```
+
+### Controller
+Create a controller to handle the logic. Remember to add a nullable `entra_id` column to your `users` table to store the unique identifier from Microsoft.
+
+```php
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\User;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Laravel\Socialite\Facades\Socialite;
+
+class AuthController extends Controller
+{
+    /**
+     * Redirect the user to the Microsoft Entra authentication page.
+     */
+    public function redirect(): RedirectResponse
+    {
+        return Socialite::driver('entra')->redirect();
+    }
+
+    /**
+     * Obtain the user information from Microsoft Entra ID after authentication.
+     */
+    public function callback(Request $request): RedirectResponse
+    {
+        try {
+            $entraUser = Socialite::driver('entra')->user();
+
+            // Find or create a user in your local database.
+            $user = User::updateOrCreate(
+                ['entra_id' => $entraUser->getId()],
+                ['name' => $entraUser->getName(), 'email' => $entraUser->getEmail()]
+            );
+
+            Auth::login($user);
+            $request->session()->regenerate();
+
+            return redirect()->intended(route('dashboard'));
+
+        } catch (\Throwable $e) {
+            report($e);
+            return redirect()->route('login')->with('error', 'Login failed. Please try again.');
+        }
+    }
+    
+    // ... other methods like login() and logout()
+}
+```