admin9/laravel-oidc-server

Laravel OIDC Server

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, 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	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

• Architecture
• Configuration Reference
• Endpoint Reference
• Claims Resolution
• Extension Points
• Troubleshooting

License

MIT