Nova Okta Laravel Package

Getting Started

This package wires Okta (via bbs-lab/laravel-okta v3) into Laravel Nova: it overrides the Nova login page, exposes an Okta authorization-code flow bound to your Nova path, and bridges Okta MFA into Nova's two-factor.login route.

1. Install and publish config

   composer require bbs-lab/nova-okta
   php artisan vendor:publish --tag="nova-okta-config"
   

2. Fill in the Okta side first. In your Okta app, register:

   • Sign-in redirect URI: {nova-path}/authorization-code/callback
   • Sign-out redirect URI: {nova-path}/authorization-code/logout ← changed in v3.0.0
   • Initiate login URI: {nova-path}/authorization-code/logout/redirect (if you use IdP-initiated logout)

3. Set env vars (OKTA_* from laravel-okta, plus OKTA_CALLBACK_LOGOUT_PATH if you want to pin the logout path).

4. Verify the wiring without Okta by running php artisan route:list | grep nova-okta. You should see the login override, the callback, and the logout route names unchanged from prior versions.

First use case: point a browser at /nova, get bounced to Okta, come back authenticated, then click "Sign out" and confirm you land back on the Nova login screen rather than looping through Okta. That single round trip exercises every path this release touched.

Implementation Patterns

Logout is still a named route. v3.0.0 changed the defaults behind the routes, not the API. Keep calling:

route('nova-okta.logout')   // initiates logout

Never hardcode authorization-code/logout or /logout/redirect in Blade, redirects, or JS — read the config keys (nova-okta.logout, nova-okta.callback.logout) or use the route name.

Custom Nova paths come for free. NovaOktaPanel derives its URI from path(), so if you run Nova at /admin, your Okta URIs become /admin/authorization-code/.... Confirm this in config/nova.php before touching Okta's app config — a mismatch here is the #1 cause of "invalid redirect_uri" errors.

Multi-panel / multi-guard setups. If you register more than one Nova panel with different auth guards, register the Okta panel per-guard and keep the Okta app's redirect URIs aligned one-to-one with each path. Route names are global, so only one nova-okta.logout will exist — resolve the right one explicitly if you fork paths.

Two-factor stays untouched. The two-factor.login bridge means Okta-verified users still hit Nova's 2FA challenge as before. If you have custom 2FA logic in a Fortify-style listener, it keeps working — don't reimplement it inside the Okta callback.

Local development. Keep an .env.local that bypasses Okta entirely (or point at a dev Okta tenant) rather than mocking the flow; the package's routes assume a live IdP redirect. For tests, assert against route names and config keys, not literal URIs — that keeps your suite green across the v2→v3 path change.

Upgrade from v2.0.0. Do the Okta dashboard change before deploying the composer bump, or in the same change window. Order matters: deployed code + stale Okta sign-out URI = failed logout. If you can't coordinate, pin OKTA_CALLBACK_LOGOUT_PATH to the old value, deploy, update Okta, then unpin.

From v1.x or a standard Okta app already whitelisting authorization-code/logout: nothing to do — the v3 default matches what you already have.

Gotchas and Tips

• The v3.0.0 logout path change is the breaking bit. nova-okta.callback.logout moved from .../callback/logout → .../logout, and nova-okta.logout moved from .../logout → .../logout/redirect. Note the nasty overlap: the old initiator value is the new redirect-URI value. If you grep your config and find authorization-code/logout, you cannot tell from the string alone whether it's stale or correct — check which key it lives under.
• Symptom of a stale sign-out URI: logout appears to succeed but Okta refuses the redirect, leaving users on an Okta error page or bouncing back authenticated. Check the Okta system log for invalid_redirect_uri.
• config:cache hides env changes. After setting OKTA_CALLBACK_LOGOUT_PATH, run php artisan config:clear && php artisan config:cache. CI pipelines that cache config before injecting env will silently use the wrong path.
• Trailing slashes matter to Okta. .../logout and .../logout/ are different URIs to the IdP. Copy the value out of config/nova-okta.php rather than typing it.
• Debugging order: route:list → config('nova-okta.*') via tinker → Okta app's registered URIs → Okta system log. The package inherits path() with no src change in v3, so if the Nova path looks right in route:list, the bug is almost certainly on the Okta dashboard side.
• Extension point: because the URIs are config-driven, per-environment Okta apps (dev/staging/prod) are just env vars. Don't subclass NovaOktaPanel for this — override config.
• Quality signals are strong: Pest at 100% coverage and 100% MSI, PHPStan level 8, Pint, green across Nova 5 × Laravel 11/12/13 × PHP 8.3/8.4. You can lean on the package's own suite when filing issues, and you can safely run PHPStan 8 in your app alongside it.
• Version alignment: this package's v3.0.0 is a thin adoption of bbs-lab/laravel-okta v3.0. If you also use laravel-okta directly elsewhere in the app, bump both together — mixed majors will disagree about route paths.