Emitir reclamaciones personalizadas con atributos de extensión de directorio en Microsoft Entra ID

• Usa atributos de extensión de directorio en Entra ID para agregar datos personalizados (por ejemplo sponsorid) a tokens SAML/OIDC.
• Registra las extensionProperties vía Microsoft Graph, asigna valores a usuarios y crea claims condicionados por grupos en la aplicación empresarial.
• Prueba con tokens interactivos y limita el alcance mediante grupos y validaciones en la aplicación.

Introducción Microsoft describe un flujo para pasar datos de usuario personalizados a aplicaciones durante el inicio de sesión, usando atributos de extensión de directorio en Entra ID. Esto permite incluir identificadores únicos (por ejemplo datos de patrocinio) en tokens SSO sólo para grupos seleccionados.

Antes de empezar

• Necesitas permisos de administrador para registrar atributos y modificar usuarios.
• Acceso a Microsoft Graph Explorer o a una app con permisos Graph adecuados.
• El identificador de la app (AppObjectId y Client ID) y los ObjectId de usuarios y grupos.

Pasos detallados

Paso 1: Registrar atributos de extensión de directorio Usa Graph Explorer para registrar dos atributos personalizados, por ejemplo sponsorid1 y sponsorid2, en la aplicación objetivo.

Envía una petición POST a:

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties

Cuerpo de ejemplo:

{
"name": "sponsorid1",
"dataType": "String",
"targetObjects": ["User"]
}

Repite para sponsorid2. Tras el registro recibirás nombres completos con este formato: extension_sponsorid1 extension_sponsorid2

Anota esos nombres exactos para usarlos después.

Paso 2: Asignar atributos de extensión a usuarios Usa Graph Explorer para hacer PATCH a los objetos de usuario y asignar valores a los atributos de extensión.

URL de la petición:

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}

Cuerpo de ejemplo:

{
"extension__sponsorid1": "ABC123"
}

Repite para cada usuario, asignando sponsorid1 o sponsorid2 según corresponda.

Paso 3: Crear claims en la aplicación empresarial En el portal de Entra ID: Aplicaciones empresariales > [Nombre de la app] > Inicio de sesión único > Atributos y reclamaciones.

1. Haz clic en Añadir nueva reclamación.
2. Pon un nombre (por ejemplo sponsorClaim1).
3. En condiciones de la reclamación, selecciona Miembro y elige el grupo que debe recibir la reclamación.
4. En atributo de origen, usa el nombre del atributo de extensión (por ejemplo extension__sponsorid1).

Repite para el segundo grupo y atributo.

Paso 4: Manejar el error de mapeo de reclamaciones Si aparece el error “Application requires custom signing key to customize claims” puedes permitir temporalmente la personalización sin clave de firma personalizada actualizando el manifiesto del app registration:

Incluye o cambia:

"acceptMappedClaims": true

Nota: esto evita el bloqueo inmediato, pero evalúa la seguridad antes de usarlo en producción.

Paso 5: Probar la configuración Llama al endpoint de autorización con un navegador: https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

Inicia sesión con usuarios pertenecientes a los grupos definidos. En https://jwt.ms verás los claims personalizados (sponsorid1 o sponsorid2) en el token SAML/OIDC. Los usuarios que no pertenezcan a esos grupos no recibirán la reclamación de sponsor.

Cuándo usar y cuándo evitar este enfoque

• Útil cuando necesitas pasar datos de usuario no estándares a aplicaciones sin cambiar el esquema del usuario principal.
• Evita usarlo para datos altamente sensibles sin cifrado o controles adicionales; evalúa el ciclo de vida y acceso a los atributos.
• Si la aplicación admite SCIM o sincronización de atributos directos, considera esa alternativa para sincronización a largo plazo.

Buenas prácticas de seguridad y privacidad

• Limita los claims por grupo y valida los valores en la aplicación antes de confiar en ellos.
• Mantén un registro de quién modifica los atributos y audita cambios periódicamente.
• Minimiza la retención de datos en los atributos; elimina valores cuando ya no sean necesarios.
• Evalúa implicaciones GDPR: documenta la base legal, acceso y procedimiento de eliminación.

Checklist por rol Admin

• Registrar extensionProperties en la app.
• Actualizar manifiesto si es necesario.
• Asignar atributos vía Graph a usuarios. Developer
• Validar claims en token y manejar ausencia/valores inesperados.
• Evitar confiar en claims para autorización sin comprobaciones adicionales. Security/Compliance
• Auditar cambios en atributos.
• Revisar exposición y encriptación si procede.

Solución de problemas rápida

• No aparecen claims: verifica nombres extension… y condiciones de grupo.
• Error de mapeo: confirma acceptMappedClaims en el manifiesto o prepara clave de firma.
• Valor vacío: comprueba que el usuario tiene el atributo asignado y que el token solicitado incluye el scope adecuado (openid).

Pruebas y criterios de aceptación

• Caso 1: Usuario A en Grupo 1 recibe sponsorClaim1 con el valor esperado.
• Caso 2: Usuario B en Grupo 2 recibe sponsorClaim2.
• Caso 3: Usuario C fuera de grupos no recibe ninguna reclamación de sponsor.
• Caso 4: Aplicación rechaza token si claim malformado o no cumple formato esperado.

Hoja de referencia rápida (cheat sheet)

• Registrar atributo:

  POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties
  {
  "name":"sponsorid1",
  "dataType":"String",
  "targetObjects":["User"]
  }

• Asignar valor a usuario:

  PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}
  {
  "extension__sponsorid1":"ABC123"
  }

• Manifiesto:

  "acceptMappedClaims": true

Consideraciones de compatibilidad y migración

• Si más tarde cambias el AppClientID (por ejemplo recreando la app), los nombres extension_ cambiarán y tendrás que re-mapear y reasignar los valores.
• Para migraciones grandes, automatiza la asignación con scripts PowerShell o llamadas Graph en lote.

Resumen Usar atributos de extensión en Entra ID permite emitir claims personalizados por grupo sin modificar el esquema principal del usuario. Sigue las buenas prácticas de seguridad, prueba con casos reales y documenta procedimientos de auditoría.

Importante: revisa políticas internas antes de exponer datos personalizados en tokens SSO.