🎯 Troubleshooting

Esta sección tiene como objetivo ayudar a identificar y resolver los errores más comunes que pueden presentarse durante la integración de **FusionAuth** con proyectos Laravel mediante el módulo de autenticación y Socialite Provider.

Antes de revisar errores específicos, se recomienda validar que se hayan completado correctamente los siguientes puntos:

1. Instalación de dependencias mediante Composer.
2. Configuración de config/services.php.
3. Configuración de variables de entorno en .env.
4. Registro del provider de Socialite.
5. Configuración del modelo User.
6. Modificación de la tabla users.
7. Coincidencia exacta de la URI de callback entre Laravel y FusionAuth.

No redirige al login de FusionAuth

Problema

Al ingresar a la ruta: http://${base_url}/autenticacion/login

la aplicación no redirige al formulario de inicio de sesión de FusionAuth, muestra una pantalla en blanco, error 404 o permanece en la misma página.

Posibles causas

• El módulo de autenticación no está instalado correctamente.
• Las rutas del módulo no fueron registradas.
• El proyecto no reconoce el módulo de autenticación.
• La URL base del proyecto no corresponde con la URL utilizada en el navegador.
• El caché de rutas o configuración de Laravel está desactualizado.

Solución recomendada

Ejecutar los siguientes comandos dentro del proyecto Laravel:

php artisan optimize:clear
php artisan route:clear
php artisan config:clear
php artisan cache:clear
composer dump-autoload

Después, validar que la ruta exista ejecutando:

php artisan route:list | grep autenticacion

Se debe verificar que existan rutas relacionadas con:

/autenticacion/login
/autenticacion/callback

Si las rutas no aparecen, revisar que el módulo de autenticación se encuentre instalado correctamente dentro de la estructura de módulos del proyecto.

Error por URI de callback incorrecta

Problema

FusionAuth muestra un error relacionado con la URL de redirección o callback.

Puede presentarse como:

Invalid redirect_uri

o

The redirect_uri is not valid

Posibles causas

• La variable FUSIONAUTH_REDIRECT_URI no coincide exactamente con la configurada en FusionAuth.
• Se está usando http en lugar de https, o viceversa.
• La aplicación tiene un prefijo en la URL y no fue considerado.
• La variable APP_URL está mal configurada.
• Hay una diagonal / extra o faltante en la URL.

Solución recomendada

Validar en el archivo .env:

APP_URL=https://dominio-del-proyecto.gob.mx
FUSIONAUTH_REDIRECT_URI=${APP_URL}/autenticacion/callback

La URI generada debe coincidir exactamente con la configurada en FusionAuth.

Ejemplo:

https://dominio-del-proyecto.gob.mx/autenticacion/callback

También se recomienda limpiar caché de configuración:

php artisan config:clear
php artisan optimize:clear

Importante: la URI de callback debe coincidir exactamente. Para FusionAuth, http://sistema.gob.mx/callback y https://sistema.gob.mx/callback son rutas diferentes.

Error 500 después del callback

Problema

El usuario inicia sesión en FusionAuth, pero al regresar a Laravel se muestra un error 500.

Posibles causas

• Faltan columnas en la tabla users.
• El modelo User no tiene los campos agregados en $fillable.
• Los campos data o registration_data no tienen casting como array.
• La base de datos no acepta valores nulos en campos requeridos.
• El campo password no permite valores nulos.
• Error al guardar los tokens de FusionAuth.
• Solución recomendada

Validar que la tabla users tenga los siguientes campos:

fusionauth_id
fusionauth_access_token
fusionauth_refresh_token
profile_photo_url
data
registration_data

Validar que el campo password permita valores nulos:

DESCRIBE users;

En el modelo User, revisar que existan los campos en $fillable:

protected $fillable = [
    'name',
    'email',
    'profile_photo_url',
    'password',
    'fusionauth_id',
    'fusionauth_access_token',
    'fusionauth_refresh_token',
    'data',
    'registration_data',
];

También revisar que los campos JSON tengan casting:

protected $casts = [
    'data' => 'array',
    'registration_data' => 'array',
];

Finalmente, revisar el log de Laravel:

tail -f storage/logs/laravel.log

Error: Class not found

Problema

Laravel muestra un error similar a:

Class "SocialiteProviders\FusionAuth\FusionAuthExtendSocialite" not found

o

Class not found

Posibles causas

• No se instaló correctamente el paquete del provider de FusionAuth.
• Composer no actualizó el autoload.
• El provider fue registrado con un namespace incorrecto.
• El archivo EventServiceProvider.php tiene una referencia mal escrita.

Solución recomendada

Validar que las dependencias estén instaladas:

composer show | grep fusionauth
composer show | grep socialite

Regenerar el autoload:

composer dump-autoload
php artisan optimize:clear

Revisar que en app/Providers/EventServiceProvider.php exista la siguiente configuración:

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

Error de configuración de services.php

Problema

La aplicación no puede iniciar el flujo de autenticación o genera errores relacionados con configuraciones vacías.

Posibles causas

• No existe la entrada fusionauth en config/services.php.
• Alguna variable del .env está vacía.
• Se modificó el nombre de una variable.
• El caché de configuración de Laravel sigue usando valores anteriores.

Solución recomendada

Validar que config/services.php tenga 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'),
],

Después, revisar las variables en .env:

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}"

Limpiar configuración:

php artisan config:clear
php artisan optimize:clear

Error: Client ID o Client Secret incorrecto

Problema

FusionAuth no permite completar el inicio de sesión o marca error relacionado con la aplicación cliente.

Posibles causas

• FUSIONAUTH_CLIENT_ID incorrecto.
• FUSIONAUTH_CLIENT_SECRET incorrecto.
• Las credenciales corresponden a otra aplicación.
• El usuario intenta autenticarse contra un tenant o aplicación distinta.
  

Solución recomendada

Validar que los valores del .env correspondan exactamente a los configurados en FusionAuth:

FUSIONAUTH_CLIENT_ID=tu_client_id
FUSIONAUTH_CLIENT_SECRET=tu_client_secret

También confirmar que el usuario tenga acceso a la aplicación configurada en FusionAuth.

Después de modificar estas variables, ejecutar:

php artisan config:clear
php artisan optimize:clear

Error al guardar el usuario autenticado

Problema

El login se completa en FusionAuth, pero Laravel no puede crear o actualizar el usuario en la base de datos.

Posibles causas

• Falta el campo fusionauth_id.
• fusionauth_id está marcado como único y ya existe un usuario duplicado.
• El correo ya existe con otro fusionauth_id.
• Faltan campos en $fillable.
• Las columnas JSON no existen o no son compatibles con la base de datos.
• Los tokens son demasiado largos para el tipo de columna definido.
  

Solución recomendada

Validar la estructura de la tabla:

DESCRIBE users;

Confirmar que los tokens estén definidos como TEXT:

fusionauth_access_token TEXT
fusionauth_refresh_token TEXT

Validar si ya existe el usuario:

SELECT id, name, email, fusionauth_id
FROM users
WHERE email = 'correo@dominio.gob.mx'
   OR fusionauth_id = 'id-de-fusionauth';

Si existe un conflicto de datos, revisar si corresponde actualizar el registro existente o depurar el registro duplicado.

Recomendación final

Si después de aplicar las soluciones anteriores el problema continúa, se recomienda recopilar la siguiente información antes de solicitar soporte:

• URL del sistema donde se presenta el error.
• Captura de pantalla del error.
• Fragmento relevante del archivo storage/logs/laravel.log.
• Valor configurado en APP_URL.
• Valor configurado en FUSIONAUTH_REDIRECT_URI.
• Confirmación de que la URI de callback coincide con FusionAuth.
• Resultado de php artisan route:list | grep autenticacion.
• Confirmación de que la tabla users contiene los campos requeridos.

Con esta información será más sencillo identificar el origen del problema y aplicar una solución puntual.