Laravel Saml2 Laravel Package

Technical Evaluation

Basis of assessment: Derived solely from the v1.1.0 release notes. No source review, version matrix, or prior assessment exists, so the items below are framed as validation work rather than confirmed findings.

Architecture fit

• The package now conforms to the standard Laravel package contract: schema is delivered as a publishable stub via vendor:publish --tag=saml2-migrations, and the application owns execution via php artisan migrate.
• This is a correct architectural correction. Packages that run migrations from their own service provider bypass the host application's migration repository, break migrate:rollback/migrate:status semantics, and are effectively untestable in CI pipelines that use RefreshDatabase.
• The saml2_tenants table implies tenant-scoped IdP configuration (entity ID, ACS URL, signing certificates, metadata). That is a reasonable persistence model for a multi-tenant SAML2 service provider, but it makes tenant rows security-sensitive configuration, not ordinary application data.
• Removing run_migrations reduces the package's blast radius on the host database. Net positive for architecture review and for security questionnaires.

Integration feasibility

• New installs: two commands, no ambiguity. Low friction.
• Upgrades from 1.0: genuinely zero-touch, because the table already exists and the migration is written to be idempotent ("keeps an existing table and only adds what's missing").
• The removal of run_migrations is a breaking change to the configuration surface, but a low-severity one: it is a config key, not a public API, and the upgrade path does not require action.

Technical risk

• Silent no-op on upgrade. Laravel does not error on unknown config keys. Any deployment automation, Helm chart, or .env/config/saml2.php that still sets run_migrations will simply stop migrating. The failure surfaces as a missing table or missing column at authentication time — that is, as a login outage, not a deploy failure. This is the primary risk in the release.
• Idempotent "add what's missing" migrations are additive-only by design. That makes upgrades safe, but it also means the migration cannot express column renames, type changes, or index drops. Schema drift between an upgraded 1.0 install and a fresh 1.1 install is possible and will not be detected. Worth confirming whether there are index or constraint changes on saml2_tenants that only apply to fresh installs.
• Leftover documentation/config stub. If the published config file or docs still reference run_migrations, operators will set a dead key and assume migrations ran.
• Publish-tag collision. saml2-migrations is a shared namespace across all vendor packages. Confirm the tag is unique and that re-publishing over an existing published stub prompts rather than silently overwrites local edits.

Key questions

1. What exactly does the migration add to saml2_tenants, and are all changes additive?
2. Does the migration define a down() method, and is rollback meaningful for an auth-critical table?
3. Does the package fail loudly (clear exception, health check, or about command output) when the tenants table is absent or stale, rather than failing at first login?
4. Is run_migrations removed from the published config stub and from all documentation, or only from code?
5. What are the supported Laravel and PHP version bounds, and is there a deprecation policy for the config surface?
6. Does v1.1.0 change anything else (SAML libraries, certificate handling, security fixes) that the notes omit? Release notes covering only packaging changes on a minor version bump warrant a changelog diff.

Integration Approach

Stack fit

• Assumes a conventional Laravel application with database-backed sessions/queues and an artisan-driven deploy. No infrastructure dependency is introduced beyond the existing database.
• SAML2 integration carries environmental requirements that this release does not change: HTTPS on the ACS endpoint, accurate system clock (assertion NotBefore/NotOnOrAfter windows), and certificate rotation handling. These dominate operational risk far more than the migration mechanics.

Migration path

• New installs: vendor:publish --tag=saml2-migrations → artisan migrate. Add both to the environment bootstrap and to the test suite setup.
• Upgrades from 1.0: no action required. Recommended nonetheless: publish the stub on upgrade so the repository contains the current migration file. Otherwise the next schema change arrives with no published baseline, and the team has to reconcile a stub they have never tracked.
• Version pinning: pin to ^1.1 and record the installed version alongside the published stub, since the stub is now a copy the team maintains rather than a package-owned artifact.

Compatibility

• Verify the Laravel/PHP support matrix before merging into any long-lived branch.
• Verify published-stub behavior on re-publish: confirm it does not overwrite app-local modifications to previously published migrations.
• Confirm the tag namespace does not collide with other published migration tags in the same application.

Sequencing

1. Publish the migration stub and commit it.
2. Review the generated file — confirm additive-only, down() behavior, and index coverage on the tenant lookup column.
3. Run migrate on a single node / leader in the deploy, not concurrently across replicas. Laravel's migration lock is only advisory per connection.
4. config:clear / config:cache after deploy so any config stub changes take effect.
5. Restart queue workers and Octane/Swoole workers, which cache config and code in memory.
6. Verify: assert the tenants table exists with expected columns, and exercise one SAML login end-to-end in staging with a real IdP before promoting.
7. Update internal runbooks to remove run_migrations and document the publish step.

Operational Impact

Maintenance

• Fewer implicit behaviors to reason about; schema changes are now visible in code review and subject to normal DBA/audit process. That is a meaningful governance improvement for an auth-path table.
• Cost shifts to the application team: the published migration becomes team-owned code. Every package upgrade that touches schema requires a deliberate re-publish and diff. Budget a small recurring task; this is not free.
• Minor-version packaging changes like this one are low-risk but indicate the package is still settling its conventions. Expect further interface churn in the 1.x line.

Support

• Any existing runbook, .env template, or infrastructure-as-code value referencing run_migrations becomes misleading. Audit and remove.
• Support burden concentrates on SAML configuration errors (metadata mismatch, expired certificates, clock skew, ACS URL mismatch), not on this change. Ensure the on-call path can distinguish a schema error (table/column missing) from a SAML assertion error — the log signatures differ and the remediations are unrelated.

Scaling

• saml2_tenants is small and read-heavy: one read per authentication handshake. Cache tenant metadata in the application cache layer (Redis) with explicit invalidation on tenant update; do not hit the database on every SSO request if login volume is meaningful.
• Index the tenant resolution column (slug/domain/entity ID) explicitly; verify the migration creates it.
• SAML handshakes are latency-sensitive and CPU-bound on signature verification. Scale horizontally; there is no shared state beyond the tenant table and cache.

Failure modes

• Missing table at runtime — the headline risk. Automation still setting run_migrations silently stops migrating; the first symptom is a failed login for all users. Mitigate with a post-deploy schema assertion in the smoke test.
• Stale published stub after upgrade — the app's copy no longer matches the package's intent, and future columns never land. Mitigate with a CI check comparing the published stub hash to the installed package version.
• Concurrent migration across replicas — partial application and lock contention. Run migrations as a single ordered deploy step.
• Stale config cache — old config values survive the deploy. Always config:cache after publishing.
• Rollback ambiguity — if down() drops the tenants table, a rollback during an auth incident destroys configuration. Confirm behavior and prefer forward-fix over rollback for this table.

Ramp-up

• Mechanically, near-zero: publish-and-migrate is the most familiar pattern in the Laravel ecosystem, and this release moves the package toward convention rather than away from it.
• The real ramp is domain knowledge. A mid-level Laravel developer needs roughly one to two days to stand up a working SP integration against a test IdP and understand entity IDs, ACS bindings, signing versus encryption certificates, and metadata refresh. Add separate effort for tenant onboarding tooling — admin UI, validation of uploaded metadata, and certificate expiry alerting — which is product work the package does not provide.
• Recommend one engineer own SAML end-to-end, including certificate rotation, before the integration reaches production traffic.