cornell-custom-dev/laravel-cu-auth

A Laravel package for authentication and identity management at Cornell University

v1.1.0 2025-10-14 22:10 UTC

Requires

• php: ^8.2
• ext-openssl: *
• illuminate/contracts: ^11.0|^12.0
• onelogin/php-saml: ^4.3

Requires (Dev)

• laravel/pint: ^1.20
• orchestra/testbench: ^9.0|^10.0
• phpunit/phpunit: ^10.5|^11.5

MIT

README

Middleware for authorizing Laravel users.

• CUAuth SSO - Single sign-on and authorization middleware
  • SAML PHP Toolkit integration
  • Apache mod_shib integration
• AppTesters - Limit access to users in the APP_TESTERS environment variable
• Local Login - Allow Laravel users to log in with a local username and password

Use Cases

• Single Sign-On: Protect routes with SSO (mod_shib or PHP SAML)
  • Optionally log in SSO users to app user accounts
• AppTesters: Limit access on non-production sites to users in the APP_TESTERS environment variable

Single Sign-On

Usage

// File: routes/web.php
use CornellCustomDev\LaravelStarterKit\CUAuth\Middleware\CUAuth;

Route::group(['middleware' => [CUAuth::class]], function () {
    // Protected routes here
    Route::get('profile', [UserController::class, 'show']);
});

# File: .env
# apache-shib (default) | php-saml
CU_AUTH_IDENTITY_MANAGER=apache-shib

See Authorization for details on how to log in remote users for local authorization.

See also: shibboleth configuration.

Routing

Any pages protected by middleware are automatically redirected to SSO. To directly trigger log in or log out, use the following routes (parameters are optional and will default to '/'):

• Login: route('cu-auth.sso-login', ['redirect_url' => '/home'])
• Logout: route('cu-auth.sso-logout', ['return' => '/'])

Certs and Metadata (php-saml)

For using the PHP SAML Toolkit, the SAML keys and certs can be generated with the following command:

  php artisan cu-auth:generate-keys

It is possible to have composer automatically install the keys on composer install by adding the following to the scripts section of composer.json, which will only install the keys if they do not already exist:

"scripts": {
    "post-install-cmd": [
        "@php artisan cu-auth:generate-keys"
    ]
}

The default location for the SAML keys and certs is in storage/app/keys. This location is configurable in the config/cu-auth.php file or by setting the SAML_CERT_PATH in .env.

Local Testing (apache-shib)

For local testing where mod_shib is not available, the REMOTE_USER environment variable can be set to simulate Shibboleth authentication. Note that APP_ENV must be set to "local" for this to work and the config cache must be cleared when REMOTE_USER is changed.

# File: .env
APP_ENV=local
REMOTE_USER=abc123

Identity and Authorization

Once authenticated via SSO, the user's identity is available via the IdentityManager, which can be accessed via the app container.

use CornellCustomDev\LaravelStarterKit\CUAuth\Managers\IdentityManager;

$remoteIdentity = app(IdentityManager::class)->getIdentity();
$netid = $remoteIdentity->id(); // NetID | CWID

// If provided with SSO attributes:
$email = $remoteIdentity->email(); // Primary email (i.e. [e-mail])
$name = $remoteIdentity->name(); // Display name

The SAML attributes available are based on the CIT-documented list: https://it.cornell.edu/shibboleth/shibboleth-faq.

User authorization

If the site should manage authorization for users in the application, set config('cu-auth.require_local_user') to true:

# File: config/cu-auth.php
'require_local_user' => env('REQUIRE_LOCAL_USER', true),

Requiring a local user triggers the CUAuthenticated event when a user is authenticated via single sign-on. The site must register a listener for the CUAuthenticated event. This listener should look up the user in the database and log them in or create a user as needed.

AuthorizeUser is provided as a starting point for handling the CUAuthenticated event. It is simplistic and should be replaced with a site-specific implementation in the site code base. It demonstrates retrieving user data via the IdentityManager and creating a user if they do not exist.

Configuration

See config/cu-auth.php for configuration options, all of which can be set with environment variables.

To modify the default configuration, publish the configuration file:

  php artisan vendor:publish --tag=starterkit:cu-auth-config

To modify the PHP SAML Toolkit configuration, publish the configuration file:

  php artisan vendor:publish --tag=starterkit:php-saml-toolkit-config

AppTesters

Limits non-production access to users in the APP_TESTERS environment variable.

Usage

// File: routes/web.php
use CornellCustomDev\LaravelStarterKit\CUAuth\Middleware\AppTesters;
use CornellCustomDev\LaravelStarterKit\CUAuth\Middleware\CUAuth;

Route::group(['middleware' => [CUAuth::class, AppTesters::class], function () {
    Route::get('profile', [UserController::class, 'show']);
});

# File: .env
APP_TESTERS=abc123,def456

On non-production sites, the AppTesters middleware checks the "APP_TESTERS" environment variable for a comma-separated list of users. If a user is logged in and not in the list, the middleware will return an HTTP_FORBIDDEN response.

The field used for looking up users is netid by default. It is configured in config/cu-auth.php file as app_testers_field.

Local Login

For testing purposes, the environment variable "ALLOW_LOCAL_LOGIN" can be set to true to bypass the middleware for a currently authenticated user.

# File: .env
ALLOW_LOCAL_LOGIN=true