Download the PHP package bbs-lab/nova-okta without Composer

Nova Okta

Okta SSO for Laravel Nova. Ships a custom Nova-styled login screen with a Log In with Okta button and an optional Fortify two-factor challenge bridge, so any Laravel Nova project gets Okta login by requiring the package and setting a few env vars. The login screen respects your Nova branding — it renders nova.brand.logo (or the name) and uses nova.brand.colors for the primary colour, including the Okta button.

It is the Nova adapter for bbs-lab/laravel-okta, which is installed automatically and owns the framework-agnostic Okta flow: the Socialite driver, the login / callback / logout controller, the user resolver, and the lifecycle hooks. This package adds the Nova-specific parts — the login screen, the login override and the 2FA bridge — and points the base flow at Nova's guard and path.

Requirements

• PHP 8.2+
• Laravel 11, 12 or 13
• Laravel Nova 5

Installation

Nova is a paid package, so authenticate against its Composer repository first, then require the package:

Both service providers are auto-discovered.

Okta application

In your Okta admin, create an OIDC / Web application and set:

• Sign-in redirect URI: {APP_URL}/{nova-path}/authorization-code/callback
• Sign-out redirect URI: {APP_URL}/{nova-path}/authorization-code/logout

where {nova-path} is your config('nova.path') (e.g. nova, or empty when Nova is mounted at the root). These paths are configurable — see Routes.

Credentials

Add the okta block to config/services.php (the package intentionally does not own your credentials):

OKTA_BASE_URL is the bare org URL (no /oauth2). Keep the redirect key present (it may be null).

OKTA_REDIRECT_URI is optional. The redirect URI is a route this package generates (under your Nova path), so when it is not set the package derives it from the callback route automatically — you only declare the matching Sign-in redirect URI in your Okta application. Set it only to override the derived URL (e.g. behind a reverse proxy).

Configuration

Nova-specific options

Okta behaviour (from the base)

The route paths, SSO logout, verified-email enforcement and stable-identifier matching live in the base package's config/okta.php:

User resolution, gating & lifecycle hooks

There is deliberately no user-mapping config — the base resolves an Okta account through Nova's guard's own user provider (by a stable id column then a verified email, never creating a user), and everything else is a hook on the BBSLab\LaravelOkta\Facades\Okta facade (resolveUserUsing, authorizeUserToLogin, beforeLogin, afterLogin, onLoginDenied) or a custom BBSLab\LaravelOkta\Contracts\OktaUserResolver.

The default resolver does not gate — it signs in any user it finds by email. Deciding who may sign in is your job. Set an authorization rule for a Nova panel.

For Nova, gate the Okta sign-in and/or Nova's own access gate — for example in your App\Providers\NovaServiceProvider:

authorizeUserToLogin stops a disallowed account at the SSO boundary (nothing is logged in, and onLoginDenied fires); viewNova is Nova's own gate that also guards password logins and every subsequent request. Use either or both.

See the bbs-lab/laravel-okta README for the hooks, the stable-identifier config, and how to extend DefaultOktaUserResolver for a reusable gate. A denied login flashes the error to the custom login screen.

How it works

The base registers the Okta Socialite driver and mounts these routes; this package adds the login override and the 2FA bridge. Every URI is prefixed by your Nova path — config('nova.path') (nova by default), read at boot — so with Nova mounted at /backend-panel the callback is /backend-panel/authorization-code/callback. Below, {nova-path} stands for that prefix:

The four authorization-code/* paths are configurable via the base package's okta.paths config (below); the route names are stable whatever the path, so reference them with route('nova-okta.login') rather than hard-coding a URI. When Nova is mounted at the root, {nova-path} is empty (e.g. /authorization-code/callback).

Logout name↔URI inversion (by design). nova-okta.logout initiates logout but mounts at the nested authorization-code/logout/redirect, while the post-logout landing nova-okta.callback.logout mounts at the short authorization-code/logout (the Okta sign-out redirect URI). Reference routes by name; do not swap the pairing.

The 2FA bridge is a redirect to Nova's native nova.two-factor.login (not a re-registration of its URI), so Nova keeps its middleware and the bridge is route:cache-safe.

Point Nova's user-menu logout link at the Okta-aware logout in your NovaServiceProvider:

Two-factor and forced enrolment

The 2FA challenge bridge (two-factor.login) lets a 2FA-enabled user complete the second factor on top of the custom login — enable Nova's 2FA in your NovaServiceProvider:

Forcing enrolment in 2FA is out of scope here — use bbs-lab/nova-force-two-factor. On an Okta login the base sets an okta_authenticated session flag so that package can skip forced enrolment for SSO users (Okta already enforces MFA).

Customising the login screen

Testing

Browser & live e2e

The browser (Pest v4) and live Playwright suites cover the pre-redirect login UX (the Okta button and the start of the OIDC redirect); the full SSO round-trip needs a real Okta org.

Security

• Verified emails. The base's default resolver rejects unverified Okta emails (require_verified_email). If you replace the resolver, keep an equivalent check.
• Logout is a GET (so it can be a Nova user-menu external link), which is why it relies on the framework's default SESSION_SAME_SITE=lax to prevent cross-site logout. Keep SameSite at lax/strict; if you set it to none, wire logout as a POST form instead.

Please email [email protected] for security issues instead of the issue tracker.

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Credits

• Big Boss Studio

License

The MIT License (MIT). See LICENSE.md.