Download the PHP package ua/okta-oidc without Composer

UA Laravel Okta OIDC

A reusable Okta OIDC authentication package for Laravel applications. Provides login, callback, logout, and session-expiry flows out of the box — without forcing any particular local user model on your app.

Requirements

• PHP 8.2+ (PHP 8.3+ for Laravel 13)
• Laravel 11, 12, or 13

Quick Start

1. Install the package

2. Publish the config

3. Add your Okta credentials to .env

4. Protect your routes

That's it. Unauthenticated users are redirected to Okta, and after login they land back on the page they originally requested.

How It Works

When a user hits a protected route:

1. The okta-oidc.auth middleware checks for a valid OIDC session
2. If missing/expired, the user is redirected to Okta to sign in
3. After Okta authentication, the callback route:
   • Resolves a principal (username, email, etc.) via a PrincipalResolver
   • Stores the principal, ID token, and expiration in the session
   • Runs a UserBootstrapper to perform any additional setup (session claims, database user, etc.)
   • Redirects back to the originally requested page

If the state parameter Okta returns does not match the one stored in the session, the callback cannot be trusted and the user is redirected to the expired page with the okta_oidc_expired flash flag — the same state the okta-oidc.auth middleware uses for a dead session. This usually means a stale login tab, a back-button revisit, or a session that did not survive the round trip.

The expired page is deliberately a terminal destination with a sign-in link, rather than an automatic bounce back to okta-oidc.login. If the underlying cause is that sessions are not persisting at all, an automatic retry would loop between the callback and Okta indefinitely, since Okta still holds an authenticated session and redirects back without any user interaction.

Routes

The package registers these routes under the auth/oidc prefix (configurable):

Principal Resolvers

A PrincipalResolver extracts a user identifier from the OIDC user object returned by Okta. This identifier is stored in the session as the "principal" — typically a username or email.

Built-in Resolvers

To switch resolvers, update config/okta-oidc.php:

Creating Your Own

Implement Ua\LaravelOktaOidc\Contracts\PrincipalResolver:

Then reference it in config:

User Bootstrappers

A UserBootstrapper runs after authentication to perform app-specific setup — storing claims in the session, creating database records, calling Auth::login(), etc. The bootstrapper is called after the core session keys (principal, ID token, expiration) are already stored.

Built-in Bootstrappers

NullUserBootstrapper

Does nothing. Use this if you only need the core session keys and handle everything else yourself.

SessionUserBootstrapper (Default)

Stores configurable OIDC claims into the session. Controlled by the session_claims config:

Accessor types:

After login, access the claims from the session:

You can add your own claims to the mapping:

EloquentUserBootstrapper

Extends SessionUserBootstrapper — stores session claims and creates/updates a local Eloquent User record, then calls Auth::login(). This gives you full Auth::user() support backed by Laravel's default users table.

On each login it:

1. Stores OIDC claims in the session (inherited from SessionUserBootstrapper)
2. Finds or creates a User by email (firstOrCreate)
3. Syncs the user's name from Okta
4. Sets a random hashed password on first creation (users authenticate via OIDC, not passwords)
5. Calls Auth::login($user)

The User model class is configurable:

Or via environment variable:

Guard Hydration (hydrate_guard)

By default, the session-only bootstrappers never touch Laravel's auth guard, so Auth::user() returns null even though the OIDC session is valid. That means guard-based tooling — monitoring like Laravel Nightwatch, Auth::id() in logs, etc. — sees every request as a guest.

If your app has no local users table (or you just don't want database-backed users), enable guard hydration:

When enabled, the okta-oidc.auth middleware populates the default guard on every request with a valid OIDC session, using a GenericUser built from the session:

• id — the principal (e.g. the username)
• name — from the getName session claim, when stored
• email — from the getEmail session claim, when stored

This is request-scoped only: Auth::setUser() does not log the user in or store anything in the session, and no user provider or database lookup is involved. If a real user is already authenticated (e.g. via EloquentUserBootstrapper), hydration is skipped and the real user wins.

With SESSION_DRIVER=database, Laravel copies Auth::id() into sessions.user_id on every session write. That column is a numeric foreignId in Laravel's default migration, so the package registers its own database session handler that stores null there for the hydrated user. The principal still reaches Auth::id(), logs, and Nightwatch; real authenticated users are stored exactly as before. No migration change is needed.

Note: With hydration enabled, anything guard-based — the auth middleware, policies, Auth::check() — will see the generic user on routes behind okta-oidc.auth. If parts of your app rely on Auth::check() being false for OIDC-only sessions, leave this off.

Creating Your Own

Implement Ua\LaravelOktaOidc\Contracts\UserBootstrapper:

Or extend SessionUserBootstrapper to keep the session claim behavior and add your own logic on top:

Then reference it in config:

Session Data

After a successful login, the following session keys are available:

The first three are always set by the controller. The rest depend on your session_claims config and which bootstrapper you're using.

Session keys are configurable:

Middleware Behavior

The okta-oidc.auth middleware protects routes by checking for a valid OIDC session. It handles expired sessions differently based on the request type:

Branches are evaluated in this order; the first match wins:

This prevents accidental form resubmission after session expiry.

Inertia.js Support

If you're using Inertia.js, the middleware automatically detects Inertia requests via the X-Inertia header and responds with HTTP 409 plus an X-Inertia-Location header. The Inertia client treats this as an external redirect and performs a full-page browser navigation — which is required to handle the redirect chain to Okta correctly. Detection is header-based, so the package does not depend on inertiajs/inertia-laravel.

Federated Logout

By default, logging out clears the local session and redirects to Okta's logout endpoint to end the Okta session. This prevents users from being silently re-authenticated on the next visit.

Disable it if you only want to clear the local session:

Configuration Reference

Publish with php artisan vendor:publish --tag=okta-oidc-config.

Security Notes

• The callback regenerates the session after successful OIDC authentication, preventing session fixation.
• The callback verifies the OAuth state parameter; a mismatch is rejected rather than exchanged, and the user is sent to the expired page instead of receiving a 500.
• The return_to parameter is validated to be a same-host URL before being stored as the intended redirect.
• Unsafe methods (POST, PUT, DELETE) are never automatically replayed after session expiry.
• Federated logout clears both the local session and the Okta session.