Cómo utilizar las extensiones del directorio Entra ID con PowerShell
Extensiones de directorio para personalizar los datos almacenados para objetos Entra ID
Si ha utilizado PowerShell para trabajar con buzones de correo de Exchange, probablemente conozca los quince atributos personalizados de valor único y cinco de valor múltiple. Las organizaciones pueden utilizar atributos personalizados cuando elijan almacenar información sobre buzones de correo, listas de distribución y otros objetos habilitados para correo. Entra ID sincroniza los atributos personalizados de los buzones con las cuentas de usuario propietarias de los buzones y almacena los valores en la propiedad onPremisesExtensionAttributes. Los atributos personalizados de valores múltiples no están sincronizados desde Exchange a Entra ID.
El uso de atributos personalizados en Exchange varía desde almacenar detalles sobre algún procesamiento realizado en un buzón hasta detalles estáticos sobre el propietario del buzón (como un número de placa). El punto es que Microsoft no dicta cómo las organizaciones usan los atributos personalizados, que existen para hacer que Exchange sea más útil para los clientes.
Las extensiones de directorio son el equivalente de Entra ID. A diferencia de los atributos personalizados de Exchange, las extensiones de directorio son específicas de inquilinos individuales y están asociadas con aplicaciones registradas con Entra ID.
¿Suena complejo? Bueno, en la práctica es más sencillo, así que definamos y usemos algunas extensiones de directorio usando el SDK de Microsoft Graph PowerShell. Desafortunadamente, la documentación actual de Microsoft utiliza el módulo Azure AD, pero es fácil cambiar los cmdlets ahora obsoletos después de consultar la descripción basada en Graph de cómo funcionan las extensiones de directorio.
Crear extensiones de directorio
El primer paso es crear una aplicación Entra ID registrada o elegir una aplicación registrada existente para contener atributos de extensión. Podemos crear una nueva aplicación usando PowerShell o mediante el centro de administración de Entra ID. La información importante a tener en cuenta es el identificador de la aplicación (propiedad ID) porque es necesario para crear extensiones de directorio. Este código crea una nueva aplicación y su entidad de servicio.
$ExtensionApp = New-MgApplication -DisplayName "Extension App to Store Properties for My Tenant"
New-MgServicePrincipal -AppId $ExtensionApp.AppId
Con una aplicación implementada, podemos agregar algunas extensiones de directorio. Este ejemplo muestra cómo agregar dos extensiones de directorio a la aplicación. La primera extensión de directorio (“CostCenter”) solo se puede usar con objetos de usuario, mientras que la otra (“Subsidiaria”) está disponible tanto para usuarios como para grupos. Otros tipos admitidos incluyen dispositivos, aplicaciones y unidades administrativas. No puede incluir espacios en los nombres dados a las extensiones de directorio:
$ExtensionProperty1 = New-MgApplicationExtensionProperty -Name "CostCenter" -DataType "String" -TargetObjects "User" -ApplicationId $ExtensionApp.Id
$ExtensionProperty2 = New-MgApplicationExtensionProperty -Name "Subsidiary" -DataType "String" -TargetObjects "User", "Group" -ApplicationId $ExtensionApp.Id
A diferencia de las variables de PowerShell, las extensiones de directorio están fuertemente tipadas. En este caso, ambos se definen como cadenas y pueden almacenar hasta 256 caracteres. Los otros tipos de datos admitidos son binarios, booleanos, DateTime, Integer y LargeInteger.
Para comprobar el conjunto de extensiones de directorio definidas para la aplicación registrada y ver para qué objetos están disponibles las extensiones, ejecute el cmdlet Get-MgApplicationExtensionProperty:
Get-MgApplicationExtensionProperty -ApplicationId $ExtensionApp.Id | Format-Table Name, DataType, TargetObjects
Name DataType TargetObjects
---- -------- -------------
extension_450c03488bae4eb98cc22699c0b46690_Subsidiary String {User, Group}
extension_450c03488bae4eb98cc22699c0b46690_CostCenter String {User}
La documentación dice que una aplicación "propietaria" puede contener hasta cinco definiciones (como muestra la Figura 1, este aspecto de la documentación puede ser incorrecto o estar desactualizado) y una organización puede admitir hasta 100 extensiones de directorio para cada tipo de recurso (como un usuario ).
Usar extensiones de directorio
Para escribir valores en extensiones de directorio, creamos una tabla hash para contener los nombres de las extensiones a actualizar y los valores a asignar. En este ejemplo, completamos la tabla hash con los nombres de las dos extensiones de directorio que acabamos de definir y los valores que queremos asignar. Puedes combinar extensiones propiedad de diferentes aplicaciones.
$Properties = @{}
$Properties.Add('extension_450c03488bae4eb98cc22699c0b46690_CostCenter', "8ZW")
$Properties.Add('extension_450c03488bae4eb98cc22699c0b46690_Subsidiary', "Contoso U.S.A")
$UserId = (Get-MgUser -UserId Tricia.Griffin@office365itpros.com).Id
Update-MgUser -UserId $UserId -AdditionalProperties $Properties
Para recuperar los valores almacenados en las extensiones de directorio, especifique los nombres de las extensiones cuando ejecute Get-MgUser:
$User = Get-MgUser -UserId $UserId -Property ` extension_450c03488bae4eb98cc22699c0b46690_CostCenter,
extension_450c03488bae4eb98cc22699c0b46690_Subsidiary
$User.AdditionalProperties | Format-List
Key : @odata.context
Value : https://graph.microsoft.com/v1.0/$metadata#users(extension_450c03488bae4eb98cc22699c0b46690_Subsidiary,extension_450c03488bae4eb98cc22699c0b46690_CostCenter)/$entity
Key : extension_450c03488bae4eb98cc22699c0b46690_CostCenter
Value : 8ZW
Key : extension_450c03488bae4eb98cc22699c0b46690_Subsidiary
Value : Contoso U.S.A
Al escribir scripts, es más fácil recuperar valores para extensiones de directorio con una búsqueda de los datos contenidos en la propiedad additionalProperties. Por ejemplo:
$User.AdditionalProperties['extension_450c03488bae4eb98cc22699c0b46690_Subsidiary']
Contoso U.S.A
Las extensiones de directorio se pueden filtrar. Estos ejemplos muestran cómo usar filtros para buscar todas las cuentas de usuario que tienen un valor específico en una extensión de directorio:
[array]$Users = Get-MgUser -Filter "extension_450c03488bae4eb98cc22699c0b46690_CostCenter eq '8ZW'"
[array]$Users = Get-MgUser -Filter "extension_450c03488bae4eb98cc22699c0b46690_SeniorityDate ge '1983-10-02T23:59:00'"
[array]$Users = Get-MgUser -Filter "extension_450c03488bae4eb98cc22699c0b46690_WorkRemote eq 'true'"
Como se describió anteriormente, el cmdlet Update-MgUser actualiza los valores almacenados en las extensiones de directorio. La excepción a la regla es cuando desea escribir un valor nulo en una extensión de directorio. El cmdlet Update-MgUser no puede hacer esto por ahora (no poder manejar la variable especial $Null es una de las debilidades del SDK de Graph). La solución es pasar una tabla hash que contenga el nombre de la extensión del directorio y el valor $Null y usar la tabla como entrada para una solicitud de parche ejecutada por el cmdlet Invoke-MgGraphRequest:
$PropertyNull = @{}
$PropertyNull.add("extension_450c03488bae4eb98cc22699c0b46690_Subsidiary", $Null)
Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/Tricia.Griffin@office365itpros.com" -Body $PropertyNull
Eliminar extensiones de directorio
Se cometen errores y, a veces, es necesario eliminar una extensión de directorio. Para hacer esto, primero busque el identificador de la extensión:
Get-MgApplicationExtensionProperty -ApplicationId $ExtensionApp.Id | Format-Table Id, Name
Id Name
-- ----
cad8d83d-eada-47c7-9bf4-5c9ef87beed9 extension_450c03488bae4eb98cc22699c0b46690_HiringManager
b4948d37-ce31-4214-b885-8b44f5fbefe3 extension_450c03488bae4eb98cc22699c0b46690_RetirementDate
6af6c7fe-a516-4b3b-ba28-b80d0b91bd9a extension_450c03488bae4eb98cc22699c0b46690_BadgeNumber
de02f69a-d599-4f68-9cb1-9a2b07e8c395 extension_450c03488bae4eb98cc22699c0b46690_LeaveAllowance
7ba15153-d8b6-4ffc-8265-edd8ede66cbf extension_450c03488bae4eb98cc22699c0b46690_Subsidiary
5ce0873c-dc0f-4df0-bdeb-a0db895d5c2b extension_450c03488bae4eb98cc22699c0b46690_CostCenter
Luego ejecute el cmdlet Remove-MgApplicationExtensionProperty para eliminar la extensión del directorio. En este ejemplo, estoy eliminando la extensión del directorio que almacena información de la Subsidiaria. El cmdlet no solicita confirmación antes de eliminar la extensión del directorio. Su eliminación elimina cualquier dato contenido en la extensión para otros objetos de Entra ID, así que asegúrese de continuar antes de ejecutar el cmdlet.
Remove-MgApplicationExtensionProperty -ApplicationId $ExtensionApp.Id -ExtensionPropertyId 7ba15153-d8b6-4ffc-8265-edd8ede66cbfEs posible recrear una extensión de directorio con el mismo nombre. Sin embargo, la nueva extensión de directorio tiene un identificador diferente y no recuperará los datos eliminados cuando elimine la otra extensión de directorio.
Vale la pena considerar las extensiones de directorio
Los inquilinos de Microsoft tienen muchas opciones cuando se trata de almacenar datos en atributos personalizados. Los atributos personalizados de Exchange están disponibles y son accesibles para todos los inquilinos donde se utiliza Exchange Online, pero está restringido a quince atributos. Las extensiones del directorio Entra ID no dependen de ninguna otra aplicación, puede definir más extensiones (hasta los límites mencionados anteriormente) y admiten más tipos de objetos (consulte esta comparación para obtener información general útil). Es posible que no necesite utilizar extensiones de directorio ahora, pero nunca se sabe lo que podría suceder en el futuro.
Gestión de riesgos de ciberseguridad para Active Directory
Descubra cómo prevenir y recuperarse de ataques AD a través de estas soluciones de gestión de riesgos de ciberseguridad.