Integración de Aplicación de Usuarios a Sistemas Existentes

📘 Introducción

El presente manual tiene como objetivo describir el proceso de integración entre la aplicación de gestión de usuarios y los sistemas existentes dentro del ecosistema institucional. Ambas soluciones han sido desarrolladas sobre el framework Laravel, lo que permite establecer una base tecnológica homogénea y facilita la interoperabilidad entre servicios.

Esta integración busca centralizar la administración de usuarios, estandarizar los mecanismos de autenticación y autorización, y garantizar una comunicación eficiente y segura entre aplicaciones. A través de este documento, se detallan los lineamientos técnicos, flujos de operación y consideraciones necesarias para lograr una correcta implementación.

⚙️ Configuración Técnica de Integración

A continuación, se describen los pasos necesarios para integrar la Aplicación de Usuarios con FusionAuth en un proyecto Laravel existente.

Configuración de servicios (config/services.php)

Reemplazar la configuración de `fusionauth` con la siguiente estructura:

'fusionauth' => [
  'client_id' => env('FUSIONAUTH_CLIENT_ID'),
  'client_secret' => env('FUSIONAUTH_CLIENT_SECRET'),
  'redirect' => env('FUSIONAUTH_REDIRECT_URI'),
  'base_url' => env('FUSIONAUTH_BASE_URL'),
  'tenant_id' => env('FUSIONAUTH_TENANT_ID'),
  'redirect_home' => env('FUSIONAUTH_REDIRECT_HOME'),
  'url_logout' => env('FUSIONAUTH_URL_LOGOUT'),
]


Variables de entorno (.env)

Agregar las siguientes variables de entorno:

FUSIONAUTH_CLIENT_ID=tu_client_id
FUSIONAUTH_CLIENT_SECRET=tu_client_secret
FUSIONAUTH_REDIRECT_URI=${APP_URL}/autenticacion/callback
FUSIONAUTH_BASE_URL=https://acceso.tamaulipas.gob.mx
FUSIONAUTH_TENANT_ID=d9220956-99f7-431f-8de1-de37e65488a8
FUSIONAUTH_REDIRECT_HOME="/inicio"
FUSIONAUTH_URL_LOGOUT="${FUSIONAUTH_BASE_URL}/oauth2/logout?client_id=${FUSIONAUTH_CLIENT_ID}"

⚠️ Importante:

Registro del Provider de Socialite

En el archivo:

app/Providers/EventServiceProvider.php

Agregar (solo si no existe):

protected $listen = [
  \SocialiteProviders\Manager\SocialiteWasCalled::class => [
    \SocialiteProviders\FusionAuth\FusionAuthExtendSocialite::class . '@handle',
  ],
];

Instalación de dependencias

Agregar la dependencia en composer.json:

"aiidt/autenticacion-module": "^1.1"

Instalar dependencias:

composer update

O bien:

composer require aiidt/autenticacion-module

Configuración del Modelo User

Agregar campos a $fillable
protected $fillable = [
  'name',
  'email',
  'profile_photo_url',
  'password',
  'fusionauth_id',
  'fusionauth_access_token',
  'fusionauth_refresh_token',
  'data',
  'registration_data',
];
Agregar casting de datos
protected $casts = [
  'data' => 'array',
  'registration_data' => 'array',
];

Modificación de la tabla users

Se debe agregar el campo registration_data para almacenar información adicional del usuario.

Opción A: Mediante migración (Recomendado)

Crear migración:

php artisan make:migration add_registration_data_to_users_table --table=users

Editar migración:

public function up()
{
    Schema::table('users', function (Blueprint $table) {
        $table->json('registration_data')->nullable()->after('fusionauth_refresh_token');
    });
}

public function down()
{
    Schema::table('users', function (Blueprint $table) {
        $table->dropColumn('registration_data');
    });
}

Ejecutar migración:

php artisan migrate

Opción B: Modificación directa (SQL)
ALTER TABLE users 
ADD COLUMN registration_data JSON NULL 
AFTER fusionauth_refresh_token;


Configuración de Menú

Se deberá agregar un acceso a la aplicación de administración de usuarios en los menús del sistema.

Editar los siguientes archivos:

Agregar una nueva entrada apuntando a:

https://acceso.tamaulipas.gob.mx/admin-usuarios/

💡 Se recomienda ubicar esta opción dentro de una sección administrativa o de configuración, dependiendo de la estructura del sistema.

Manejo de Roles y Permisos

A partir de esta integración, se podrá hacer uso de las directivas de roles y permisos proporcionadas por Spatie.

Esto permite:

Ejemplo de uso en Blade:

@role('admin')
    <!-- Contenido solo para administradores -->
@endrole

@can('editar usuarios')
    <!-- Contenido con permiso específico -->
@endcan

Para más información sobre el uso y configuración de roles y permisos, se recomienda revisar la documentación oficial de Spatie:

https://spatie.be/docs/laravel-permission/v7/introduction

⚠️ Consideraciones Finales

Es necesario solicitar previamente el acceso a la aplicación de administración de usuarios, ya que la integración por sí sola no garantiza permisos de uso. Cada sistema o usuario deberá ser registrado y autorizado dentro de la plataforma para poder consumir sus funcionalidades. Este acceso es gestionado de forma centralizada, por lo que se recomienda coordinar la solicitud con el área responsable antes de iniciar pruebas o despliegues en ambientes productivos.