Download the PHP package dost-tapi/portal-integration without Composer

DOST-TAPI Portal Integration Package

A Laravel package that provides SSO (Single Sign-On) and role management integration for DOST-TAPI applications using Spatie Laravel Permission.

Features

• SSO Authentication: Validate Portal SSO tokens and authenticate users
• Role Management: Expose application roles to Portal with permissions
• User Provisioning: Create and update users from Portal with role assignment
• Automatic User Sync: Keep user data synchronized with Portal
• Middleware Protection: Protect routes with Portal API key and SSO validation
• Artisan Commands: Sync roles to Portal via command line

Requirements

• PHP ^8.1
• Laravel ^11.0
• Spatie Laravel Permission ^6.0

Installation

Install the package via Composer:

Publish Configuration

Publish the configuration file:

This will create a config/portal-integration.php file.

Publish Migrations

Publish the migration file:

Then run the migration:

This adds the following columns to your users table:

• portal_user_id (nullable, indexed)
• department (nullable)
• employee_id (nullable)

Configuration

Add the following environment variables to your .env file:

Configuration Options

Usage

API Endpoints

The package automatically registers the following API endpoints:

1. Get Roles

Endpoint: GET /api/roles

Description: Returns all roles with their permissions for Portal synchronization.

Authentication: Requires Portal API key as Bearer token

Request Example:

Response Example:

2. Create/Update User

Endpoint: POST /api/admin/create-user

Description: Creates or updates a user with role assignment from Portal.

Authentication: Requires Portal API key as Bearer token

Request Body:

Response Example:

Error Response (Role not found):

3. Update User Role

Endpoint: PUT /api/admin/update-user-role/{portal_user_id}

Description: Updates an existing user's role.

Authentication: Requires Portal API key as Bearer token

Request Body:

Response Example:

Error Response (User not found):

SSO Middleware

Protect routes with SSO authentication using the portal.sso middleware:

The middleware will:

1. Extract the SSO token from query parameter (?token=...) or Bearer token
2. Validate the token with the Portal API
3. Create or update the user in your application
4. Authenticate the user
5. Continue the request

SSO Flow Example:

API Key Middleware

The portal.api middleware is automatically applied to all package routes. You can also use it on custom routes:

Artisan Commands

Sync Roles to Portal

Synchronize your application's roles and permissions to the Portal:

Output Example:

This command:

• Fetches all roles with permissions from your application
• Sends them to the Portal API (POST /api/applications/sync-roles)
• Logs the sync operation

You can run this command:

• After creating new roles
• After updating role permissions
• As part of deployment scripts
• Via scheduled task for automatic synchronization

Testing

The package includes comprehensive tests. To run tests:

Test Coverage

The package includes tests for:

• ✅ Role endpoint with API key validation
• ✅ User creation and update endpoints
• ✅ Role assignment and validation
• ✅ SSO token validation and user authentication
• ✅ Middleware authentication and authorization
• ✅ Error handling and edge cases

API Reference

Response Format

All endpoints return JSON responses with consistent format:

Success Response:

Error Response:

HTTP Status Codes

Authentication

All API endpoints require authentication via Bearer token:

The API key is configured in PORTAL_API_KEY environment variable.

Security

• API Key: Each application should have a unique API key
• HTTPS: Always use HTTPS in production
• Token Validation: SSO tokens are validated with the Portal API
• Role Verification: All role assignments verify role existence
• Input Validation: All endpoints validate input data
• Error Logging: Failed authentication attempts are logged

Troubleshooting

Common Issues

Issue: API key authentication fails

Solution:

• Verify PORTAL_API_KEY is set in .env
• Check Bearer token is included in request headers
• Ensure API key matches between applications

Issue: SSO token validation fails

Solution:

• Verify PORTAL_URL points to correct Portal instance
• Check network connectivity between applications
• Ensure Portal API is accessible
• Review logs in storage/logs/laravel.log

Issue: Role not found error

Solution:

• Verify role exists in application using: php artisan permission:show
• Check role name matches exactly (case-sensitive)
• Run php artisan cache:clear to clear permission cache

Issue: Migration fails

Solution:

• Ensure users table exists before running migration
• Check database connection
• Verify you haven't already run the migration

Issue: Users not being created via SSO

Solution:

• Verify PORTAL_AUTO_CREATE_USERS=true in .env
• Check that default role exists (configured in PORTAL_DEFAULT_ROLE)
• Review logs for validation errors

Docker Integration

When using Docker, use internal container URLs for PORTAL_URL:

Package Installation Methods

Via GitHub Repository

Add to composer.json:

Via Local Path (Development)

Add to composer.json:

Then run:

Logging

The package logs important events:

• User creation/update from Portal
• Role assignment changes
• SSO authentication success/failure
• Token validation errors
• Role sync operations

Logs are written to Laravel's default log channel (storage/logs/laravel.log).

Support

For issues, questions, or contributions:

• Email: [email protected]
• Create an issue in the package repository

License

MIT License. See LICENSE file for details.

Credits

Developed by the DOST-TAPI Development Team.

Changelog

Version 1.0.0

• Initial release
• SSO authentication middleware
• Role management API endpoints
• User provisioning from Portal
• Role synchronization command
• Comprehensive test coverage