Cómo inventariar Service Principals en Azure y ligarlos a proyectos y repositorios
Los registros de aplicaciones, los Service Principals y las identidades administradas forman parte del día a día de cualquier plataforma que trabaje con Azure.
Al principio es fácil mantenerlos bajo control. Hay pocos pipelines, pocas integraciones y todo el equipo recuerda para qué sirve cada identidad. Sin embargo, a medida que crece la plataforma, empiezan a aparecer preguntas difíciles de responder:
- ¿Qué aplicación utiliza esta identidad?
- ¿A qué proyecto pertenece?
- ¿Qué repositorio la despliega?
- ¿En qué entorno se usa?
- ¿Quién es el responsable?
- ¿Qué ocurre si mañana caduca uno de sus secretos?
Microsoft Entra permite consultar identidades y asignar propietarios. Azure RBAC muestra qué permisos tiene cada identidad sobre los recursos de Azure. Pero gran parte del contexto operativo suele vivir fuera de ambos sistemas: en GitHub, Azure DevOps, una base de datos interna, una hoja de cálculo o, en el peor de los casos, en la memoria del equipo.
El problema no suele ser descubrir que una identidad existe. El problema es entender rápidamente qué depende de ella y quién debe actuar cuando algo falla.
La buena noticia es que no hace falta construir una gran plataforma de gobierno para mejorar esta situación. Con un sistema pequeño puedes cubrir lo esencial:
- Descubrir las identidades existentes en Microsoft Entra.
- Revisar si están activas.
- Detectar secretos y certificados próximos a caducar.
- Relacionar cada identidad con un proyecto, repositorio, equipo o entorno.
- Identificar identidades activas que nadie reconoce como propias.
En este artículo veremos cómo plantear ese sistema paso a paso utilizando Microsoft Graph, el SDK de identidad de Azure y una base de datos sencilla para almacenar el contexto operativo.
Un escenario que probablemente te resulte familiar
Son las nueve de un lunes y uno de los pipelines de producción empieza a fallar con el siguiente error:
AADSTS7000222: The provided client secret keys are expired.
Abres Microsoft Entra, buscas el client ID que aparece en el log y encuentras la Enterprise Application asociada. Hasta ahí, todo bien.
El problema empieza cuando intentas responder a la siguiente pregunta: ¿Qué repositorio está utilizando este Service Principal? Quizá sea el repositorio de pagos, el de facturación o una integración antigua que nadie ha modificado durante dos años. La identidad puede tener propietarios asignados en Entra, pero eso no indica necesariamente qué workflow utiliza el secreto, qué entorno depende de él o qué servicio dejará de funcionar.
Empieza entonces una investigación manual:
- Buscar el client ID en GitHub.
- Revisar secretos de organizaciones y repositorios.
- Consultar documentación interna.
- Preguntar en Slack o Teams.
- Examinar pipelines antiguos.
- Intentar localizar a la persona que creó la identidad.
La renovación del secreto puede llevar cinco minutos. Descubrir dónde se utiliza puede llevar varias horas. Ese vacío entre la identidad técnica y el contexto operativo es el que queremos cerrar.
Tres conceptos que conviene no mezclar
Antes de construir el inventario, es importante diferenciar varias piezas que habitualmente se agrupan bajo expresiones como «la aplicación» o «el SPN».
- App Registration - La definición global de una aplicación: permisos, URI, credenciales y configuración de autenticación. Dónde consultarlo:
GET /applicationsen Microsoft Graph. - Enterprise Application - La instancia de una aplicación dentro de un tenant. Dónde consultarlo:
GET /servicePrincipals. - Service Principal - La identidad no humana utilizada para autenticarse y obtener tokens. Es el mismo objeto que la Enterprise Application.
La relación habitual es la siguiente:
flowchart TD
App[App Registration] SP[Enterprise Application / Service Principal] Consumers[Pipelines, APIs, scripts e integraciones]
App -->|appId / client ID| SP
SP --> Consumers
La App Registration contiene la definición de la aplicación. El Service Principal representa esa aplicación dentro de un tenant concreto. El campo que normalmente conecta ambos objetos es appId, conocido también como client ID.
Un pipeline de GitHub Actions, un backend desplegado fuera de Azure o una integración con un SaaS suelen autenticarse utilizando ese client ID junto con un secreto, un certificado o una identidad federada.
Sin embargo, no todos los Service Principals tienen una App Registration local. Cuando instalas una aplicación SaaS, utilizas una aplicación multi-tenant o consumes determinados servicios publicados por Microsoft, puede existir un Service Principal en tu tenant sin que aparezca una App Registration equivalente en /applications. Por eso, un inventario que consulte únicamente App Registrations estará incompleto.
Qué información no ofrece Entra por sí solo
Microsoft Entra conoce la identidad, sus credenciales, su estado y sus propietarios administrativos. Pero normalmente no conoce el contexto completo en el que esa identidad se utiliza.
Por ejemplo, Entra no responde directamente a preguntas como:
- Este Service Principal pertenece al proyecto Billing.
- Esta identidad la utiliza el repositorio
company/payments-api. - Este client ID se usa únicamente en producción.
- El equipo responsable es Platform Payments.
- La identidad puede eliminarse cuando se retire un determinado servicio.
- El secreto está almacenado en los secrets de un repositorio concreto.
Los propietarios de Entra indican quién puede administrar una identidad, pero no siempre quién conoce el servicio que depende de ella. Tampoco existe un recurso ARM natural sobre el que añadir etiquetas de proyecto, repositorio o producto cuando hablamos de Service Principals.
Por eso es útil mantener dos capas separadas:
- Inventario técnico, obtenido desde Microsoft Graph.
- Contexto operativo, almacenado en una base de datos controlada por tu organización.
Managed Identity primero; Service Principal cuando sea necesario
Antes de empezar a inventariar secretos, conviene recordar que no todos los escenarios deberían utilizar uno. Siempre que sea posible, las Managed Identities y la Workload Identity Federation deberían ser la opción preferente. Reducen la necesidad de almacenar credenciales de larga duración y eliminan gran parte del trabajo manual de rotación.
- App Service o Azure Function accede a Storage o Key Vault - Opción recomendada: Managed Identity. Motivo: No requiere secretos gestionados por el equipo.
- Pod de AKS accede a recursos de Azure - Opción recomendada: Workload Identity o identidad asignada por el usuario. Motivo: Integración nativa con la identidad del workload.
- GitHub Actions despliega en Azure - Opción recomendada: Workload Identity Federation mediante OIDC. Motivo: Evita almacenar un client secret en GitHub.
- Runner local o desplegado en otra nube - Opción recomendada: Service Principal con certificado o secreto. Motivo: No existe un recurso de Azure que pueda emitir la identidad.
- Integración con un SaaS externo - Opción recomendada: Enterprise Application. Motivo: El proveedor controla la aplicación.
- Script legacy con variables de entorno - Opción recomendada: Service Principal con secreto. Motivo: Puede requerir una migración progresiva.
Aunque una organización priorice la federación, seguirá teniendo Service Principals tradicionales durante bastante tiempo. Además, las Managed Identities también aparecen en Microsoft Graph como objetos servicePrincipal, normalmente con:
servicePrincipalType = "ManagedIdentity"
Por tanto, el inventario debería incluirlas. No necesitan una alerta de rotación manual, pero sí puede ser útil conocer:
- Qué identidades existen.
- Si siguen activas.
- Qué recurso las creó.
- Si tienen asignaciones RBAC.
- Si continúan teniendo un propietario operativo.
Qué debería hacer el sistema
No es necesario empezar con una aplicación compleja. Una primera versión puede dividirse en dos capas:
flowchart LR
subgraph Azure["Inventario técnico"]
Graph[Microsoft Graph] Fetcher[Proceso de descubrimiento] Cache[(Inventario almacenado)]
end
subgraph Context["Contexto operativo"]
Projects[Proyectos] Repositories[Repositorios] Teams[Equipos] Assignments[(Asignaciones)]
end
subgraph Usage["Consumo"]
API[API] UI[Panel o informe] Alerts[Alertas]
end
Graph --> Fetcher
Fetcher --> Cache
Cache --> Assignments
Projects --> Assignments
Repositories --> Assignments
Teams --> Assignments
Cache --> API
Assignments --> API
API --> UI
API --> Alerts
La primera capa responde: ¿Qué identidades existen y en qué estado se encuentran? La segunda responde: ¿A qué proyecto, repositorio, entorno o equipo pertenece cada identidad? Juntas permiten responder una tercera pregunta mucho más útil: ¿Quién tiene que actuar cuando una credencial está a punto de caducar?
Paso 1: obtener acceso a Microsoft Graph
Para consultar las aplicaciones y los Service Principals del tenant puedes utilizar @azure/identity. Una implementación básica con ClientSecretCredential sería la siguiente:
import { ClientSecretCredential } from "@azure/identity" ;
const tenantId = process . env . AZURE_TENANT_ID ;
const clientId = process . env . AZURE_CLIENT_ID ;
const clientSecret = process . env . AZURE_CLIENT_SECRET ;
if ( ! tenantId || ! clientId || ! clientSecret ) { throw new Error ( "Faltan AZURE_TENANT_ID, AZURE_CLIENT_ID o AZURE_CLIENT_SECRET" , ) ; }
export const azureCredential = new ClientSecretCredential ( tenantId , clientId , clientSecret , ) ;
Para obtener un token de Microsoft Graph:
const GRAPH_SCOPE = "https://graph.microsoft.com/.default" ;
const tokenResponse = await azureCredential . getToken ( GRAPH_SCOPE , { abortSignal : AbortSignal . timeout ( 15_000 ) , } ) ;
if ( ! tokenResponse ? . token ) { throw new Error ( "No se pudo obtener un token de Microsoft Graph" ) ; }
El Service Principal que ejecute este inventario debe ser una identidad de lectura independiente de las identidades que se están inventariando. Para consultar aplicaciones y Service Principals necesita normalmente:
Application.Read.All
Debe configurarse como permiso de aplicación y recibir consentimiento de administrador. Si Graph devuelve un error 403, conviene mostrar un mensaje explícito:
if ( response . status === 403 ) { throw new Error ( "Microsoft Graph no permite leer las identidades. " + "Concede Application.Read.All como permiso de aplicación " + "y aplica consentimiento de administrador." , ) ; }
Evita transformar todos los errores en un mensaje genérico como «Azure no está disponible». Una configuración incorrecta debe poder distinguirse de un problema de red o de throttling.
Autenticación diferida para entornos locales
Si el inventario forma parte de una aplicación más grande, quizá no quieras que toda la aplicación deje de arrancar cuando Azure no está configurado. En ese caso puedes crear la credencial solo cuando se utilice:
import { ClientSecretCredential } from "@azure/identity" ;
let credential : ClientSecretCredential | null = null ;
function buildCredential ( ) : ClientSecretCredential { const tenantId = process . env . AZURE_TENANT_ID ; const clientId = process . env . AZURE_CLIENT_ID ; const clientSecret = process . env . AZURE_CLIENT_SECRET ; if ( ! tenantId || ! clientId || ! clientSecret ) { throw new Error ( "El proveedor Azure no está configurado" ) ; } return new ClientSecretCredential ( tenantId , clientId , clientSecret ) ; }
export function getAzureCredential ( ) : ClientSecretCredential { credential ??= buildCredential ( ) ; return credential ; }
Así, una persona puede trabajar en otras partes de la aplicación sin disponer necesariamente de credenciales de Azure. El panel de identidades puede mostrarse como no configurado o degradado, mientras el resto del sistema sigue funcionando.
Paso 2: descubrir todas las identidades del tenant
Uno de los errores más frecuentes es consultar únicamente:
GET / applications
Eso deja fuera:
- Enterprise Applications de terceros.
- Aplicaciones de catálogo.
- Service Principals sin una App Registration local.
- Managed Identities.
- Algunas identidades antiguas o creadas por integraciones externas.
Para construir un inventario completo deberías consultar al menos:
GET / applicationsGET / servicePrincipals
Puedes hacer ambas llamadas en paralelo:
const [ applications , servicePrincipals ] = await Promise . all ( [ listGraphPages < GraphApplication > ( graphUrl ( "applications" , [ "id" , "appId" , "displayName" , "createdDateTime" , "signInAudience" , "passwordCredentials" , "keyCredentials" , ] . join ( "," ) , ) , token , ) , listGraphPages < GraphServicePrincipal > ( graphUrl ( "servicePrincipals" , [ "id" , "appId" , "displayName" , "accountEnabled" , "servicePrincipalType" , "appOwnerOrganizationId" , "createdDateTime" , "passwordCredentials" , "keyCredentials" , ] . join ( "," ) , ) , token , ) , ] ) ;
Una función sencilla para construir las URLs puede ser:
function graphUrl ( resource : string , select : string ) : string { const url = new URL ( `https://graph.microsoft.com/v1.0/${resource}` ) ; url . searchParams . set ( "$select" , select ) ; return url . toString ( ) ; }
Los campos más relevantes son:
passwordCredentials: secretos asociados.keyCredentials: certificados asociados.servicePrincipalType: permite identificar Managed Identities.appOwnerOrganizationId: indica qué tenant controla la aplicación.accountEnabled: muestra si la identidad está habilitada.signInAudience: diferencia aplicaciones single-tenant y multi-tenant.createdDateTime: ayuda a detectar identidades antiguas o creadas recientemente.appId: client ID utilizado por aplicaciones y pipelines.id: object ID del objeto concreto en el tenant.
Gestionar la paginación de Microsoft Graph
Microsoft Graph devuelve resultados paginados mediante @odata.nextLink. Una función reutilizable podría tener esta forma:
interface GraphPage < T > { value ?: T [ ] ; "@odata.nextLink" ?: string ; }
async function listGraphPages < T > ( initialUrl : string , token : string , ) : Promise < T [ ] > { const results : T [ ] = [ ] ; let nextUrl : string | null = initialUrl ; while ( nextUrl ) { const parsedUrl = new URL ( nextUrl ) ; if ( parsedUrl . hostname !== "graph.microsoft.com" ) { throw new Error ( "Microsoft Graph devolvió una URL de paginación no válida" ) ; } const response =
Comments
No comments yet. Start the discussion.