Moving from wayne-cas#
Apps that use wayne-cas can move to SESAME without rewriting their auth. Open sesame, indeed: the same door, a new lock. The easy way is Booster's cas-to-sesame hop; the by-hand path is below it.
The easy way: Booster's cas-to-sesame hop#
Booster plans the hop with --sesame, and leaves it out with a warning when the plan ends below PHP 8.3, which SESAME needs. It lands just before the hop from Laravel 10 to 11, and while PHP is still below 8.3 the PHP hops go first. What the hop does:
- Writes
config/sesame.phpfrom the app'sconfig/wayne-cas.phpwhen the oldrootis a plain string (the old root becomes the fallback forcas.base_url), or from SESAME's published defaults when the app has no wayne-cas config at all.user_resolverdefaults to\Waynestate\Sesame\Laravel\ModelUserResolver::class. - Moves the CAS middleware off the global
webgroup and onto the app's web routes, with theauth.sesamemiddleware. - Points the web guard at the
sesamedriver and the users provider ateloquent, adding a model key when the provider has none. - Rewrites user models so they keep their static
findOrImportUserand use the app's own copy of theReadOnlyAttributestrait. - Swaps the Composer requirement to
waynestate/sesame:^0.8(SESAME is on Packagist, so no extra repository is needed; Booster 1.19.0 and later write^0.8. Booster 1.14.0 to 1.18.0 wrote^0.7, so an app they hopped takes the 0.8.0 step to move to^0.8; Booster 1.12.0 and 1.13.0 wrote^0.6, so take the 0.7.0 and 0.8.0 steps, and an app hopped by an earlier Booster got^0.4, so take the 0.5.0, 0.6.0, 0.7.0 and 0.8.0 steps) and drops thewayne-caspackage, anywayne-caspath entry and its VCS repository entries. - Removes
config/wayne-cas.phpwhen nothing in the app reads its config keys any more; while anything still does, the file stays and a manual note names the readers. - Flags the dead
DUO_*settings in example env files.
By hand#
SESAME 0.8.0 has no compatibility layer, so the app moves straight to SESAME's own names.
The mapping#
The mapping:
| wayne-cas | SESAME 0.8.0 |
|---|---|
wayne-cas.root |
sesame.cas.base_url |
auth.providers.users.model |
auth.providers.users.model (unchanged) |
the model's WayneCasable trait |
the model keeps its static findOrImportUser; config/sesame.php sets user_resolver to \Waynestate\Sesame\Laravel\ModelUserResolver::class |
| the model's read-only attributes | the app's own copy of the ReadOnlyAttributes trait (app/Models/Concerns/ReadOnlyAttributes.php) |
WayneAuthenticate middleware |
auth.sesame on the app's route groups (a guest gets a redirect to the login route, a JSON request a 401, not wayne-cas's 403) |
auth()->user() through the wayneCas guard |
auth()->user() with the guard pointed at sesame, or app(Sesame::class)->user() |
use2FA |
not carried; require MFA with the sesame.mfa middleware or leave it to Duo at the IdP |
The model#
The model. wayne-cas found the user through the model's static findOrImportUser, with the verified username as the access ID. The model keeps that method, and config/sesame.php points user_resolver at \Waynestate\Sesame\Laravel\ModelUserResolver::class, which finds the user through it:
use App\Models\Concerns\ReadOnlyAttributes;
class User extends Model
{
use Notifiable, ReadOnlyAttributes;
public static function findOrImportUser($accessId)
{
return static::firstOrCreate(['username' => $accessId]);
}
public function getReadOnlyAttributes($persistedAttributes = []): array
{
return [
'cn' => $persistedAttributes['cn'] ?? null,
];
}
}
The read-only attributes come from the app's own copy of the trait, in app/Models/Concerns/ReadOnlyAttributes.php (The ReadOnlyAttributes trait below). getReadOnlyAttributes is public, keeping its $persistedAttributes parameter.
ModelUserResolver also looks the signed-in user up again on every request (a plain find by primary key, never an import, so a deleted account stays deleted). An Eloquent model works as it is, with or without JSON session serialization, so the app needs no resolver of its own.
The middleware#
The middleware. Protect the app's route groups with the auth.sesame middleware. It checks the SESAME session instead of the Laravel auth guard, and it sends unauthenticated users to the sesame.login route: a guest gets a redirect to the login route, and a JSON request gets a 401 (wayne-cas returned a 403). It belongs on the app's route groups, not the global web group, because it does not let the sesame.login, sesame.callback and sesame.logout routes through; an app that takes the routes over with sesame.routes = false must keep those names or exclude its routes.
The guard#
The guard. Apps that read the user through auth()->user() keep that call: point the app's guard at the sesame driver (see Laravel) and auth()->user(), Auth::check() and auth()->logout() all work against the SESAME session. Without the guard, the equivalent is app(Sesame::class)->user().
The service URL#
The service URL. wayne-cas built the service URL from the current request. SESAME takes sesame.cas.service_url from config; the Laravel adapter defaults it to the app's /login route when it is not set.
use2FA#
use2FA. wayne-cas's use2FA runs a Duo challenge that SESAME does not carry. Require MFA on the routes that need it with the sesame.mfa middleware (see Requiring MFA), or leave 2FA to Duo at the identity provider. Drop the DUO_HOSTNAME, DUO_IKEY, DUO_SKEY and DUO_AKEY settings: they do nothing under SESAME.
Leaving the shim (apps on 0.7.x)#
SESAME 0.8.0 has removed the shim: the Waynestate\Sesame\WayneCas namespace (UserResolver, WayneAuthenticate, WayneCasable, ReadOnlyAttributes and Deprecation) and the wayne.cas middleware alias are gone. An app still on the shim does these steps while it is on 0.7.x, before composer update to 0.8.0:
config/sesame.php. Makeuser_resolver\Waynestate\Sesame\Laravel\ModelUserResolver::class. It does exactly what the shim did: it finds the user throughauth.providers.users.modelvia its staticfindOrImportUser, and it looks the stored user up again on every request.- Routes. Swap the middleware from
'wayne.cas'to'auth.sesame'. Two differences: a guest gets a redirect to the login route (a JSON request a 401) instead of the 403 wayne-cas returned, andauth.sesamebelongs on the app's route groups, not the globalwebgroup, because it does not let thesesame.*routes through. - The model. Keep its static
findOrImportUser, and drop the oldWayneCasableinterface from the class declaration. ReadOnlyAttributes. An app that uses theReadOnlyAttributestrait copies it from The ReadOnlyAttributes trait below into the app (for exampleapp/Models/Concerns/ReadOnlyAttributes.php) before taking 0.8.0, which removes it with the rest of the namespace.- Verify. Sign in, and the log no longer carries the deprecation line.
The ReadOnlyAttributes trait#
SESAME 0.8.0 no longer ships the ReadOnlyAttributes trait, so an app keeps this copy of it.
<?php
namespace App\Models\Concerns;
use Illuminate\Database\Eloquent\Builder;
/**
* Class ReadOnlyAttributes
* @package App\Models\Concerns
*
* This trait manages the "extra" attributes that the User model will have, typically fields retrieved
* from the Banner database that are immutable. To use this trait, you must implement the
* abstract method `getReadOnlyAttributes` which should return a key=>value pair array of attributes and
* attributeValues that will be set as read-only on the model. How you determine the readOnly attributes
* is entirely up to you.
*/
trait ReadOnlyAttributes
{
/** @var array<int, string> */
private $readOnlyAttributes = [];
/**
* Get an array of attribute => attributeValue pairs that will be read-only for the Eloquent model.
* Attributes can be native to the model (i.e. part of the database table).
*
* The same signature the WayneCasable interface declares, so a model
* that implements the interface and uses this trait satisfies both.
*
* @param array<string, mixed> $persistedAttributes
* @return array<string, mixed>
*/
abstract public function getReadOnlyAttributes($persistedAttributes = []): array;
/**
* Get the attributes that have been changed since last sync.
* We exclude the read-only attributes so they won't trigger a database call if changed.
*
* @return array<string, mixed>
*/
public function getDirty()
{
$dirty = [];
$attributes = array_filter($this->attributes, function ($key) {
return ! in_array($key, (array) $this->readOnlyAttributes, true); // @phpstan-ignore cast.useless (defensive cast: the property is written through an untyped setter)
}, ARRAY_FILTER_USE_KEY);
foreach ($attributes as $key => $value) {
if (! array_key_exists($key, $this->original)) {
$dirty[$key] = $value;
} elseif ($value !== $this->original[$key]) {
if ((method_exists($this, 'originalIsNumericallyEquivalent') && ! $this->originalIsNumericallyEquivalent($key))
|| (method_exists($this, 'originalIsEquivalent') && ! $this->originalIsEquivalent($key))) { // @phpstan-ignore function.alreadyNarrowedType (guard kept for older Laravel versions without originalIsEquivalent)
$dirty[$key] = $value;
}
}
}
return $dirty;
}
/**
* @param Builder<static> $query
* @param array<string, mixed> $attributes
* @return void
*/
protected function insertAndSetId(Builder $query, $attributes)
{
// We exclude the read-only attributes so they aren't persisted
$attributes = array_diff($attributes, $this->readOnlyAttributes);
// Then we let the parent method do all the hard work
parent::insertAndSetId($query, $attributes);
// parent::insertAndSetId() has just set the newly generated key on the
// instance. Carry it into $attributes, because setRawAttributes(..., true)
// below replaces the whole attribute set and would otherwise discard it,
// leaving the model with a null key immediately after save().
//
// This is latent for the usage the README documents, where the access ID
// is the primary key and is assigned before save, so it is already in
// $attributes. It bites whenever the key is generated by the database,
// which is the ordinary Eloquent case.
$attributes[$this->getKeyName()] = $this->getKey();
// Now we refresh the read-only attributes and values
$readOnlyAttributes = $this->getReadOnlyAttributes($attributes);
// merge them with the native attributes
$attributes = array_merge($attributes, $readOnlyAttributes);
// set them on the instance
$this->setRawAttributes($attributes, true);
// and finally register the read-only attributes to prevent persistence in future database calls
$this->setReadOnlyAttributes(array_keys($readOnlyAttributes));
}
/**
* @param array<string, mixed> $attributes
* @param string|\UnitEnum|null $connection
* @return static
*/
public function newFromBuilder($attributes = [], $connection = null)
{
// Here we grab the attribute => attributeValue pairs the developer defines for this model
$readOnlyAttributes = $this->getReadOnlyAttributes((array) $attributes); // @phpstan-ignore cast.useless (defensive cast: the parameter is untyped at runtime)
// merge them with the native attributes
$attributes = array_merge((array) $attributes, $readOnlyAttributes); // @phpstan-ignore cast.useless (defensive cast: the parameter is untyped at runtime)
// let the parent method do the work of hydrating an instance with them
$model = parent::newFromBuilder($attributes, $connection);
// and finally register the read-only attributes to prevent persistence in future database calls
$model->setReadOnlyAttributes(array_keys($readOnlyAttributes));
// oh yeah, we also have to return the freshly hydrated model. duh!
return $model;
}
/**
* @param array<int, string> $readOnlyAttributes
* @return void
*/
public function setReadOnlyAttributes($readOnlyAttributes)
{
$this->readOnlyAttributes = $readOnlyAttributes;
}
}
What Booster leaves for you#
- Duo 2FA is not carried. If the app had
use2FAenabled, re-enable two-factor in the app itself, and drop theDUO_HOSTNAME,DUO_IKEY,DUO_SKEYandDUO_AKEYsettings: they do nothing under SESAME. - Log in through the pre-production host before you ship, and check the session timeout, the Access ID attribute and Duo there.
auth()->user()now comes from SESAME's guard and is reloaded every request (ModelUserResolverlooks the user up again throughauth.providers.users.model), so check that signed-in pages and any Gate or policy checks still work.