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.

Requirements

PHP 8.2+
Laravel 11 or 12
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

# 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.

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	RP-Initiated Logout

Configuration

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

User Model

By default, the package uses config('auth.providers.users.model') to look up users when generating ID tokens. Override if needed:

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

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

admin9 / laravel-oidc-server

Maintainers

Details