https://github.com/digram/bukua-auth

authentication bukua edtech kenya laravel
Last synced: 5 months ago
JSON representation
Host: GitHub
URL: https://github.com/digram/bukua-auth
Owner: digram
License: apache-2.0
Created: 2024-08-05T15:18:02.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2025-10-07T07:26:24.000Z (9 months ago)
Last Synced: 2026-01-14T14:15:11.818Z (5 months ago)
Topics: authentication, bukua, edtech, kenya, laravel
Language: PHP
Homepage: https://www.bukuaplatform.com
Size: 98.6 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          # Login with Bukua Laravel Integration

This package provides seamless **OAuth 2.0 authentication** with Bukua for Laravel applications, handling the complete authentication flow and user management.

## Table of Contents

- [Prerequisites](#prerequisites)

- [Installation](#installation)

- [Configuration](#configuration)

  - [Environment Variables](#environment-variables)

  - [Database Setup](#database-setup)

  - [User Model Configuration](#user-model-configuration)

  - [CORS Configuration](#cors-configuration)

- [Usage](#usage)

  - [Login Button Implementation](#login-button-implementation)

  - [Authentication Routes](#authentication-routes)

- [Events](#events)

- [API Methods](#api-methods)

- [Troubleshooting](#troubleshooting)

- [Support](#support)

## Prerequisites

Before using this package, ensure you have:

1. **Bukua Developer Account**

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

   - Create a **User Access App** in the selected environment above

2. **Application Credentials**

   - Obtain your `client_id`, `client_secret` and `app_url` from the Bukua Developer Dashboard

3. **Laravel Application**

   - Laravel 8.x or higher

   - Composer for dependency management

## Installation

1. **Install the package via Composer:**

   ```bash

   composer require digram/bukua-auth

   ```

2. **Clear configuration cache:**

   ```bash

   # For development

   php artisan config:clear && php artisan route:clear

   # For production

   php artisan config:cache && php artisan route:cache

   ```

## Configuration

### Environment Variables

Add the following variables to your `.env` file:

```bash

# Bukua OAuth Configuration

BUKUA_USER_ACCESS_CLIENT_ID=your-client-id-here

BUKUA_USER_ACCESS_CLIENT_SECRET=your-client-secret-here

BUKUA_USER_ACCESS_APP_URL="https://your-app-url.com"

BUKUA_BASE_URL="https://bukua-core.apptempest.com"  # Development

# BUKUA_BASE_URL="https://app.bukuaplatform.com"    # Production

# Application Settings

BUKUA_USER_MODEL="App\\Models\\User"

BUKUA_REDIRECT_AFTER_LOGIN="/dashboard" # Your authenticated user dashboard URL

```

**Configuration Notes:**

- **Environment**: Use the development base URL for testing and production URL for live applications

- **User Access App URL**: Must exactly match the App URL from your Bukua Developer Dashboard

- **User Model**: Ensure this matches your application's User model namespace

### Database Setup

1. **Update your User migration:**

   ```php

   Schema::table('users', function ($table) {

       $table->char('bukua_user_id', 36)->nullable()->index();

       $table->text('bukua_access_token')->nullable();

       $table->text('bukua_refresh_token')->nullable();

       $table->string('name')->nullable();

       // Consider adding index for better performance

       $table->index(['bukua_user_id']);

   });

   ```

2. **Run migrations:**

   ```bash

   php artisan migrate

   ```

### User Model Configuration

Update your User model to include the Bukua fields:

```php

     */

    protected $fillable = [

        'name',

        'email',

        'password',

        'bukua_user_id',

        'bukua_access_token',

        'bukua_refresh_token',

    ];

    /**

     * The attributes that should be hidden for serialization.

     *

     * @var array

     */

    protected $hidden = [

        'password',

        'remember_token',

        'bukua_access_token',

        'bukua_refresh_token',

    ];

}

```

### CORS Configuration

To handle cross-origin requests properly, configure your Laravel CORS settings in `config/cors.php`:

If your Laravel application doesn't have the CORS configuration file, generate it using:

```bash

php artisan config:publish cors

```

This will create the `config/cors.php` file if it doesn't already exist.

Update your `config/cors.php` file with the following settings:

```php

return [

    'paths' => [

        'api/*',

        'sanctum/csrf-cookie',

        'bukua-auth/callback', // Bukua OAuth callback

    ],

    'allowed_methods' => ['*'],

    'allowed_origins' => [

        'https://bukua-core.apptempest.com', // Bukua development environment

        'https://app.bukuaplatform.com',     // Bukua production environment

    ],

    'allowed_origins_patterns' => [],

    'allowed_headers' => ['*'],

    'exposed_headers' => [

        'X-Inertia-Location', // Bukua OAuth redirects

        'X-Inertia',          // Bukua OAuth responses

    ],

    'max_age' => 0,

    'supports_credentials' => false,

];

```

**CORS Configuration Notes:**

- Ensure the `paths` array includes `'bukua-auth/callback'` to handle OAuth callbacks

- Add both Bukua domains to `allowed_origins` for proper cross-origin requests

- Include `'X-Inertia-Location'` and `'X-Inertia'` in `exposed_headers` for OAuth redirection

## Usage

### Login Button Implementation

**Blade Templates:**

```html

@if (Route::has('bukua-auth.authorize'))

    

        @csrf

        

            Login with Bukua

        

    

@endif

```

**Inertia.js with React/Vue:**

```jsx

// For React components

import { Link } from '@inertiajs/react';

function LoginButton() {

    return (

        

            Login with Bukua

        

    );

}

```

### Authentication Routes

The package automatically registers the following routes:

| Route Name | URL | Method | Purpose |

|------------|-----|--------|---------|

| `bukua-auth.authorize` | `/bukua/authorize` | POST | Initiates OAuth flow |

| `bukua-auth.callback` | `/bukua/callback` | GET | Handles OAuth callback |

## Events

The package dispatches events that you can listen for to extend functionality:

### Available Events

- `BukuaUserLoggedInEvent`: Dispatched when a user successfully logs in

### Event Listener Setup

Create an example listener in Laravel using:

**Name**: `HandleBukuaUserLoggedIn`

**Event**: `\BukuaAuth\Events\BukuaUserLoggedInEvent`:

```bash

php artisan make:listener

```

**Example listener implementation:**

   ```php

   user;

           

           // Log the event

           Log::info('Bukua user logged in', [

               'bukua_user_id' => $user->bukua_user_id,

               'timestamp' => now(),

           ]);

           try {

               // Fetch basic user profile

               $userProfile = BukuaAuth::me();

               $firstName   = $userProfile['response']['user']['first_name'];

               $schoolName  = $userProfile['response']['school']['name'];

               $schoolUid   = $userProfile['response']['school']['uid'];

               $roleName    = $userProfile['response']['role']['name'];

               $roleUid     = $userProfile['response']['role']['uid'];

               // Run your business logic ...                           

           } catch (\Exception $e) {

               Log::error('Failed to fetch user data from Bukua', [

                   'error' => $e->getMessage(),

                   'bukua_user_id' => $user->bukua_user_id,

               ]);

           }

       }

   }

   ```

## API Methods

The package provides several methods to interact with Bukua's API:

### Basic User Profile

```php

use BukuaAuth\Facades\BukuaAuth;

try {

    $userProfile = BukuaAuth::me();

    print_r($userProfile);

    

    // Returns: {

    //   user: {"uid": "user_uid", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com"}

    //   school: {"uid": "school_uid", "name": "Jitahidi School"}

    //   role: {"uid": "role_uid", "name": "Teacher"}

    // }

    

} catch (\Exception $e) {

    echo "Error: " . $e->getMessage();

}

```

### User Subjects

```php

try {

    $subjects = BukuaAuth::subjects();

    print_r($subjects);

    

    // Returns array of subject objects: [

    //   {

    //     "uid": "subject_uid",

    //     "name": "Media Technology",

    //   }

    //   {

    //     "uid": "subject_uid",

    //     "name": "Fasihi ya Kiswahili",

    //   }

    //   {

    //     "uid": "subject_uid",

    //     "name": "Home Science",

    //   }

    // ]

    

} catch (\Exception $e) {

    echo "Error: " . $e->getMessage();

}

```

## Troubleshooting

### Common Issues

1. **"Invalid redirect_uri" error**

   - Ensure `BUKUA_USER_ACCESS_APP_URL` matches exactly with your Bukua app credentials

   - App URL must use **HTTPS** and be accessible

2. **"Client authentication failed" error**

   - Verify `BUKUA_USER_ACCESS_CLIENT_ID` and `BUKUA_USER_ACCESS_CLIENT_SECRET` are correct

   - Check for extra spaces in environment variables

3. **User model not found**

   - Verify `BUKUA_USER_MODEL` points to the correct namespace

   - Ensure the User model exists and is accessible

4. **User creation errors**

   - Check if users table already has the required columns

   - Ensure all existing fields in the users table are nullable as specified

5. **CORS issues**

   - Verify `bukua-auth/callback` is added to CORS paths

   - Ensure Bukua domains are in allowed_origins

   - Check that X-Inertia headers are exposed

## Support

- **Support Email**: hello@bukuaplatform.com

- **Issue Tracking**: [GitHub Issues](https://github.com/digram/bukua-auth/issues)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/digram/bukua-auth

Awesome Lists containing this project

README
