Download the PHP package laramicrosoft/auth without Composer

LaraMicrosoft-Auth

Librería PHP para autenticación social con Microsoft Entra ID (Office 365) mediante OAuth 2.0. Pensada para backends en PHP (Laravel, Slim, etc.) que exponen la lógica de login; el frontend (Vue, Nuxt, React) solo redirige al usuario a Microsoft y envía el código de autorización de vuelta al backend.

• PHP 8.4+
• Flujo: Authorization Code (backend confidencial)
• Frontend: Cualquier SPA o SSR (Vue, Nuxt, React, etc.)

Índice

• Requisitos
• Instalación
• Flujo de autenticación
• Registro en Azure (Entra ID)
• Configuración en el backend
• Endpoints del backend
• Integración en el frontend
• Referencia de la API
• Datos que devuelve Office 365
• Opciones de configuración
• Solución de problemas
• Seguridad
• Licencia

Requisitos

• PHP >= 8.4
• Composer 2.x
• Aplicación registrada en Azure Portal (Microsoft Entra ID) con Client ID, Client Secret y URI de redirección configurados

Instalación

Flujo de autenticación

1. El frontend pide al backend la URL de autorización (y opcionalmente un state).
2. El backend genera la URL de Microsoft, guarda el state en sesión y devuelve { url, state }.
3. El frontend redirige al usuario a esa URL; el usuario inicia sesión en Microsoft.
4. Microsoft redirige a tu redirect_uri con code y state en la query.
5. El frontend envía code y state al backend; el backend valida el state, canjea el code por tokens y usuario, y establece la sesión (o devuelve un token).

Registro en Azure (Entra ID)

Pasos

1. Entra en Azure Portal → Microsoft Entra ID → Registros de aplicaciones → Nuevo registro.

2. Nombre: por ejemplo Mi App o LaraMicrosoft-Auth Demo.

3. Tipos de cuenta admitidos:

   • Solo mi organización: solo usuarios de tu tenant.
   • Cualquier organización: cuentas laborales o escolares de cualquier tenant.
   • Cuentas personales y laborales: incluye cuentas Microsoft personales (outlook.com, etc.).

4. URI de redirección:

   • Tipo Web.
   • URL donde Microsoft enviará al usuario tras el login. Debe coincidir exactamente con la ruta de callback de tu app (backend o frontend), por ejemplo:
     • Producción: https://tu-dominio.com/auth/entra/callback
     • Local: http://localhost:3000/auth/callback (ajusta puerto y ruta a tu app).

5. Tras crear el registro, anota:

   • Id. de aplicación (cliente) → lo usarás como client_id.
   • Id. de directorio (inquilino) → lo usarás como tenant (o common para multi-tenant).

6. Certificados y secretos → Nuevo secreto de cliente → copia el Valor (solo se muestra una vez) → client_secret.

7. Permisos de API → Agregar un permiso → Microsoft Graph → Permisos delegados. Añade al menos:
   • openid
   • profile
   • email
   • User.Read

Resumen de valores

Configuración en el backend

Crea la configuración a partir de un array (por ejemplo variables de entorno):

Ejemplo de .env:

La librería exige que client_id, client_secret y redirect_uri no estén vacíos; si lo están, se lanzará una excepción al crear la config.

Endpoints del backend

Tu aplicación debe exponer al menos dos rutas que usen EntraIdAuthService.

1. Obtener URL de login

El frontend llama a esta ruta para obtener la URL a la que redirigir al usuario.

Ejemplo (pseudo-framework):

El frontend guarda state (por ejemplo en sessionStorage) y redirige al usuario a url.

2. Callback: canjear código por token y usuario

Microsoft redirige al usuario a tu redirect_uri con ?code=...&state=.... El frontend (o el backend si el callback es una ruta del propio backend) debe enviar code y state a esta ruta.

Ejemplo (pseudo-framework):

Integración en el frontend

Vue 3 o React (fetch)

Iniciar login:

Página de callback (ruta que hayas configurado como redirect_uri en Azure):

Nuxt 3

Página de login (pages/login.vue):

Página de callback (pages/auth/callback.vue): la URL de esta página debe ser exactamente la configurada como redirect_uri en Azure.

Referencia de la API

EntraIdResourceOwner (usuario)

• getId() – identificador (sub/oid)
• getEmail() – email o preferred_username
• getName() – nombre completo
• getGivenName() – nombre
• getFamilyName() – apellido
• toArray() – array con todos los claims que devuelve Microsoft (userinfo)

Datos que devuelve Office 365

Para ver toda la respuesta de Entra ID (tokens + usuario), usa exchangeCodeAndGetFullResponse():

Campos típicos en token_response

Campos típicos en user (userinfo)

Microsoft puede devolver más campos según permisos y configuración del tenant. Con exchangeCodeAndGetFullResponse() o $user->toArray() tienes siempre el array completo para inspeccionar o guardar.

Opciones de configuración

Solución de problemas

AADSTS900144 — "The request body must contain the following parameter: 'client_id'"

Significa que la petición al endpoint de tokens de Microsoft no incluye client_id.

• Comprueba que en tu .env (o config) tengas ENTRA_CLIENT_ID con el valor del Id. de aplicación (cliente) del registro en Azure.
• Asegúrate de que la app lee esa variable al construir EntraIdConfig y que no esté vacía. Si está vacía, la librería lanzará una excepción al crear la config.

AADSTS50011 — "Reply URL does not match"

La redirect_uri que envías no coincide con ninguna de las URLs configuradas en el registro de la aplicación.

• En Azure → Registro de la aplicación → Autenticación → URI de redirección, añade exactamente la misma URL que usas en redirect_uri (incluyendo protocolo, dominio, puerto y path).

Invalid state / Estado inválido

• El state que envías en el callback debe ser el mismo que guardaste al generar la URL (por ejemplo en sesión).
• Asegúrate de que el frontend envía el mismo state que recibió al pedir la URL y de que el backend compara con el guardado (por sesión o almacén equivalente).

Código ya canjeado o expirado

Los códigos de autorización son de un solo uso y caducan en poco tiempo (aprox. 1 minuto). Si el usuario recarga la página de callback o se envía el mismo código dos veces, Microsoft devolverá error; en ese caso hay que pedir de nuevo la URL de login e iniciar el flujo otra vez.

Seguridad

• State: Siempre genera y valida un state aleatorio para evitar ataques CSRF. Guarda el state en sesión (o almacén vinculado al usuario) al generar la URL y compáralo en el callback.
• Client secret: No expongas nunca el client_secret en el frontend; úsalo solo en el backend.
• HTTPS: En producción usa siempre HTTPS para redirect_uri y para las rutas de tu API.
• Redirect URI: Registra solo las URLs que realmente uses; evita wildcards si no son necesarios.

Licencia

MIT.