CU Auth package

README.md

@@ -11,7 +11,7 @@ A Cornell University CIT Custom Development starter kit and library for Laravel.
 
 ## Usage
 
-The Starter Kit can be used as a starter kit for a new site or as a library for an existing site.
+The Starter Kit can be used [as a starter kit for a new site](#as-a-starter-kit-for-a-new-site) or [as a library for an existing site](#as-a-library-for-an-existing-site).
 
 ### As a Starter Kit for a New Site
 
@@ -84,7 +84,7 @@ For an existing Laravel site, this package can be composer-required to provide t
 The libraries included in the Starter Kit are documented in their respective README files:
 
 - [Contact/PhoneNumber](src/Contact/README.md): A library for parsing and formatting a phone number.
-
+- [CUAuth](src/CUAuth/README.md): A middleware for authorizing Laravel users, mostly for Apache mod_shib authentication.
 
 ## Deploying a site
 Once a Media3 site has been created, you have confirmed you can reach the default site via a web browser, and you have access to the site login by command line, the code can be deployed.

composer.json

@@ -29,7 +29,8 @@
   "extra": {
     "laravel": {
       "providers": [
-        "CornellCustomDev\\LaravelStarterKit\\StarterKitServiceProvider"
+        "CornellCustomDev\\LaravelStarterKit\\StarterKitServiceProvider",
+        "CornellCustomDev\\LaravelStarterKit\\CUAuth\\CUAuthServiceProvider"
       ]
     }
   },

config/cu-auth.php

@@ -0,0 +1,52 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | ApacheShib Configuration
+    |--------------------------------------------------------------------------
+    |
+    | ApacheShib retrieves user data from server variables populated by the
+    | Apache shibboleth module (mod_shib).
+    |
+    | The default user variable is "REMOTE_USER", but this may differ depending
+    | on how mod_shib is configured.
+    |
+    | For local development without shibboleth, you can add
+    | REMOTE_USER=<netid> to your project .env file to log in as that user.
+    |
+    | To require a local user be logged in based on the remote user, set
+    | REQUIRE_LOCAL_USER to true.
+    |
+    */
+    'apache_shib_user_variable' => env('APACHE_SHIB_USER_VARIABLE', 'REMOTE_USER'),
+    'remote_user_override' => env('REMOTE_USER'),
+
+    'require_local_user' => env('REQUIRE_LOCAL_USER', false),
+
+    'shibboleth_login_url' => env('SHIBBOLETH_LOGIN_URL', '/Shibboleth.sso/Login'),
+    'shibboleth_logout_url' => env('SHIBBOLETH_LOGOUT_URL', '/Shibboleth.sso/Logout'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | AppTesters Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Comma-separated list of users to allow in development environments.
+    | APP_TESTERS_FIELD is the field on the user model to compare against.
+    |
+    */
+    'app_testers' => env('APP_TESTERS', ''),
+    'app_testers_field' => env('APP_TESTERS_FIELD', 'netid'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Allow Local Login
+    |--------------------------------------------------------------------------
+    |
+    | Allow Laravel password-based login? Typically, this would only be used
+    | for local or automated testing.
+    |
+    */
+    'allow_local_login' => boolval(env('ALLOW_LOCAL_LOGIN', false)),
+];

phpunit.xml

@@ -4,7 +4,7 @@
     bootstrap="vendor/autoload.php"
     colors="true"
     testdox="true"
-    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+    xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
     cacheDirectory=".phpunit.cache"
 >
     <source>

src/CUAuth/CUAuthServiceProvider.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace CornellCustomDev\LaravelStarterKit\CUAuth;
+
+use CornellCustomDev\LaravelStarterKit\StarterKitServiceProvider;
+use Illuminate\Support\ServiceProvider;
+
+class CUAuthServiceProvider extends ServiceProvider
+{
+    const INSTALL_CONFIG_TAG = 'cu-auth-config';
+
+    public function register(): void
+    {
+        $this->mergeConfigFrom(
+            path: __DIR__.'/../../config/cu-auth.php',
+            key: 'cu-auth',
+        );
+    }
+
+    public function boot(): void
+    {
+        if ($this->app->runningInConsole()) {
+            $this->publishes([
+                __DIR__.'/../../config/cu-auth.php' => config_path('cu-auth.php'),
+            ], StarterKitServiceProvider::PACKAGE_NAME.':'.self::INSTALL_CONFIG_TAG);
+        }
+        $this->loadRoutesFrom(__DIR__.'/routes.php');
+    }
+}

src/CUAuth/DataObjects/ShibIdentity.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace CornellCustomDev\LaravelStarterKit\CUAuth\DataObjects;
+
+use Illuminate\Http\Request;
+
+class ShibIdentity
+{
+    // Shibboleth fields generally available from either cit or weill IdPs.
+    public const SHIB_FIELDS = [
+        'Shib_Application_ID', // <vhost|applicationId>
+        'Shib_Authentication_Instant', // YYYY-MM-DDT00:00:00.000Z
+        'Shib_Identity_Provider', // https://shibidp.cit.cornell.edu/idp/shibboleth|https://login.weill.cornell.edu/idp
+        'Shib_Session_Expires', // timestamp
+        'Shib_Session_Inactivity', // timestamp
+        'displayName', // John Doe
+        'eduPersonAffiliations', // employee;member;staff
+        'eduPersonPrincipalName', // [email protected]|[email protected]
+        'eduPersonScopedAffiliation', // employee@[med.]cornell.edu;member@[med.]cornell.edu;[email protected]
+        'givenName', // John
+        'mail', // alias email
+        'sn', // Doe
+        'uid', // netid|cwid
+    ];
+
+    public function __construct(
+        public readonly string $idp,
+        public readonly string $uid,
+        public readonly string $displayName = '',
+        public readonly string $email = '',
+        public readonly array $serverVars = [],
+    ) {}
+
+    /**
+     * Shibboleth server variables will be retrieved from the request if not provided.
+     */
+    public static function fromServerVars(?array $serverVars = null): self
+    {
+        if (empty($serverVars)) {
+            $serverVars = app('request')->server();
+        }
+
+        return new ShibIdentity(
+            idp: $serverVars['Shib_Identity_Provider'] ?? '',
+            uid: $serverVars['uid'] ?? '',
+            displayName: $serverVars['displayName']
+                ?? $serverVars['cn']
+                ?? trim(($serverVars['givenName'] ?? '').' '.($serverVars['sn'] ?? '')),
+            email: $serverVars['eduPersonPrincipalName']
+                ?? $serverVars['mail'] ?? '',
+            serverVars: $serverVars,
+        );
+    }
+
+    public static function getRemoteUser(?Request $request = null): ?string
+    {
+        if (empty($request)) {
+            $request = app('request');
+        }
+
+        // If this is a local development environment, allow the local override.
+        $remote_user_override = self::getRemoteUserOverride();
+
+        // Apache mod_shib populates the remote user variable if someone is logged in.
+        return $request->server(config('cu-auth.apache_shib_user_variable')) ?: $remote_user_override;
+    }
+
+    public static function getRemoteUserOverride(): ?string
+    {
+        // If this is a local development environment, allow the local override.
+        return app()->isLocal() ? config('cu-auth.remote_user_override') : null;
+    }
+
+    public function isCornellIdP(): bool
+    {
+        return str_contains($this->idp, 'cit.cornell.edu');
+    }
+
+    public function isWeillIdP(): bool
+    {
+        return str_contains($this->idp, 'weill.cornell.edu');
+    }
+
+    /**
+     * Provides a uid that is unique across Cornell IdPs.
+     */
+    public function uniqueUid(): string
+    {
+        return match (true) {
+            $this->isCornellIdP() => $this->uid,
+            $this->isWeillIdP() => $this->uid.'_w',
+        };
+    }
+
+    /**
+     * Returns the primary email ([email protected]|[email protected]) if available, otherwise the alias email.
+     */
+    public function email(): string
+    {
+        return $this->email;
+    }
+
+    /**
+     * Returns the display name if available, otherwise the common name, fallback is "givenName sn".
+     */
+    public function name(): string
+    {
+        return $this->displayName;
+    }
+}

src/CUAuth/Events/CUAuthenticated.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace CornellCustomDev\LaravelStarterKit\CUAuth\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class CUAuthenticated
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(
+        public readonly string $remoteUser,
+    ) {}
+}

src/CUAuth/Http/Controllers/AuthController.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace CornellCustomDev\LaravelStarterKit\CUAuth\Http\Controllers;
+
+use CornellCustomDev\LaravelStarterKit\CUAuth\DataObjects\ShibIdentity;
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller as BaseController;
+use Illuminate\Support\Facades\Auth;
+
+class AuthController extends BaseController
+{
+    public function shibbolethLogin(Request $request)
+    {
+        $redirectUri = $request->query('redirect_uri', '/');
+
+        if (ShibIdentity::getRemoteUser($request)) {
+            // Already logged in so redirect to the originally intended URL
+            return redirect()->to($redirectUri);
+        }
+
+        // Use the Shibboleth login URL
+        return redirect(config('cu-auth.shibboleth_login_url').'?target='.urlencode($redirectUri));
+    }
+
+    public function shibbolethLogout(Request $request)
+    {
+        Auth::logout();
+        $request->session()->invalidate();
+        $request->session()->regenerateToken();
+
+        $returnUrl = $request->query('return', '/');
+
+        if (ShibIdentity::getRemoteUserOverride()) {
+            // If using locally configured remote user, there is no Shibboleth logout
+            return redirect()->to($returnUrl);
+        }
+
+        // Use the Shibboleth logout URL
+        return redirect(config('cu-auth.shibboleth_logout_url').'?return='.urlencode($returnUrl));
+    }
+}

src/CUAuth/Listeners/AuthorizeUser.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace CornellCustomDev\LaravelStarterKit\CUAuth\Listeners;
+
+use CornellCustomDev\LaravelStarterKit\CUAuth\DataObjects\ShibIdentity;
+use CornellCustomDev\LaravelStarterKit\CUAuth\Events\CUAuthenticated;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+
+class AuthorizeUser
+{
+    public function handle(CUAuthenticated $event, ?array $serverVars = null): void
+    {
+        $shibboleth = ShibIdentity::fromServerVars($serverVars);
+
+        // Look for a matching user.
+        $userModel = config('auth.providers.users.model');
+        $user = $userModel::firstWhere('email', $shibboleth->email());
+
+        if (empty($user)) {
+            // User does not exist, so create them.
+            $user = new $userModel;
+            $user->name = $shibboleth->name();
+            $user->email = $shibboleth->email();
+            $user->password = Str::random(32);
+            $user->save();
+            Log::info("AuthorizeUser: Created user $user->email with ID $user->id.");
+        }
+
+        auth()->login($user);
+        Log::info("AuthorizeUser: Logged in user $user->email.");
+    }
+}

src/CUAuth/Middleware/ApacheShib.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace CornellCustomDev\LaravelStarterKit\CUAuth\Middleware;
+
+use Closure;
+use CornellCustomDev\LaravelStarterKit\CUAuth\DataObjects\ShibIdentity;
+use CornellCustomDev\LaravelStarterKit\CUAuth\Events\CUAuthenticated;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class ApacheShib
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        // If local login is allowed and someone is authenticated, let them through.
+        if (config('cu-auth.allow_local_login') && auth()->check()) {
+            return $next($request);
+        }
+
+        // Shibboleth login route is allowed to pass through.
+        if ($request->path() == route('cu-auth.shibboleth-login')) {
+            return $next($request);
+        }
+
+        // remoteUser will be set for authenticated users.
+        $remoteUser = ShibIdentity::getRemoteUser($request);
+
+        // Unauthenticated get redirected to Shibboleth login.
+        if (empty($remoteUser)) {
+            return redirect()->route('cu-auth.shibboleth-login', [
+                'redirect_uri' => $request->fullUrl(),
+            ]);
+        }
+
+        // If requiring a local user, attempt to log in the user.
+        if (config('cu-auth.require_local_user') && ! auth()->check()) {
+            event(new CUAuthenticated($remoteUser));
+
+            // If the authenticated user is still not logged in, return a 403.
+            if (! auth()->check()) {
+                if (app()->runningInConsole()) {
+                    return response('Forbidden', Response::HTTP_FORBIDDEN);
+                }
+                abort(403);
+            }
+        }
+
+        return $next($request);
+    }
+}