Skip to main content

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

Para habilitar la autenticación mediante FusionAuth en un proyecto Laravel, es necesario instalar el módulo de autenticación desarrollado por la AIIDT, el cual contiene la estructura base requerida para gestionar el flujo de inicio de sesión, retorno de autenticación, cierre de sesión, controlador principal y rutas necesarias para la integración con FusionAuth.

Este módulo permite estandarizar la implementación de autenticación en los proyectos Laravel, evitando duplicar lógica entre aplicaciones y facilitando el mantenimiento centralizado del proceso de autenticación institucional. En pocas palabras: menos código repetido, menos caos y más paz para el backend.

Para su instalación, el proyecto debe contar previamente con la librería de módulos de Laravel:

composer require nwidart/laravel-modules:^12.0

Posteriormente, se deben instalar las siguientes dependencias mediante Composer:

composer require joshbrw/laravel-module-installer:^2.0
composer require aiidt/autenticacion-module:^1.1

La primera dependencia, joshbrw/laravel-module-installer, permite la instalación automática de módulos dentro de la estructura del proyecto Laravel. Esta librería se encarga de ubicar correctamente el módulo dentro del directorio correspondiente, de acuerdo con la configuración del proyecto.

La segunda dependencia, aiidt/autenticacion-module, corresponde al módulo de autenticación como tal. Este módulo contiene la lógica necesaria para integrar Laravel con FusionAuth, incluyendo rutas, controladores y configuraciones base requeridas para completar el flujo de autenticación.

Se recomienda no modificar directamente el módulo de autenticación, ya que al ser administrado como una librería instalada mediante Composer, cualquier cambio local puede perderse al reinstalar dependencias, actualizar el paquete o desplegar nuevamente el proyecto. En caso de requerir ajustes específicos, estos deberán realizarse mediante configuración externa, extensión del comportamiento o personalización desde el proyecto consumidor, sin alterar el código fuente del módulo.

Con esta configuración, el proyecto queda preparado para incorporar el flujo de autenticación centralizada con FusionAuth de forma ordenada, reutilizable y alineada con el estándar institucional de integración.

 

Configuración de servicios

En el archivo config/services.php, se debe reemplazar o agregar 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'),
],

Esta configuración permite que Laravel obtenga desde el archivo .env los datos necesarios para comunicarse con FusionAuth, incluyendo las credenciales de la aplicación, la URL base del servicio, el tenant correspondiente, la ruta de retorno después del inicio de sesión y la URL utilizada para cerrar sesión.

Variables de entorno

En el archivo .env del proyecto Laravel, se deben 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}"

Estas variables permiten parametrizar la integración sin modificar directamente el código fuente del proyecto, facilitando su mantenimiento y despliegue entre distintos ambientes. Básicamente: configuración afuera, código limpio adentro; como debe ser.

Consideraciones importantes

Es importante tomar en cuenta las siguientes consideraciones antes de realizar la integración:

No se deben modificar las siguientes variables:

FUSIONAUTH_REDIRECT_URI=${APP_URL}/autenticacion/callback
FUSIONAUTH_BASE_URL=https://acceso.tamaulipas.gob.mx
FUSIONAUTH_TENANT_ID=d9220956-99f7-431f-8de1-de37e65488a8

La variable FUSIONAUTH_REDIRECT_URI define la ruta de callback a la que FusionAuth redirigirá al usuario después de completar el proceso de autenticación. Esta URI debe coincidir exactamente con la configurada en FusionAuth, ya que cualquier diferencia en dominio, protocolo, ruta o prefijo puede provocar errores durante el inicio de sesión.

Asimismo, FUSIONAUTH_BASE_URL y FUSIONAUTH_TENANT_ID corresponden a la configuración institucional del servicio de autenticación, por lo que deben conservarse sin cambios para garantizar que la aplicación se conecte al tenant correcto.

Registro del Provider de Socialite

Para que Laravel Socialite pueda reconocer y utilizar el proveedor de FusionAuth, es necesario registrar el provider correspondiente dentro del archivo:

 

app/Providers/EventServiceProvider.php

En este archivo, se debe agregar la siguiente configuración solo en caso de que no exista previamente:

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