|
| 1 | +# CUAuth |
| 2 | + |
| 3 | +Middleware for authorizing Laravel users. |
| 4 | + |
| 5 | +- [CUAuth SSO](#cuauth) - Single sign-on and authorization middleware |
| 6 | + - SAML PHP Toolkit integration |
| 7 | + - Apache mod_shib integration |
| 8 | +- [AppTesters](#apptesters) - Limit access to users in the `APP_TESTERS` environment variable |
| 9 | +- [Local Login](#local-login) - Allow Laravel users to log in with a local username and password |
| 10 | + |
| 11 | +## Use Cases |
| 12 | + |
| 13 | +- **Single Sign-On**: Protect routes with SSO (mod_shib or PHP SAML) |
| 14 | + - Optionally log in SSO users to app user accounts |
| 15 | +- **AppTesters**: Limit access on non-production sites to users in the `APP_TESTERS` environment variable |
| 16 | + |
| 17 | + |
| 18 | +## Single Sign-On |
| 19 | + |
| 20 | +### Usage |
| 21 | + |
| 22 | +```php |
| 23 | +// File: routes/web.php |
| 24 | +use CornellCustomDev\LaravelStarterKit\CUAuth\Middleware\CUAuth; |
| 25 | + |
| 26 | +Route::group(['middleware' => [CUAuth::class]], function () { |
| 27 | + // Protected routes here |
| 28 | + Route::get('profile', [UserController::class, 'show']); |
| 29 | +}); |
| 30 | +``` |
| 31 | + |
| 32 | +```dotenv |
| 33 | +# File: .env |
| 34 | +# apache-shib (default) | php-saml |
| 35 | +CU_AUTH_IDENTITY_MANAGER=apache-shib |
| 36 | +``` |
| 37 | + |
| 38 | +See [Authorization](#identity-and-authorization) for details on how to log in remote users for local authorization. |
| 39 | + |
| 40 | +> _See also: [shibboleth configuration](SHIBBOLETH.md)._ |
| 41 | +
|
| 42 | +--- |
| 43 | + |
| 44 | +### Routing |
| 45 | + |
| 46 | +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 `'/'`): |
| 47 | +- Login: `route('cu-auth.sso-login', ['redirect_url' => '/home'])` |
| 48 | +- Logout: `route('cu-auth.sso-logout', ['return' => '/'])` |
| 49 | + |
| 50 | +### Certs and Metadata (php-saml) |
| 51 | + |
| 52 | +For using the PHP SAML Toolkit, the SAML keys and certs can be generated with the following command, or as an option from the starter kit installer: |
| 53 | + |
| 54 | +```bash |
| 55 | + php artisan cu-auth:generate-keys |
| 56 | +``` |
| 57 | + |
| 58 | +The SAML metadata can be retrieved at `https://<site-url>/sso/metadata`. |
| 59 | + |
| 60 | +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`. |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +### Local Testing (apache-shib) |
| 65 | +For local testing where mod_shib is not available, the `REMOTE_USER` environment variable can be set to simulate |
| 66 | +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. |
| 67 | + |
| 68 | +```dotenv |
| 69 | +# File: .env |
| 70 | +APP_ENV=local |
| 71 | +REMOTE_USER=abc123 |
| 72 | +``` |
| 73 | + |
| 74 | +## Identity and Authorization |
| 75 | + |
| 76 | +Once authenticated via SSO, the user's identity is available via the `IdentityManager`, which can be accessed via the app container. |
| 77 | + |
| 78 | +```php |
| 79 | +use CornellCustomDev\LaravelStarterKit\CUAuth\Managers\IdentityManager; |
| 80 | + |
| 81 | +$remoteIdentity = app(IdentityManager::class)->getIdentity(); |
| 82 | +$netid = $remoteIdentity->id(); // NetID | CWID |
| 83 | + |
| 84 | +// If provided with SSO attributes: |
| 85 | +$email = $remoteIdentity->email(); // Primary email (i.e. [email protected]) |
| 86 | +$name = $remoteIdentity->name(); // Display name |
| 87 | +``` |
| 88 | + |
| 89 | +### User authorization |
| 90 | + |
| 91 | +If the site should manage authorization for users in the application, set `config('cu-auth.require_local_user')` to true: |
| 92 | + |
| 93 | +```php |
| 94 | +# File: config/cu-auth.php |
| 95 | +'require_local_user' => env('REQUIRE_LOCAL_USER', true), |
| 96 | +``` |
| 97 | + |
| 98 | +Requiring a local user triggers the `CUAuthenticated` event when a user is authenticated via single sign-on. The site must |
| 99 | +[register a listener](https://laravel.com/docs/11.x/events#registering-events-and-listeners) for |
| 100 | +the `CUAuthenticated` event. This listener should look up the user in the database and log them in or create a user |
| 101 | +as needed. |
| 102 | + |
| 103 | +> [AuthorizeUser](Listeners/AuthorizeUser.php) is provided as a starting point for handling the CUAuthenticated event. |
| 104 | +> It is simplistic and should be replaced with a site-specific implementation in the site code base. It demonstrates |
| 105 | +> retrieving user data via the [IdentityManager](Managers/IdentityManager.php) and creating a user if they do not exist. |
| 106 | +
|
| 107 | + |
| 108 | +## Configuration |
| 109 | + |
| 110 | +See [config/cu-auth.php](../../config/cu-auth.php) for configuration options, all of which can be set with environment variables. |
| 111 | + |
| 112 | +To modify the default configuration, publish the configuration file: |
| 113 | + |
| 114 | +```bash |
| 115 | + php artisan vendor:publish --tag=starterkit:cu-auth-config |
| 116 | +``` |
| 117 | + |
| 118 | +To modify the PHP SAML Toolkit configuration, publish the configuration file: |
| 119 | + |
| 120 | +```bash |
| 121 | + php artisan vendor:publish --tag=starterkit:php-saml-toolkit-config |
| 122 | +``` |
| 123 | + |
| 124 | + |
| 125 | +## AppTesters |
| 126 | + |
| 127 | +Limits non-production access to users in the `APP_TESTERS` environment variable. |
| 128 | + |
| 129 | +### Usage |
| 130 | + |
| 131 | +```php |
| 132 | +// File: routes/web.php |
| 133 | +use CornellCustomDev\LaravelStarterKit\CUAuth\Middleware\AppTesters; |
| 134 | +use CornellCustomDev\LaravelStarterKit\CUAuth\Middleware\CUAuth; |
| 135 | + |
| 136 | +Route::group(['middleware' => [CUAuth::class, AppTesters::class], function () { |
| 137 | + Route::get('profile', [UserController::class, 'show']); |
| 138 | +}); |
| 139 | +``` |
| 140 | + |
| 141 | +```dotenv |
| 142 | +# File: .env |
| 143 | +APP_TESTERS=abc123,def456 |
| 144 | +``` |
| 145 | + |
| 146 | +On non-production sites, the [AppTesters](Middleware/AppTesters.php) 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. |
| 147 | + |
| 148 | +The field used for looking up users is `netid` by default. It is configured in [config/cu-auth.php](../../config/cu-auth.php) file as `app_testers_field`. |
| 149 | + |
| 150 | + |
| 151 | +## Local Login |
| 152 | +For testing purposes, the environment variable "ALLOW_LOCAL_LOGIN" can be set to true to bypass the middleware for a currently authenticated user. |
| 153 | +```dotenv |
| 154 | +# File: .env |
| 155 | +ALLOW_LOCAL_LOGIN=true |
| 156 | +
|
0 commit comments