README

English | 中文文档

OpenID Connect Server for Laravel Passport — adds OIDC Discovery, JWKS, UserInfo, Token Introspection, Token Revocation, and RP-Initiated Logout to any Laravel + Passport application.

This release omits auth_time and rejects max_age / Essential auth_time requests. Full OIDC authentication freshness remains deferred; see the upgrade guide.

Requirements

PHP 8.2+
Laravel 11, 12, or 13
Laravel Passport 12 or 13

Quick Start

Prerequisite: Laravel Passport must be installed and configured before using this package.

1. Install the package

composer require admin9/laravel-oidc-server

2. Implement the interface on your User model

use Admin9\OidcServer\Contracts\OidcUserInterface;
use Admin9\OidcServer\Concerns\HasOidcClaims;

class User extends Authenticatable implements OidcUserInterface
{
    use HasOidcClaims;

    // Optional: Override for custom claims
    protected function resolveOidcClaim(string $claim): mixed
    {
        return match ($claim) {
            'nickname' => $this->display_name,
            'picture' => $this->avatar_url,
            default => parent::resolveOidcClaim($claim),
        };
    }
}

3. Generate Passport keys

php artisan passport:keys

This creates the RSA key pair (storage/oauth-private.key and storage/oauth-public.key) needed for signing tokens.

4. Create an OAuth client

Create a client application that will use your OIDC server:

# For authorization code flow (recommended for web apps)
php artisan passport:client

# For client credentials grant (recommended for machine-to-machine, e.g., microservices)
php artisan passport:client --client

# For password grant (only for first-party trusted apps)
php artisan passport:client --password

# Or install default clients (personal access + password grant)
php artisan passport:install

You'll receive a Client ID and Client Secret — save these for configuring your client application.

Grant Type Guide:

Authorization Code Flow: For web apps with user interaction, most secure
Client Credentials Grant: For server-to-server API calls, no user involvement
Password Grant: Only for first-party trusted apps, not recommended for third-party

5. (Optional) Publish and customize the config

php artisan vendor:publish --tag=oidc-server-config

Edit config/oidc-server.php to customize scopes, claims, token TTLs, and more.

That's it! Your OIDC server is ready. Test it by visiting:

https://your-app.test/.well-known/openid-configuration

Endpoints

Endpoint	Method	Description
`/.well-known/openid-configuration`	GET	OIDC Discovery
`/.well-known/jwks.json`	GET	JSON Web Key Set
`/oauth/authorize`	GET	Authorization (Passport)
`/oauth/token`	POST	Token (Passport)
`/oauth/userinfo`	GET/POST	UserInfo
`/oauth/introspect`	POST	Token Introspection (RFC 7662)
`/oauth/revoke`	POST	Token Revocation (RFC 7009)
`/oauth/logout`	GET, POST	RP-Initiated Logout

Configuration

After publishing the config file, you can customize various aspects in config/oidc-server.php:

User Model

By default, ID tokens use the provider model of the session guard selected by passport.guard. Override if needed:

'user_model' => \App\Models\User::class,

user_model does not select a login guard. Authorization and logout use passport.guard; the ID Token model and the Passport API provider for UserInfo must represent the same users. See alternate user models and guards for a complete Member configuration.

Passport Route Control

The package calls Passport::ignoreRoutes() by default to prevent route conflicts. Disable this if you need Passport's default routes alongside OIDC:

'ignore_passport_routes' => false,

Default Claims Map

The HasOidcClaims trait resolves standard claims via a configurable map. Override to match your User model's schema:

'default_claims_map' => [
    'name' => 'name',           // string = model attribute
    'email' => 'email',
    'email_verified' => fn ($user) => $user->email_verified_at !== null,
    'updated_at' => fn ($user) => $user->updated_at?->timestamp,
],

For custom claims (e.g., nickname, picture), use claims_resolver or override resolveOidcClaim() in your User model.

Other Options

Scopes & claims mapping — scopes, claims_resolver
Token TTLs — tokens.access_token_ttl, tokens.refresh_token_ttl, tokens.id_token_ttl
Route middleware — routes.discovery_middleware, routes.token_middleware, routes.userinfo_middleware
Passport auto-configuration — configure_passport (set to false to configure Passport yourself)

See the Configuration Reference for all available options.

Documentation

License

MIT

Security upgrade

Read the v1.2.2 upgrade guide for logout confirmation, exact callbacks, resource-server authorization and historical-grant handling.

admin9 / laravel-oidc-server

Package info

Security

Statistics