Uso del SDK de Microsoft Graph PowerShell para administrar políticas de acceso condicional

Necesidad de actualizar los scripts que administran las políticas de acceso condicional

En 2021, Damian Scoles escribió sobre la gestión de políticas de acceso condicional (CA) con PowerShell. En ese momento, los cmdlets relevantes provenían de los módulos AzureAD o AzureADPreview, los cuales Microsoft planea dejar de utilizar el 30 de marzo de 2024. Es hora de actualizar los scripts basados ​​en estos módulos para usar solicitudes de Graph API o el SDK de Microsoft Graph PowerShell. Este artículo explica cómo utilizar los cmdlets del SDK para administrar las políticas de CA.

Antes de comenzar, permítanme decirles que no creo que muchos inquilinos de Microsoft 365 utilicen PowerShell para crear políticas de acceso condicional. Como veremos, el cmdlet New-MgIdentityConditionalAccessPolicy ciertamente funciona, pero creo que es más fácil crear nuevas políticas de acceso condicional a través del centro de administración de Entra ID. Otro factor es que Microsoft tiende a actualizar la interfaz de usuario para adaptarse a las nuevas capacidades de políticas antes de que sea posible administrar la configuración con PowerShell. Algunos ejemplos son el uso de contextos de autenticación para identificar sitios específicos de SharePoint Online o insistir en que las sesiones utilicen una determinada fuerza de autenticación para la autenticación multifactor.

Invariablemente se produce un retraso entre la aparición de una nueva característica y la compatibilidad con los cmdlets de PowerShell. El retraso se ve agravado por la necesidad de que Microsoft actualice la API Graph para admitir nuevas funciones antes de que se pueda ejecutar el proceso de «generación automática» para llevar ese soporte a los cmdlets del SDK.

A los socios que administran inquilinos de clientes u organizaciones que ejecutan múltiples inquilinos les puede resultar conveniente implementar un conjunto de políticas para nuevos inquilinos, y ahí es donde resulta útil crear nuevas políticas de acceso condicional con PowerShell.

Conexión y obtención de detalles de políticas de acceso condicional

Primero, conectemos a Graph con el permiso (alcance) necesario para el acceso de lectura y escritura a las políticas de acceso condicional y usemos el cmdlet Get-MgIdentityConditionalAccessPolicy para devolver el conjunto de políticas en el inquilino.

Connect-MgGraph -NoWelcome -Scopes Policy.ReadWrite.ConditionalAccess  [array]$Policies = Get-MgIdentityConditionalAccessPolicy | Sort-Object DisplayName $Policies | Format-Table DisplayName, ModifiedDateTime, State  DisplayName                                                 ModifiedDateTime    State -----------                                                 ----------------    ----- Allow Access to IT Apps                                     05/12/2023 16:51:13 enabled Authentication Strength                                     25/10/2022 09:45:00 enabledForReportingButNotEnforced Azure Information Protection CA policy                                          disabled B2B Collaboration and Direct Connect Guests                 05/12/2023 16:51:15 enabled Block Guest Access to PowerShell                                                enabledForReportingButNotEnforced Block Weekend Access                                        08/05/2023 13:40:59 enabledForReportingButNotEnforced CA005: Require multi-factor authentication for guest access 05/12/2023 16:51:17 enabled Outlook Authentication Sessions                             05/12/2023 19:08:25 enabled Remove Access for Legacy Email Clients                      05/12/2023 16:51:19 enabled Require MFA access for Confidential Access SPO Sites        05/12/2023 16:51:21 enabled Restrict Access to Graph Explorer                           05/12/2023 19:08:42 enabled  

Una política de acceso condicional puede estar en los siguientes estados:

  • Habilitado: actualmente activo y utilizado por Entra ID para evaluar sesiones de conexión.
  • Desactivado: No se utiliza actualmente.
  • EnabledForReportingButNotEnforced: actualmente activo pero solo para fines de generación de informes. Entra ID no impone condiciones al evaluar las conexiones.

Como la mayoría de los demás objetos de Microsoft 365, cada política también tiene un GUID único (no se muestra) que los cmdlets usan para identificar una política. Podemos ver el identificador examinando las propiedades de una política:

$Policies[0] | Format-List  Conditions           : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessConditionSet CreatedDateTime      : 27/10/2022 20:19:01 Description          : DisplayName          : Allow Access to IT Apps GrantControls        : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessGrantControls Id                   : ead51ecc-0d37-412a-8b3f-aac6b61e6117 ModifiedDateTime     : 05/12/2023 16:51:13 SessionControls      : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessSessionControls State                : enabled TemplateId           : AdditionalProperties : {} 

Además del identificador (id), las propiedades más importantes son:

  • Condiciones: dicta las condiciones utilizadas para evaluar una sesión, como el dispositivo utilizado, la ubicación desde la que se origina la sesión y el estado de riesgo del usuario.
  • GrantControls: dicta las condiciones bajo las cuales se concede acceso a una sesión, como si se utiliza la autenticación multifactor.
  • Controles de sesión: dicta si Entra ID impone limitaciones a una sesión, como la frecuencia de inicio de sesión para que los usuarios demuestren que tienen credenciales (aquí se explica por qué una frecuencia de inicio de sesión frecuente es mala).

Estas propiedades corresponden a las secciones de la interfaz de usuario de Entra ID utilizadas para configurar los ajustes de acceso condicional (Figura 1).

Figura 1: Configuración para una política de acceso condicional

Desde una perspectiva de PowerShell, es fundamental comprender que muchas propiedades contienen muchas otras propiedades para almacenar la configuración de políticas. Aquí hay una vista de cada propiedad y lo que hay debajo:

$Policies[0].Conditions | Format-List  Applications               : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessApplications ClientAppTypes             : {all} ClientApplications         : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessClientApplications Devices                    : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessDevices Locations                  : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessLocations Platforms                  : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessPlatforms ServicePrincipalRiskLevels : {} SignInRiskLevels           : {} UserRiskLevels             : {} Users                      : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessUsers AdditionalProperties       : {}  $Policies[0].GrantControls | Format-List  AuthenticationStrength      : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAuthenticationStrengthPolicy BuiltInControls             : {mfa} CustomAuthenticationFactors : {} Operator                    : OR TermsOfUse                  : {} AdditionalProperties        : {[authenticationStrength@odata.context, https://graph.microsoft.com/v1.0/$metadata#identity/conditionalAccess/policies('ead51ecc-0d37-412a-8b3f-aac6b61e6117')/grantControls/authenticationStrength/$entity]}  $Policies[0].SessionControls | Format-List  ApplicationEnforcedRestrictions : Microsoft.Graph.PowerShell.Models.MicrosoftGraphApplicationEnforcedRestrictionsSessionControl CloudAppSecurity                : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCloudAppSecuritySessionControl DisableResilienceDefaults       : PersistentBrowser               : Microsoft.Graph.PowerShell.Models.MicrosoftGraphPersistentBrowserSessionControl SignInFrequency                 : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSignInFrequencySessionControl AdditionalProperties            : {} 

Algunas propiedades tienen otro nivel debajo. Por ejemplo, para acceder a los detalles de las cuentas de usuario y grupos a los que se aplica una política, debemos mirar la propiedad Usuarios de Condiciones. Aquí encontramos otro conjunto de propiedades. Debido a que la propiedad IncludeUsers está establecida en Todos, sabemos que la política se aplica a todas las cuentas excepto a las dos cuentas de usuario excluidas definidas en la propiedad ExcludeUsers:

$Policies[0].Conditions.Users | fl  ExcludeGroups                : {} ExcludeGuestsOrExternalUsers : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessGuestsOrExternalUsers ExcludeRoles                 : {} ExcludeUsers                 : {91813a30-f048-48f1-a0f2-fd7c72020515, b7289bc7-7e4e-44e2-ae1b-7e13e94e3749} IncludeGroups                : {} IncludeGuestsOrExternalUsers : Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessGuestsOrExternalUsers IncludeRoles                 : {} IncludeUsers                 : {All} AdditionalProperties         : {} 

Cuando ve un valor como Microsoft.Graph.PowerShell.Models.MicrosoftGraphConditionalAccessGuestsOrExternalUsers, significa que uno o más valores están presentes en una matriz. Puedes extraer los valores de esta manera:

$Values = $Conditions.Users | Select-Object -ExpandProperty ExcludeGuestsOrExternalUsers

Lo que resulta obvio de esta descripción es que interactuar con la configuración de las políticas de acceso condicional a través de los cmdlets del SDK requiere cierta familiaridad con la estructura utilizada para mantener la configuración de las políticas. En otras palabras, tómate un tiempo para husmear y encontrar dónde emergen las configuraciones de políticas individuales.

Preparándose para crear una nueva política de acceso condicional

La documentación del cmdlet New-MgIdentityConditionalAccessPolicy incluye varios ejemplos útiles que no tengo intención de replicar aquí. En lugar de eso, crearé una política relativamente simple para ilustrar el principio.

Antes de crear una política, es posible que un script necesite recopilar cierta información, que incluye:

Ubicaciones: una ubicación define desde dónde se puede originar una sesión, como un rango IPv4 o IPv6 específico. Las ubicaciones con nombre se recuperan con el cmdlet Get-MgIdentityConditionalAccessNamedLocation. Las políticas de acceso condicional utilizan el identificador (id) para una ubicación con nombre.

Get-MgIdentityConditionalAccessNamedLocation  Id                                   CreatedDateTime     DisplayName   ModifiedDateTime --                                   ---------------     -----------   ---------------- 6ff84108-eab2-4bba-bcea-c952075c2c9f 01/01/2021 16:01:22 IT Department 143f73a6-a30b-47b8-bad8-9381a04bbe65 24/01/2023 18:35:19 Ireland       24/01/2023 18:35:19 0053e3ac-90b5-4bd3-b51e-e2fae92564b0 24/01/2023 18:38:20 HQ            24/01/2023 18:38:20 

Usuarios, grupos y roles: las políticas de acceso condicional pueden establecer el alcance de su aplicación al incluir o excluir cuentas de usuario, grupos y roles administrativos. Por ejemplo, es una buena práctica excluir las cuentas Breakglass de las políticas de acceso condicional para garantizar que siempre haya una manera de iniciar sesión en un inquilino. Si desea crear o modificar una política con inclusiones o exclusiones, necesitará conocer los identificadores de las cuentas de usuario, grupos o roles administrativos de destino. Los identificadores de roles están disponibles ejecutando los cmdlets Get-MgDirectoryRole o Get-MgDirectoryRoleTemplate. El primero devuelve el conjunto de roles administrativos utilizados en el inquilino; el segundo devuelve todos los roles disponibles.

Aplicaciones: muchas políticas de acceso condicional controlan el acceso a aplicaciones como Exchange Online o SharePoint Online. Si desea especificar una aplicación en una política de acceso condicional, necesitará conocer su identificador, que puede encontrar ejecutando el cmdlet Get-MgServicePrincipal y verificando el resultado para encontrar la aplicación correcta. Por ejemplo, este código busca el identificador (AppId) de Exchange Online.

[array]$SPs = Get-MgServicePrincipal -All $Office365AppId = $SPs | Where-Object {$_.DisplayName -eq "Office 365 Exchange Online"} | Select-Object -ExpandProperty AppId 

Además, también necesitará saber si la política necesita implementar alguna configuración específica, como si cubre tipos de aplicaciones o plataformas de cliente específicos, o establece una frecuencia de inicio de sesión. Si utiliza esta última configuración, no establezca la frecuencia en menos de una semana a menos que sea absolutamente necesario, ya que obligar a las personas a iniciar sesión con frecuencia puede afectar su flujo de trabajo.

Crear una nueva política de acceso condicional

Sería posible construir una política exótica de acceso condicional y utilizarla como ejemplo. Un ejemplo más práctico demuestra cómo crear la conocida política para aplicar la autenticación multifactor a cualquier usuario que tenga un rol administrativo (la política cubre catorce roles seleccionados). Esta política debe ser utilizada por todos los inquilinos.

El primer paso es crear una estructura de parámetros para contener la configuración de la política. En términos de PowerShell, se trata de una tabla hash que contiene pares clave/valor. Algunos de los valores son otras tablas hash que contienen matrices. Por ejemplo, el valor Usuarios contiene la configuración de cuentas, grupos y roles incluidos o excluidos por la política. Usuarios es una tabla hash con matrices para usuarios, grupos, roles, etc. incluidos. La única diferencia entre la configuración de esta política y las recomendadas por Microsoft es que la política establece una frecuencia de inicio de sesión de 30 días para los administradores.

$PolicySettings = @{ 	displayName = "Require Multifactor authentication for admin roles" 	state = "enabled" 	conditions = @{ 		clientAppTypes = @( 			"all" 		) 		applications = @{ 			includeApplications = @( 				"All" 			)	 		} 		users = @{ 			excludeUsers = @( 				"aff4cd58-1bb8-4899-94de-795f656b4a18" 			) 			includeRoles = @( 				"62e90394-69f5-4237-9190-012177145e10" 				"194ae4cb-b126-40b2-bd5b-6091b380977d" 				"f28a1f50-f6e7-4571-818b-6a12f2af6b6c" 				"29232cdf-9323-42fd-ade2-1d097af3e4de" 				"b1be1c3e-b65d-4f19-8427-f6fa0d97feb9" 				"729827e3-9c14-49f7-bb1b-9608f156bbb8" 				"b0f54661-2d74-4c50-afa3-1ec803f12efe" 				"fe930be7-5e62-47db-91af-98c3a49a38b1" 				"c4e39bd9-1100-46d3-8c65-fb160da0071f" 				"9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3" 				"158c047a-c907-4556-b7ef-446551a6b5f7" 				"966707d0-3269-4727-9be2-8c3a10f19b9d" 				"7be44c8a-adaf-4e2a-84d6-ab2649e08a13" 				"e8611ab8-c189-46e8-94e1-60213ab1f814" 			) 		} 	} 	grantControls = @{ 		operator = "OR" 		builtInControls = @( 			"mfa" 		) 	} 	sessionControls = @{ 		signInFrequency = @{ 			value = 30 			type = "days" 			isEnabled = $true 		} 	} } 

Para crear la política, ejecute el cmdlet New-MgDirectoryConditionalPolicy:

New-MgIdentityConditionalAccessPolicy -BodyParameter $PolicySettings  Id                                   CreatedDateTime     Description DisplayName --                                   ---------------     ----------- ----------- b1e82588-96f9-4e3b-9881-b1fef352309c 17/12/2023 18:40:11             Require Multifactor authentication for admin roles 

Notará que el estado de la política está habilitado, lo que significa que Entra ID comenzará a utilizar la política inmediatamente. Si desea crear una política que tenga un impacto menor en un inquilino, considere limitar su alcance a un grupo seleccionado o cuentas de usuario individuales. Para hacer esto, incluya una matriz includeUsers o IncludeGroups en la estructura de parámetros.

Como ejemplo, busquemos el identificador de un grupo y usémoslo para actualizar la política. Primero, use el cmdlet Get-MgGroup para recuperar el identificador del grupo:

(Get-MgGroup -Filter "Displayname eq 'System Innovation'").Id 5c011293-7cc7-41c4-a0fc-3e3bb98db834 

Ahora cree una estructura de parámetros que solo actualice la sección Usuarios de Condiciones:

$UpdateSettings = @{     Conditions = @{         users = @{               includeGroups = @(                 "5c011293-7cc7-41c4-a0fc-3e3bb98db834"             )         }     } } 

Finalmente, ejecute el cmdlet Update-MgIdentityConditionalAccessPolicy después de obtener el identificador de la política de acceso condicional para actualizar:

$PolicyId = (Get-MgIdentityConditionalAccessPolicy -Filter "displayName eq 'Require Multifactor authentication for admin roles'").Id Update-MgIdentityConditionalAccessPolicy -BodyParameter $UpdateSettings -ConditionalAccessPolicyId $PolicyId 

Ahora solo los miembros del grupo seleccionado están sujetos a la política de acceso condicional.

Toma un poco de tiempo acostumbrarse

Trabajar con políticas de acceso condicional utilizando los cmdlets del SDK de Microsoft Graph PowerShell no es particularmente difícil una vez que domina cómo pasar valores para actualizar la configuración. Si no está acostumbrado a administrar el acceso condicional, le recomiendo que considere crear y actualizar políticas en un inquilino de desarrollo para asegurarse de que todo funcione como se espera antes de llevar el trabajo a su entorno de producción. Entra ID es muy bueno para seguir instrucciones de políticas de acceso condicional, así que asegúrese siempre de saber qué hace una configuración antes de cambiarla. De lo contrario, podría terminar encerrándose a usted y a otros fuera del inquilino.