PHPackages inmanturbo/homework-starter-kit - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. inmanturbo/homework-starter-kit ActiveProject[Authentication & Authorization](/categories/authentication) inmanturbo/homework-starter-kit =============================== Self-hosted WorkOS-compatible OAuth server using Laravel Passport - starter kit. v0.0.1(7mo ago)10MITBladePHP ^8.2CI passing Since Sep 29Pushed 7mo agoCompare [ Source](https://github.com/inmanturbo/homework-starter-kit)[ Packagist](https://packagist.org/packages/inmanturbo/homework-starter-kit)[ RSS](/packages/inmanturbo-homework-starter-kit/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (16)Versions (2)Used By (0) WorkOS Passport Starter Kit =========================== [](#workos-passport-starter-kit) [![Tests](https://github.com/inmanturbo/homework-starter-kit/actions/workflows/tests.yml/badge.svg)](https://github.com/inmanturbo/homework-starter-kit/actions)[![Install with Herd](https://camo.githubusercontent.com/c62cb221d136c92117fbfd4398c9f0f038d7bc205d84db3ce1b19d46b5045009/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f496e7374616c6c25323077697468253230486572642d6666663f6c6f676f3d6c61726176656c266c6f676f436f6c6f723d663533303033)](https://herd.laravel.com/new?starter-kit=inmanturbo/homework-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 -------- [](#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 ----------- [](#quick-start) ### Option 1: Using Laravel Herd (Easiest) [](#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 [](#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 [](#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 [](#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 [](#3-database-setup) ``` php artisan migrate ``` ### 4. Create OAuth Client [](#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 [](#5-start-the-server) ``` php artisan serve --port=8000 ``` Your WorkOS-compatible OAuth server is now running at `http://localhost:8000`! API Endpoints ------------- [](#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 ------------------------ [](#client-application-setup) ### Laravel Applications with WorkOS SDK [](#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 ------------- [](#configuration) ### Passport 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 [](#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 ----------------- [](#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 ---------- [](#deployment) ### Production Considerations [](#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 [](#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 ------------------- [](#package-information) This starter kit uses the [inmanturbo/homework](https://github.com/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 --------------------- [](#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 ------------ [](#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 ------- [](#support) - **Package Issues**: [inmanturbo/homework GitHub Issues](https://github.com/inmanturbo/homework/issues) - **Starter Kit Issues**: [homework-starter-kit GitHub Issues](https://github.com/inmanturbo/homework-starter-kit/issues) License ------- [](#license) MIT License. See [LICENSE](LICENSE) for details. Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. --- **Self-hosted • Secure • WorkOS Compatible** ### Health Score 29 — LowBetter than 60% of packages Maintenance63 Regular maintenance activity Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 226d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/0261babef618b8fb3bfcea84376ed5e71e7169586eb8de63a6550c2e7ea653a6?d=identicon)[inmanturbo](/maintainers/inmanturbo) --- Top Contributors [![inmanturbo](https://avatars.githubusercontent.com/u/47095624?v=4)](https://github.com/inmanturbo "inmanturbo (7 commits)") --- Tags laravelAuthenticationoauthpassportstarter-kitworkos ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/inmanturbo-homework-starter-kit/health.svg) ``` [![Health](https://phpackages.com/badges/inmanturbo-homework-starter-kit/health.svg)](https://phpackages.com/packages/inmanturbo-homework-starter-kit) ``` ### Alternatives [jeremy379/laravel-openid-connect OpenID Connect support to the PHP League's OAuth2 Server. Compatible with Laravel Passport. 55342.3k2](/packages/jeremy379-laravel-openid-connect)[wearedevtical/novassport A Laravel Nova tool to manage API Authentication (Passport). 663.1k](/packages/wearedevtical-novassport)[danjdewhurst/laravel-passport-facebook-login Facebook Token Request Grant for Laravel Passport 2824.4k](/packages/danjdewhurst-laravel-passport-facebook-login)[mikemclin/passport-custom-request-grant Custom Request Grant for Laravel Passport 343.6k](/packages/mikemclin-passport-custom-request-grant) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)