README

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:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=workos_passport
DB_USERNAME=your_username
DB_PASSWORD=your_password

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:

WORKOS_CLIENT_ID=your_oauth_client_id
WORKOS_API_KEY=your_oauth_client_secret
WORKOS_REDIRECT_URL=http://your-app.test/authenticate
WORKOS_BASE_URL=http://localhost:8000/

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

Environment Variables: Set proper production values in .env
Database: Use a production database (PostgreSQL, MySQL)
HTTPS: Always use HTTPS in production
Client Secrets: Keep OAuth client secrets secure
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:

Deploy this starter kit to your server
Create OAuth clients matching your WorkOS application IDs
Update client applications to point to your OAuth server
Test the authentication flow thoroughly
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

inmanturbo / homework-starter-kit

Maintainers

Details