{"id":37234379,"url":"https://github.com/digram/bukua-auth","last_synced_at":"2026-01-15T03:58:49.672Z","repository":{"id":251774742,"uuid":"838405929","full_name":"digram/bukua-auth","owner":"digram","description":"Login with Bukua OAuth for Laravel","archived":false,"fork":false,"pushed_at":"2025-10-07T07:26:24.000Z","size":101,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-14T14:15:11.818Z","etag":null,"topics":["authentication","bukua","edtech","kenya","laravel"],"latest_commit_sha":null,"homepage":"https://www.bukuaplatform.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-05T15:18:02.000Z","updated_at":"2025-10-07T07:26:28.000Z","dependencies_parsed_at":"2025-09-17T07:15:59.036Z","dependency_job_id":"1dabe97e-e235-4f0f-bb8f-5bbec1314d32","html_url":"https://github.com/digram/bukua-auth","commit_stats":null,"previous_names":["digram/bukua-auth"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/digram/bukua-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digram%2Fbukua-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digram%2Fbukua-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digram%2Fbukua-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digram%2Fbukua-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digram","download_url":"https://codeload.github.com/digram/bukua-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digram%2Fbukua-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","bukua","edtech","kenya","laravel"],"created_at":"2026-01-15T03:58:49.087Z","updated_at":"2026-01-15T03:58:49.655Z","avatar_url":"https://github.com/digram.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Login with Bukua Laravel Integration\n\nThis package provides seamless **OAuth 2.0 authentication** with Bukua for Laravel applications, handling the complete authentication flow and user management.\n\n## Table of Contents\n\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [Environment Variables](#environment-variables)\n  - [Database Setup](#database-setup)\n  - [User Model Configuration](#user-model-configuration)\n  - [CORS Configuration](#cors-configuration)\n- [Usage](#usage)\n  - [Login Button Implementation](#login-button-implementation)\n  - [Authentication Routes](#authentication-routes)\n- [Events](#events)\n- [API Methods](#api-methods)\n- [Troubleshooting](#troubleshooting)\n- [Support](#support)\n\n## Prerequisites\n\nBefore using this package, ensure you have:\n\n1. **Bukua Developer Account**\n   - Register as an app developer at [Bukua Platform - Development Environment](https://bukua-core.apptempest.com/login) or [Bukua Platform - Production Environment](https://app.bukuaplatform.com/login)\n   - Create a **User Access App** in the selected environment above\n\n2. **Application Credentials**\n   - Obtain your `client_id`, `client_secret` and `app_url` from the Bukua Developer Dashboard\n\n3. **Laravel Application**\n   - Laravel 8.x or higher\n   - Composer for dependency management\n\n## Installation\n\n1. **Install the package via Composer:**\n   ```bash\n   composer require digram/bukua-auth\n   ```\n\n2. **Clear configuration cache:**\n   ```bash\n   # For development\n   php artisan config:clear \u0026\u0026 php artisan route:clear\n\n   # For production\n   php artisan config:cache \u0026\u0026 php artisan route:cache\n   ```\n\n## Configuration\n\n### Environment Variables\n\nAdd the following variables to your `.env` file:\n\n```bash\n# Bukua OAuth Configuration\nBUKUA_USER_ACCESS_CLIENT_ID=your-client-id-here\nBUKUA_USER_ACCESS_CLIENT_SECRET=your-client-secret-here\nBUKUA_USER_ACCESS_APP_URL=\"https://your-app-url.com\"\nBUKUA_BASE_URL=\"https://bukua-core.apptempest.com\"  # Development\n# BUKUA_BASE_URL=\"https://app.bukuaplatform.com\"    # Production\n\n# Application Settings\nBUKUA_USER_MODEL=\"App\\\\Models\\\\User\"\nBUKUA_REDIRECT_AFTER_LOGIN=\"/dashboard\" # Your authenticated user dashboard URL\n```\n\n**Configuration Notes:**\n- **Environment**: Use the development base URL for testing and production URL for live applications\n- **User Access App URL**: Must exactly match the App URL from your Bukua Developer Dashboard\n- **User Model**: Ensure this matches your application's User model namespace\n\n### Database Setup\n\n1. **Update your User migration:**\n   ```php\n   Schema::table('users', function ($table) {\n       $table-\u003echar('bukua_user_id', 36)-\u003enullable()-\u003eindex();\n       $table-\u003etext('bukua_access_token')-\u003enullable();\n       $table-\u003etext('bukua_refresh_token')-\u003enullable();\n       $table-\u003estring('name')-\u003enullable();\n       // Consider adding index for better performance\n       $table-\u003eindex(['bukua_user_id']);\n   });\n   ```\n\n2. **Run migrations:**\n   ```bash\n   php artisan migrate\n   ```\n\n### User Model Configuration\n\nUpdate your User model to include the Bukua fields:\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\nuse Illuminate\\Notifications\\Notifiable;\n\nclass User extends Authenticatable\n{\n    use Notifiable;\n\n    /**\n     * The attributes that are mass assignable.\n     *\n     * @var array\u003cint, string\u003e\n     */\n    protected $fillable = [\n        'name',\n        'email',\n        'password',\n        'bukua_user_id',\n        'bukua_access_token',\n        'bukua_refresh_token',\n    ];\n\n    /**\n     * The attributes that should be hidden for serialization.\n     *\n     * @var array\u003cint, string\u003e\n     */\n    protected $hidden = [\n        'password',\n        'remember_token',\n        'bukua_access_token',\n        'bukua_refresh_token',\n    ];\n}\n```\n\n### CORS Configuration\n\nTo handle cross-origin requests properly, configure your Laravel CORS settings in `config/cors.php`:\n\nIf your Laravel application doesn't have the CORS configuration file, generate it using:\n\n```bash\nphp artisan config:publish cors\n```\n\nThis will create the `config/cors.php` file if it doesn't already exist.\n\nUpdate your `config/cors.php` file with the following settings:\n\n```php\nreturn [\n    'paths' =\u003e [\n        'api/*',\n        'sanctum/csrf-cookie',\n        'bukua-auth/callback', // Bukua OAuth callback\n    ],\n\n    'allowed_methods' =\u003e ['*'],\n\n    'allowed_origins' =\u003e [\n        'https://bukua-core.apptempest.com', // Bukua development environment\n        'https://app.bukuaplatform.com',     // Bukua production environment\n    ],\n\n    'allowed_origins_patterns' =\u003e [],\n\n    'allowed_headers' =\u003e ['*'],\n\n    'exposed_headers' =\u003e [\n        'X-Inertia-Location', // Bukua OAuth redirects\n        'X-Inertia',          // Bukua OAuth responses\n    ],\n\n    'max_age' =\u003e 0,\n\n    'supports_credentials' =\u003e false,\n];\n```\n\n**CORS Configuration Notes:**\n- Ensure the `paths` array includes `'bukua-auth/callback'` to handle OAuth callbacks\n- Add both Bukua domains to `allowed_origins` for proper cross-origin requests\n- Include `'X-Inertia-Location'` and `'X-Inertia'` in `exposed_headers` for OAuth redirection\n\n## Usage\n\n### Login Button Implementation\n\n**Blade Templates:**\n```html\n\u003c!-- resources/views/auth/login.blade.php --\u003e\n@if (Route::has('bukua-auth.authorize'))\n    \u003cform action=\"{{ route('bukua-auth.authorize') }}\" method=\"POST\"\u003e\n        @csrf\n        \u003cbutton type=\"submit\" class=\"btn btn-primary\"\u003e\n            Login with Bukua\n        \u003c/button\u003e\n    \u003c/form\u003e\n@endif\n```\n\n**Inertia.js with React/Vue:**\n```jsx\n// For React components\nimport { Link } from '@inertiajs/react';\n\nfunction LoginButton() {\n    return (\n        \u003cLink \n            method=\"post\" \n            href={route('bukua-auth.authorize')}\n            as=\"button\"\n            className=\"btn btn-primary\"\n        \u003e\n            Login with Bukua\n        \u003c/Link\u003e\n    );\n}\n```\n\n### Authentication Routes\n\nThe package automatically registers the following routes:\n\n| Route Name | URL | Method | Purpose |\n|------------|-----|--------|---------|\n| `bukua-auth.authorize` | `/bukua/authorize` | POST | Initiates OAuth flow |\n| `bukua-auth.callback` | `/bukua/callback` | GET | Handles OAuth callback |\n\n## Events\n\nThe package dispatches events that you can listen for to extend functionality:\n\n### Available Events\n\n- `BukuaUserLoggedInEvent`: Dispatched when a user successfully logs in\n\n### Event Listener Setup\n\nCreate an example listener in Laravel using:\n\n**Name**: `HandleBukuaUserLoggedIn`\n**Event**: `\\BukuaAuth\\Events\\BukuaUserLoggedInEvent`:\n\n```bash\nphp artisan make:listener\n```\n\n**Example listener implementation:**\n   ```php\n   \u003c?php\n\n   namespace App\\Listeners;\n\n   use BukuaAuth\\Events\\BukuaUserLoggedInEvent;\n   use BukuaAuth\\Facades\\BukuaAuth;\n   use Illuminate\\Support\\Facades\\Log;\n\n   class HandleBukuaUserLoggedIn\n   {\n       /**\n        * Handle the event.\n        */\n       public function handle(BukuaUserLoggedInEvent $event)\n       {\n           $user = $event-\u003euser;\n           \n           // Log the event\n           Log::info('Bukua user logged in', [\n               'bukua_user_id' =\u003e $user-\u003ebukua_user_id,\n               'timestamp' =\u003e now(),\n           ]);\n\n           try {\n               // Fetch basic user profile\n               $userProfile = BukuaAuth::me();\n\n               $firstName   = $userProfile['response']['user']['first_name'];\n               $schoolName  = $userProfile['response']['school']['name'];\n               $schoolUid   = $userProfile['response']['school']['uid'];\n               $roleName    = $userProfile['response']['role']['name'];\n               $roleUid     = $userProfile['response']['role']['uid'];\n\n               // Run your business logic ...                           \n           } catch (\\Exception $e) {\n               Log::error('Failed to fetch user data from Bukua', [\n                   'error' =\u003e $e-\u003egetMessage(),\n                   'bukua_user_id' =\u003e $user-\u003ebukua_user_id,\n               ]);\n           }\n       }\n   }\n   ```\n\n## API Methods\n\nThe package provides several methods to interact with Bukua's API:\n\n### Basic User Profile\n\n```php\nuse BukuaAuth\\Facades\\BukuaAuth;\n\ntry {\n    $userProfile = BukuaAuth::me();\n\n    print_r($userProfile);\n    \n    // Returns: {\n    //   user: {\"uid\": \"user_uid\", \"first_name\": \"John\", \"last_name\": \"Doe\", \"email\": \"john.doe@example.com\"}\n    //   school: {\"uid\": \"school_uid\", \"name\": \"Jitahidi School\"}\n    //   role: {\"uid\": \"role_uid\", \"name\": \"Teacher\"}\n    // }\n    \n} catch (\\Exception $e) {\n    echo \"Error: \" . $e-\u003egetMessage();\n}\n```\n\n### User Subjects\n\n```php\ntry {\n    $subjects = BukuaAuth::subjects();\n\n    print_r($subjects);\n    \n    // Returns array of subject objects: [\n    //   {\n    //     \"uid\": \"subject_uid\",\n    //     \"name\": \"Media Technology\",\n    //   }\n    //   {\n    //     \"uid\": \"subject_uid\",\n    //     \"name\": \"Fasihi ya Kiswahili\",\n    //   }\n    //   {\n    //     \"uid\": \"subject_uid\",\n    //     \"name\": \"Home Science\",\n    //   }\n    // ]\n    \n} catch (\\Exception $e) {\n    echo \"Error: \" . $e-\u003egetMessage();\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Invalid redirect_uri\" error**\n   - Ensure `BUKUA_USER_ACCESS_APP_URL` matches exactly with your Bukua app credentials\n   - App URL must use **HTTPS** and be accessible\n\n2. **\"Client authentication failed\" error**\n   - Verify `BUKUA_USER_ACCESS_CLIENT_ID` and `BUKUA_USER_ACCESS_CLIENT_SECRET` are correct\n   - Check for extra spaces in environment variables\n\n3. **User model not found**\n   - Verify `BUKUA_USER_MODEL` points to the correct namespace\n   - Ensure the User model exists and is accessible\n\n4. **User creation errors**\n   - Check if users table already has the required columns\n   - Ensure all existing fields in the users table are nullable as specified\n\n5. **CORS issues**\n   - Verify `bukua-auth/callback` is added to CORS paths\n   - Ensure Bukua domains are in allowed_origins\n   - Check that X-Inertia headers are exposed\n\n## Support\n\n- **Support Email**: hello@bukuaplatform.com\n- **Issue Tracking**: [GitHub Issues](https://github.com/digram/bukua-auth/issues)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigram%2Fbukua-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigram%2Fbukua-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigram%2Fbukua-auth/lists"}