Oauth2 Azure Laravel Package

Technical Evaluation

Architecture Fit

• Leverages League OAuth2 Client: The package is a provider for the widely adopted League OAuth2 Client, ensuring compatibility with Laravel’s ecosystem (e.g., socialite or custom OAuth integrations). This aligns with Laravel’s modular, package-based architecture.
• Azure AD Specificity: Tailored for Azure AD’s OAuth2 flows (e.g., v1.0/v2.0 endpoints, B2C, certificate auth), reducing boilerplate for Azure-specific logic. Supports Microsoft Graph and Azure Graph API out-of-the-box, critical for enterprise integrations.
• Experimental Features: Includes experimental but valuable features like:
  • On-behalf-of flows (delegated permissions).
  • API protection (token validation for protected endpoints).
  • B2C support (useful for consumer-facing apps).
  • Multipurpose refresh tokens (simplifies multi-resource access).

Integration Feasibility

• Laravel Compatibility:
  • Works seamlessly with Laravel’s Service Container (bind the provider as a singleton).
  • Integrates with Laravel Sessions for state management (e.g., storing OAuth state/codes).
  • Can be wrapped in a custom facade or service class for cleaner usage.
• Dependency Alignment:
  • Requires league/oauth2-client (v1.3.0+), which Laravel projects likely already use or can easily adopt.
  • No Laravel-specific dependencies; pure PHP/OAuth2 logic.
• Configuration Flexibility:
  • Supports client secrets, certificate-based auth, and custom scopes/resources.
  • Configurable endpoints (e.g., pathAuthorize, pathToken) for B2C or custom Azure setups.

Technical Risk

Key Questions for TPM

1. Authentication Flow:
   • Will the app use Authorization Code Flow (web), Client Credentials (service-to-service), or On-Behalf-Of (delegated)?
   • Are refresh tokens required for long-lived sessions?
2. Azure AD Configuration:
   • Are client certificates preferred over secrets (for higher security)?
   • Will the app support B2C or multi-tenant scenarios?
3. Integration Points:
   • Where will token validation occur? (e.g., Laravel middleware, API gateway).
   • How will Microsoft Graph data be cached (e.g., Laravel Cache, Redis)?
4. Error Handling:
   • How will OAuth failures (e.g., invalid state, expired tokens) be surfaced to users?
5. Testing:
   • Are there mock Azure AD endpoints for CI/CD (e.g., Azure AD Free Trial tenant)?
   • Will load testing be performed for token refresh scenarios?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Container: Bind the provider as a singleton in AppServiceProvider:

    $this->app->singleton(TheNetworg\OAuth2\Client\Provider\Azure::class, function ($app) {
        return new Azure([
            'clientId' => config('services.azure.client_id'),
            'clientSecret' => config('services.azure.client_secret'),
            'redirectUri' => config('services.azure.redirect_uri'),
        ]);
    });
    

  • Middleware: Create middleware to validate tokens for API routes:

    public function handle($request, Closure $next) {
        $token = $request->bearerToken();
        $provider = app(Azure::class);
        $provider->validateAccessToken($token);
        return $next($request);
    }
    

  • Socialite Wrapper: Extend Laravel Socialite for Azure-specific logic (e.g., custom scopes).
• Database:
  • Store refresh tokens and user claims in users table or a oauth_tokens table.
  • Example schema:

    Schema::create('oauth_tokens', function (Blueprint $table) {
        $table->id();
        $table->foreignId('user_id')->constrained();
        $table->text('access_token');
        $table->text('refresh_token')->nullable();
        $table->timestamp('expires_at');
        $table->timestamps();
    });
    

• Caching:
  • Cache Microsoft Graph responses (e.g., user profiles) using Laravel Cache:

    Cache::remember("graph_user_{$userId}", now()->addHours(1), function () use ($token, $provider) {
        return $provider->get($provider->getRootMicrosoftGraphUri($token) . '/me', $token);
    });
    

Migration Path

1. Phase 1: Proof of Concept (PoC)
   • Integrate the package in a non-production Laravel app (e.g., a feature branch).
   • Test Authorization Code Flow with a single scope (e.g., openid).
   • Validate token storage and refresh logic.
2. Phase 2: Core Integration
   • Replace hardcoded Azure configs with Laravel config files (config/services.php).
   • Implement middleware for token validation on protected routes.
   • Add Microsoft Graph API calls (e.g., fetch user emails).
3. Phase 3: Advanced Features
   • Enable client certificate auth if required.
   • Implement on-behalf-of flows for delegated permissions.
   • Add B2C support if targeting consumer users.
4. Phase 4: Optimization
   • Add rate limiting for Graph API calls (e.g., Laravel Throttle).
   • Implement webhook-based token refresh (e.g., Azure AD token cache).

Compatibility

Sequencing

1. Prerequisites:
   • Register an app in Azure AD Portal with:
     • Redirect URI (e.g., https://yourapp.com/auth/azure/callback).
     • Required permissions (e.g., openid, User.Read).
     • Client secret or certificate.
   • Install dependencies:

     composer require thenetworg/oauth2-azure league/oauth2-client
     

2. Core Setup:
   • Configure Laravel to bind the provider (see Stack Fit above).
   • Create routes for authentication and callback:

     Route::get('/auth/azure', [AzureAuthController::class, 'redirectToAzure']);
     Route::get('/auth/azure/callback', [AzureAuthController::class, 'handleAzureCallback']);
     

3. Token Storage:
   • Implement logic to store/retrieve tokens (e.g., in database or cache).
4. API Integration:
   • Use the provider’s get() methods to call Microsoft Graph.
   • Example:

     $user = $provider->get($provider->getRootMicrosoftGraphUri($token) . '/me', $token);
     

5. Security:
   • Add middleware to validate tokens on protected routes.
   • Implement logout functionality using getLogoutUrl().

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor updates to thenetworg/oauth2-azure and league/oauth2-client for breaking changes.
  • Azure AD endpoints