WorkOS Passport Starter Kit

A ready-to-use Laravel application that provides a self-hosted, WorkOS-compatible OAuth server using Laravel Passport. This starter kit gives you a complete authentication server that can replace WorkOS while maintaining full API compatibility.

Features

• Drop-in WorkOS Replacement: Complete compatibility with WorkOS UserManagement API
• Laravel Passport Integration: Robust OAuth2 server implementation
• ULID User IDs: Uses Laravel's built-in ULID support for portable, sortable user identifiers
• String Client IDs: Full compatibility with WorkOS client applications
• Auto-Approval for First-Party Clients: Seamless user experience for your own apps
• JWT Token Support: WorkOS-compatible token format with JWKS endpoint
• Modern Laravel Architecture: Request-based routing with clean separation of concerns
• Ready to Deploy: Pre-configured Laravel application

Quick Start

Option 1: Using Laravel Herd (Easiest)

# Create a new project using Herd
herd new my-oauth-server --using="inmanturbo/homework-starter-kit"

# Navigate to your project
cd my-oauth-server

# Your OAuth server is now available at https://my-oauth-server.test

Option 2: Using Laravel Installer

# Install Laravel installer if you haven't already
composer global require laravel/installer

# Create a new project using this starter kit
laravel new my-oauth-server --using="inmanturbo/homework-starter-kit"

# Navigate to your project
cd my-oauth-server

Option 3: Manual Installation

Clone this repository and install dependencies:

git clone https://github.com/inmanturbo/homework-starter-kit.git my-oauth-server
cd my-oauth-server
composer install
npm install && npm run build

2. Environment Setup

cp .env.example .env
php artisan key:generate

Configure your database in .env:

3. Database Setup

php artisan migrate

4. Create OAuth Client

Create a first-party client (auto-approves authorization):

php artisan passport:client --public

Save the Client ID - you'll need this for your client applications.

5. Start the Server

php artisan serve --port=8000

Your WorkOS-compatible OAuth server is now running at http://localhost:8000!

API Endpoints

The starter kit provides these WorkOS-compatible endpoints:

• GET /user_management/authorize - OAuth authorization endpoint
• POST /user_management/authenticate - Token exchange endpoint
• POST /user_management/authenticate_with_refresh_token - Refresh token endpoint
• GET /user_management/users/{userId} - Get user information
• GET /sso/jwks/{clientId} - JWKS endpoint for token verification

Client Application Setup

Laravel Applications with WorkOS SDK

Configure your client application to use your OAuth server:

Option 1: Configuration-Based (Recommended)

Add to your config/services.php:

'workos' => [
    'client_id' => env('WORKOS_CLIENT_ID'),
    'secret' => env('WORKOS_API_KEY'),
    'redirect_url' => env('WORKOS_REDIRECT_URL'),
    'base_url' => env('WORKOS_BASE_URL', 'https://api.workos.com/'),
],

In your .env:

In your AppServiceProvider:

use WorkOS\WorkOS;

public function boot()
{
    $baseUrl = config('services.workos.base_url');
    if ($baseUrl && $baseUrl !== 'https://api.workos.com/') {
        WorkOS::setApiBaseUrl($baseUrl);
    }
}

Option 2: Environment-Based

// In AppServiceProvider
public function boot()
{
    if (app()->environment('local')) {
        WorkOS::setApiBaseUrl('http://localhost:8000/');
    }
}

Configuration

Passport Configuration

The starter kit comes pre-configured with sensible defaults in app/Providers/PassportServiceProvider.php:

// Token lifetimes
Passport::tokensExpireIn(CarbonInterval::days(15));
Passport::refreshTokensExpireIn(CarbonInterval::days(30));
Passport::personalAccessTokensExpireIn(CarbonInterval::months(6));

// Default scopes
Passport::tokensCan([
    'read' => 'Read user information',
    'write' => 'Modify user information',
]);

Passport::setDefaultScope(['read']);

User Model & ULID Support

The starter kit uses Laravel's built-in ULID support for user IDs, providing:

• Globally Unique: ULIDs are guaranteed to be unique across distributed systems
• Sortable: Lexicographically sortable by creation time
• URL-Safe: No special characters, perfect for APIs
• Portable: Work across different databases and systems

The User model includes the HasUlids trait:

use Illuminate\Database\Eloquent\Concerns\HasUlids;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, HasUlids, Notifiable, TwoFactorAuthenticatable;
    // ...
}

User IDs will be ULIDs like: 01ARZ3NDEKTSV4RRFFQ69G5FAV

If you use a custom user model, ensure it includes the HasUlids trait and update config/auth.php:

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\CustomUser::class, // Your custom model
    ],
],

Testing the Setup

Test your OAuth flow:

# Test authorization endpoint
curl -I "http://localhost:8000/oauth/authorize?client_id=your_client_id&redirect_uri=http://your-app.test/authenticate&state=test_state"

# Test token exchange (after getting authorization code)
curl -X POST "http://localhost:8000/user_management/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "your_client_id",
    "code": "authorization_code_here"
  }'

Deployment

Production Considerations

1. Environment Variables: Set proper production values in .env
2. Database: Use a production database (PostgreSQL, MySQL)
3. HTTPS: Always use HTTPS in production
4. Client Secrets: Keep OAuth client secrets secure
5. Token Security: Consider shorter token lifetimes for production

Deployment Commands

# Install dependencies
composer install --optimize-autoloader --no-dev

# Clear and cache config
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Run migrations
php artisan migrate --force

Package Information

This starter kit uses the inmanturbo/homework package to provide WorkOS compatibility. The package:

• Modern Architecture: Request-based routing with type-hinted FormRequest classes
• WorkOS API Compatibility: Extends Laravel Passport with WorkOS-compatible endpoints
• Auto-Approval Middleware: Seamless first-party client authorization
• WorkOS Response Format: Returns snake_case formatted API responses
• JWT & JWKS Support: Token verification with public key endpoints
• ULID Compatible: Works seamlessly with ULID user identifiers

Migration from WorkOS

To migrate from WorkOS to this self-hosted solution:

1. Deploy this starter kit to your server
2. Create OAuth clients matching your WorkOS application IDs
3. Update client applications to point to your OAuth server
4. Test the authentication flow thoroughly
5. Switch DNS/URLs when ready

Requirements

• PHP ^8.2
• Laravel ^12.0
• Laravel Passport ^13.0
• inmanturbo/homework ^0.0.2
• MySQL/PostgreSQL/SQLite
• Composer 2.x
• Node.js & NPM (for asset compilation)

Support

• Package Issues: inmanturbo/homework GitHub Issues
• Starter Kit Issues: homework-starter-kit GitHub Issues

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Self-hosted • Secure • WorkOS Compatible