Creación de un paquete de acceso en la administración de derechos para una aplicación con un solo rol mediante PowerShell
En la administración de derechos de Microsoft Entra, un paquete de acceso abarca las directivas de cómo los usuarios pueden obtener asignaciones para uno o varios roles de recursos. Los recursos pueden incluir grupos, aplicaciones y sitios de SharePoint Online.
En este artículo se describe cómo crear un paquete de acceso para una sola aplicación con un solo rol mediante PowerShell de Microsoft Graph. Este escenario se aplica principalmente a entornos que usan la administración de derechos para automatizar el acceso continuo para una aplicación de middleware o negocio específica. Una organización que tiene varios recursos o recursos con varios roles también puede modelar sus directivas de acceso con paquetes de acceso:
- Si la organización ya tiene un modelo de rol organizativo existente para sus roles empresariales, puede migrar ese modelo a Gobierno de Microsoft Entra ID y controlar el acceso con un modelo de roles organizativo.
- Si la organización tiene aplicaciones con varios roles, puede implementar directivas organizativas para gobernar el acceso a las aplicaciones integradas con Microsoft Entra ID
- Para obtener más información sobre cómo crear paquetes de acceso para otros escenarios, consulte tutorial: Administración del acceso a recursos en la administración de derechos y cómo crear un paquete de acceso en la administración de derechos.
Requisitos previos
El uso de esta característica requiere licencias de Gobierno de Microsoft Entra ID o el Conjunto de aplicaciones de Microsoft Entra. Para encontrar la licencia adecuada para tus requisitos, consulta Aspectos básicos de las licencias de Gobierno de Microsoft Entra ID.
Antes de empezar a crear el paquete de acceso, debe integrar la aplicación con Microsoft Entra ID. Si la aplicación aún no está presente en el inquilino de Microsoft Entra ID, siga las instrucciones de ese artículo para crear una aplicación y una entidad de servicio para el objeto. Asegúrese también de que el inquilino de Microsoft Entra ID cumpla los requisitos previos antes de configurar Microsoft Entra ID para la gobernanza de identidades.
Para crear el paquete de acceso y sus directivas y asignaciones asociadas, deberá tener lista la siguiente información:
Caso de uso | Opción de configuración | Variable de PowerShell |
---|---|---|
All | Nombre de la aplicación en el inquilino de Microsoft Entra ID | $servicePrincipalName |
All | Nombre del rol de la aplicación | $servicePrincipalRoleName |
All | Nombre del catálogo que contiene el paquete de acceso | $catalogName |
All | Nombre para proporcionar al paquete de acceso | $accessPackageName |
All | Descripción para proporcionar al paquete de acceso | $accessPackageDescription |
Separación de requisitos de deberes con un paquete de acceso no compatible | Id. del paquete de acceso no compatible | $incompatibleAccessPackageId (en caso de ser necesario) |
Los usuarios que aún no tienen asignaciones y no se asignarán automáticamente | lista de usuarios | $inputpath (en caso de ser necesario) |
Los usuarios con atributos específicos tienen automáticamente asignaciones | expresión de consulta para los usuarios en el ámbito | $autoAssignmentPolicyFilter (en caso de ser necesario) |
Permitir que los usuarios que no tengan una asignación soliciten una asignación | el ámbito de los usuarios que pueden solicitar, los aprobadores y el período de revisión de acceso | depende de los requisitos |
Automatización de la creación o eliminación de asignaciones en función de flujos de trabajo de unión o de salida en flujos de trabajo de ciclo de vida | los nombres de los flujos de trabajo que proporcionan y quitan acceso | depende de los requisitos |
Autenticarse en Microsoft Entra ID
En esta sección se muestra cómo interactuar con Gobierno de Microsoft Entra ID mediante cmdlets de PowerShell de Microsoft Graph.
La primera vez que la organización use estos cmdlets para este escenario, deberá tener un rol de administrador global para permitir el uso de PowerShell de Microsoft Graph en el inquilino. Las interacciones posteriores pueden usar un rol con privilegios inferiores, como:
Abra PowerShell.
Si aún no tiene instalados los módulos de PowerShell de Microsoft Graph, instale el módulo
Microsoft.Graph.Identity.Governance
y otros mediante este comando:Install-Module Microsoft.Graph
Si ya tiene instalados los módulos, asegúrese de que usa una versión reciente:
Update-Module microsoft.graph.users,microsoft.graph.identity.governance,microsoft.graph.applications
Conéctese a Microsoft Entra ID:
$msg = Connect-MgGraph -ContextScope Process -Scopes "User.ReadWrite.All,Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All,EntitlementManagement.ReadWrite.All"
Si es la primera vez que ha usado este comando, es posible que tenga que dar su consentimiento para permitir que las herramientas de la línea de comandos de Microsoft Graph tengan estos permisos.
Creación de un catálogo en la administración de derechos de Microsoft Entra
De manera predeterminada, cuando un administrador interactúa por primera vez con la administración de derechos, se crea automáticamente un catálogo predeterminado. Sin embargo, los paquetes de acceso para las aplicaciones gobernadas deben estar en un catálogo designado.
Especifique el nombre del catálogo.
$catalogName = "Business applications"
Si ya tiene un catálogo para el escenario de gobernanza de las aplicaciones, continúe con el paso 4 de esta sección.
Si aún no tiene un catálogo para el escenario de gobernanza de las aplicaciones, cree un catálogo.
$catalog = New-MgEntitlementManagementCatalog -DisplayName $catalogName
Busque el id. del catálogo.
$catalogFilter = "displayName eq '" + $catalogName + "'" $catalog = Get-MgEntitlementManagementCatalog -Filter $catalogFilter -All -expandProperty resources,accessPackages if ($catalog -eq $null) { throw "catalog $catalogName not found" } $catalogId = $catalog.Id
Agregar la aplicación como un recurso al catálogo
Una vez creado el catálogo, agregue la aplicación como un recurso en ese catálogo.
Especifique el nombre de la aplicación y el nombre del rol de la aplicación. Use el nombre de la aplicación como valor de
servicePrincipalName
.$servicePrincipalName = "SAP Cloud Identity Services" $servicePrincipalRoleName = "User"
Busque el id. de la entidad de servicio de la aplicación.
$servicePrincipalFilter = "displayName eq '" + $applicationName + "'" $servicePrincipal = Get-MgServicePrincipal -Filter $servicePrincipalFilter -all if ($servicePrincipal -eq $null) { throw "service principal $servicePrincipalName not found" } $servicePrincipalId = $servicePrincipal.Id
Compruebe si la aplicación ya está presente en el catálogo como un recurso. Si ya está presente, continúe con el paso 6 de esta sección.
$resourceId = $null foreach ($r in $catalog.Resources) { if ($r.OriginId -eq $servicePrincipalId) { $resourceId = $r.id; break } } if ($resourceId -ne $null) { write-output "resource already in catalog" } else {write-output "resource not yet in catalog"}
Agregue la entidad de servicio de la aplicación como un recurso al catálogo.
$resourceAddParams = @{ requestType = "adminAdd" resource = @{ originId = $servicePrincipalId originSystem = "AadApplication" } catalog = @{ id = $catalogId } } $resourceAdd = New-MgEntitlementManagementResourceRequest -BodyParameter $resourceAddParams if ($resourceAdd -eq $null) { throw "resource could not be added" } sleep 5
Recupere el id. y el ámbito del recurso en ese catálogo.
$resource = $null $resourceId = $null $resourceScope = $null $catalogResources = Get-MgEntitlementManagementCatalogResource -AccessPackageCatalogId $CatalogId -ExpandProperty "scopes" -all foreach ($r in $catalogResources) { if ($r.OriginId -eq $servicePrincipalId) { $resource = $r; $resourceId = $r.id; $resourceScope = $r.Scopes[0]; break } } if ($resourceId -eq $null) { throw "resource was not added" }
Recupere los roles de la aplicación.
$resourceRoleFilter = "(originSystem eq 'AadApplication' and resource/id eq '" + $resourceId + "')" $resourceRoles = @(get-mgentitlementmanagementcatalogresourcerole -AccessPackageCatalogId $catalogId -Filter $resourceRoleFilter -All -ExpandProperty "resource") if ($resourceRoles -eq $null -or $resourceRoles.count -eq 0) { throw "no roles available" }
Seleccione el rol que se incluirá en el paquete de acceso.
$resourceRole = $null foreach ($r in $resourceRoles) { if ($r.DisplayName -eq $servicePrincipalRoleName) { $resourceRole = $r; break; } } if ($resourceRole -eq $null) { throw "role $servicePrincipalRoleName not located" }
Crear el paquete de acceso para la aplicación
A continuación, usará PowerShell para crear un paquete de acceso en un catálogo que incluya el rol de la aplicación.
Especifique el nombre y la descripción del paquete de acceso.
$accessPackageName = "SAP Cloud Identity Services" $accessPackageDescription = "A user of SAP Cloud Identity Services" $accessPackageHidden = $true
Compruebe que el paquete de acceso aún no exista.
foreach ($a in $catalog.AccessPackages) { if ($a.DisplayName -eq $accessPackageName) { throw "access package $accessPackageName already exists" } }
Cree el paquete de acceso.
$accessPackageParams = @{ displayName = $accessPackageName description = $accessPackageDescription isHidden = $accessPackageHidden catalog = @{ id = $catalog.id } } $accessPackage = New-MgEntitlementManagementAccessPackage -BodyParameter $accessPackageParams $accessPackageId = $accessPackage.Id
Agregar el rol de aplicación al paquete de acceso
Una vez que haya creado un paquete de acceso, vincule el rol del recurso en el catálogo al paquete de acceso.
$rrsParams = @{
role = @{
id = $resourceRole.Id
displayName = $resourceRole.DisplayName
description = $resourceRole.Description
originSystem = $resourceRole.OriginSystem
originId = $resourceRole.OriginId
resource = @{
id = $resource.Id
originId = $resource.OriginId
originSystem = $resource.OriginSystem
}
}
scope = @{
id = $resourceScope.Id
originId = $resourceScope.OriginId
originSystem = $resourceScope.OriginSystem
}
}
$roleAddRes = New-MgEntitlementManagementAccessPackageResourceRoleScope -AccessPackageId $accessPackageId -BodyParameter $rrsParams
Crear directivas de asignación de paquetes de acceso para la asignación directa
En esta sección creará la primera directiva de asignación de paquetes de acceso en el paquete de acceso, una directiva de asignación de paquetes de acceso para la asignación directa, que se puede usar para realizar un seguimiento de los usuarios que ya tienen acceso a la aplicación. En la directiva de ejemplo creada en esta sección, solo los administradores o los administradores de asignación de paquetes de acceso pueden asignar acceso; los usuarios conservan el acceso indefinidamente y no hay aprobaciones ni revisiones de acceso.
Creación de una directiva.
$policy1Name = "Direct assignment policy" $policy1Description = "policy for administrative assignment" $policy1params = @{ displayName = $policy1Name description = $policy1Description allowedTargetScope = "notSpecified" specificAllowedTargets = @( ) expiration = @{ endDateTime = $null duration = $null type = "noExpiration" } requestorSettings = @{ enableTargetsToSelfAddAccess = $true enableTargetsToSelfUpdateAccess = $false enableTargetsToSelfRemoveAccess = $true allowCustomAssignmentSchedule = $true enableOnBehalfRequestorsToAddAccess = $false enableOnBehalfRequestorsToUpdateAccess = $false enableOnBehalfRequestorsToRemoveAccess = $false onBehalfRequestors = @( ) } requestApprovalSettings = @{ isApprovalRequiredForAdd = $false isApprovalRequiredForUpdate = $false stages = @( ) } accessPackage = @{ id = $accessPackageId } } $policy1Res = New-MgEntitlementManagementAssignmentPolicy -BodyParameter $policy1params $directAssignmentPolicyId = $policy1Res.Id
Configurar las restricciones en la separación de obligaciones
La administración de derechos de Microsoft Entra puede aplicar la separación de las comprobaciones de obligaciones para evitar que un usuario que ya tenga una asignación existente a otro paquete de acceso designado, o la pertenencia a un grupo designado, solicite un paquete de acceso.
Si no tiene requisitos de separación de obligaciones para esta aplicación, continúe con la sección siguiente.
Si tiene requisitos de separación de tareas, configure los paquetes de acceso no compatibles o los grupos existentes para el paquete de acceso.
Para cada paquete de acceso que se vaya a marcar como no compatible con otro, puede usar PowerShell para configurar los paquetes de acceso como no compatibles.
Especifique el otro paquete de acceso que no es compatible con este. Cambie el valor de
incompatibleAccessPackageId
por el id. de otro paquete de acceso en la administración de derechos de Microsoft Entra.$incompatibleAccessPackageId = "67cc7175-7a3d-4cb2-860f-4d9217ba96ca"
Cree la referencia no compatible en este paquete de acceso.
$incompatible1params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $incompatibleAccessPackageId } New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $accessPackageId -BodyParameter $incompatible1params
Cree la referencia no compatible en el otro paquete de acceso.
$incompatible2params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $accessPackageId } New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $incompatibleAccessPackageId -BodyParameter $incompatible2params
Repita el proceso para cualquier otro paquete de acceso.
Si su escenario requiere la capacidad de invalidar una separación de la comprobación de tareas, también puede configurar paquetes de acceso adicionales para esos escenarios de invalidación.
Agregar asignaciones de usuarios existentes que ya tengan acceso a la aplicación
Agregue asignaciones de usuarios existentes que ya tengan acceso a la aplicación, al paquete de acceso y a su directiva de asignación directa. Puede asignar directamente cada usuario a un paquete de acceso.
Recupere las asignaciones de roles de aplicación existentes.
$existingAppRoleAssignments = @(Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $servicePrincipalId -All)
Para evitar crear asignaciones duplicadas, recupera las asignaciones existentes en el paquete de acceso.
$existingAssignments1filter = "accessPackage/id eq '" + $accessPackageId + "' and state eq 'Delivered'" $existingassignments1 = @(Get-MgEntitlementManagementAssignment -Filter $existingAssignments1filter -ExpandProperty target -All -ErrorAction Stop) $existingusers1 = @() foreach ($a in $existingassignments1) { $existingusers1 += $a.Target.ObjectId}
Crea nuevas asignaciones.
foreach ($ar in $existingAppRoleAssignments) { if ($ar.principalType -ne "User") { write-warning "non-user assigned to application role" } $arpid = $ar.principalId if ($existingusers1.contains($arpId)) { continue } $params = @{ requestType = "adminAdd" assignment = @{ targetId = $arpId assignmentPolicyId = $directAssignmentPolicyId accessPackageId = $accessPackageId } } try { New-MgEntitlementManagementAssignmentRequest -BodyParameter $params } catch { write-error "cannot create request for user $upn" } }
Incorporación de asignaciones para los usuarios adicionales que deban tener acceso a la aplicación
Este script muestra el uso de los cmdlets de PowerShell de Microsoft Graph para agregar asignaciones para usuarios adicionales, de modo que tengan acceso a la aplicación. Si no tienes ningún usuario que necesite acceso y no lo recibiría automáticamente, continúa con la sección siguiente.
Este script supone que tienes un archivo CSV de entrada que contiene una columna, UserPrincipalName
, para asignar esos usuarios al paquete de acceso a través de su directiva de asignación directa.
Especifica el nombre del archivo de entrada.
$inputpath = "users.csv"
Para evitar crear asignaciones duplicadas, recupera las asignaciones existentes en el paquete de acceso.
$existingAssignments2filter = "accessPackage/id eq '" + $accessPackageId + "' and state eq 'Delivered'" $existingassignments2 = @(Get-MgEntitlementManagementAssignment -Filter $existingAssignments2filter -ExpandProperty target -All -ErrorAction Stop) $existingusers2 = @() foreach ($a in $existingassignments2) { $existingusers2 += $a.Target.ObjectId}
Crea nuevas asignaciones.
$users = import-csv -Path $inputpath foreach ($userrecord in $users) { $upn = $userrecord.UserPrincipalName if ($null -eq $upn) {throw "no UserPrincipalName" } $u = $null try { $u = Get-MgUser -UserId $upn } catch { write-error "no user $upn" } if ($u -eq $null) { continue } if ($existingusers2.contains($u.Id)) { continue } $params = @{ requestType = "adminAdd" assignment = @{ targetId = $u.Id assignmentPolicyId = $directAssignmentPolicyId accessPackageId = $accessPackageId } } try { New-MgEntitlementManagementAssignmentRequest -BodyParameter $params } catch { write-error "cannot create request for user $upn" } }
Agregar una directiva a los paquetes de acceso para la asignación automática
Si la directiva de tu organización para quién puede recibir acceso a una aplicación incluye una regla basada en los atributos del usuario para asignar y quitar el acceso automáticamente en función de esos atributos, puedes representarlo mediante una directiva de asignación automática. Un paquete de acceso puede tener como máximo una directiva de asignación automática. Si no tienes un requisito para una asignación automática, continúa con la sección siguiente.
Especifica la expresión de filtro de asignación automática para que los usuarios reciban una asignación. Cambia el valor de
autoAssignmentPolicyFilter
para que sea un filtro para los usuarios de Microsoft Entra ID que están en el ámbito. La sintaxis y los atributos permitidos se proporcionan en reglas de grupos de pertenencia dinámica en Microsoft Entra ID.$autoAssignmentPolicyFilter = '(user.city -eq "Redmond")'
Usa PowerShell para crear una directiva de asignación automática en el paquete de acceso.
$policy2Name = "Automatic assignment policy" $policy2Description = "policy for automatic assignment" $policy2Params = @{ DisplayName = $policy2Name Description = $policy2Description AllowedTargetScope = "specificDirectoryUsers" SpecificAllowedTargets = @( @{ "@odata.type" = "#microsoft.graph.attributeRuleMembers" description = $policy2Description membershipRule = $autoAssignmentPolicyFilter } ) AutomaticRequestSettings = @{ RequestAccessForAllowedTargets = $true } AccessPackage = @{ Id = $accessPackageId } } New-MgEntitlementManagementAssignmentPolicy -BodyParameter $policy2Params
Crear directivas adicionales para permitir que los usuarios soliciten acceso
Si los usuarios que aún no tienen acceso pueden solicitar ser asignados a la aplicación, también puedes configurar una directiva de asignación de paquetes de acceso para permitir a los usuarios solicitar un paquete de acceso. Puedes agregar directivas adicionales a un paquete de acceso y, en cada directiva, especificar qué usuarios pueden solicitar y quién debe aprobar. Si deseas que el acceso se asigne a los usuarios automáticamente o que lo asigne un administrador, continúa con la sección siguiente.
Para ver más ejemplos, consulta Creación de una directiva de asignación mediante PowerShell, accessPackageAssignmentPolicy y Crear una assignmentPolicy.
Especifica el nombre, la descripción de la directiva y el id. de un usuario de Microsoft Entra que será el aprobador.
$policy3Name = "example policy" $policy3Description = "example of a policy for users to request assignment" $policy3ApproverSingleUserId = "1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5"
Crea la directiva.
$policy3Params = @{ displayName = $policy3Name description = $policy3Description allowedTargetScope = "allMemberUsers" expiration = @{ type = "noExpiration" } requestorSettings = @{ enableTargetsToSelfAddAccess = "true" enableTargetsToSelfUpdateAccess = "true" enableTargetsToSelfRemoveAccess = "true" } requestApprovalSettings = @{ isApprovalRequiredForAdd = "true" isApprovalRequiredForUpdate = "true" stages = @( @{ durationBeforeAutomaticDenial = "P7D" isApproverJustificationRequired = "false" isEscalationEnabled = "false" fallbackPrimaryApprovers = @( ) escalationApprovers = @( ) fallbackEscalationApprovers = @( ) primaryApprovers = @( @{ "@odata.type" = "#microsoft.graph.singleUser" userId = $policy3ApproverSingleUserId } ) } ) } accessPackage = @{ id = $accessPackageId } } New-MgEntitlementManagementAssignmentPolicy -BodyParameter $policy3Params
Configurar tareas de flujos de trabajo del ciclo de vida
Si usas flujos de trabajo del ciclo de vida de Microsoft Entra para eventos de unión, movimiento y salida de empleados, también puedes agregar tareas a esos flujos de trabajo para agregar o quitar asignaciones a este paquete de acceso. Si no usas flujos de trabajo de ciclo de vida, continúa con la sección siguiente.
En este ejemplo se muestra cómo realizar un cambio en los flujos de trabajo de eventos de unión y salida.
Recupera el flujo de trabajo de la categoría
joiner
y sus tareas mediante el comando Get-MgIdentityGovernanceLifecycleWorkflow.Agrega una tarea a la lista de tareas de ese flujo de trabajo.
Nombre para mostrar de la tarea taskDefinitionId argumentos Solicitar asignación de paquete de acceso de usuario c1ec1e76-f374-4375-aaa6-0bb6bd4c60be
name: assignmentPolicyId
value: el id. de la directiva de asignación, como el valor de$directAssignmentPolicyId
si no se requiere ninguna aprobación, para el paquete de acceso que deseas asignar al usuario.
name:accessPackageId
value: el id. del paquete de acceso,$accessPackageId
, para el paquete de acceso que deseas asignar al usuario.Crea una nueva versión del flujo de trabajo, incluida la nueva tarea, mediante el comando New-MgIdentityGovernanceLifecycleWorkflowNewVersion.
Recupera el flujo de trabajo de la categoría
leaver
y sus tareas mediante el comando Get-MgIdentityGovernanceLifecycleWorkflow.Agrega una tarea a la lista de tareas de ese flujo de trabajo.
Nombre para mostrar de la tarea taskDefinitionId argumentos Eliminar la asignación de paquete de acceso para el usuario 4a0b64f2-c7ec-46ba-b117-18f262946c50
name: accessPackageId
value: un id. de paquete de acceso válido,accessPackageId
, para el paquete de acceso del que deseas anular la asignación al usuario.Crea una nueva versión del flujo de trabajo, incluida la nueva tarea, mediante el comando New-MgIdentityGovernanceLifecycleWorkflowNewVersion.
Administrar asignaciones
Una vez creados los paquetes de acceso, las directivas y las asignaciones iniciales, a los usuarios se les asigna acceso al rol de la aplicación.
Más adelante, puede supervisar los cambios en las asignaciones, o bien agregar o quitar asignaciones mediante programación.
Recuperar asignaciones existentes
Este script muestra el uso de un filtro para recuperar las asignaciones al paquete de acceso que están en estado Delivered
. El script genera un archivo CSV assignments.csv
con una lista de usuarios que tienen asignaciones, con una fila por asignación.
$assignmentFilter = "accessPackage/id eq '" + $accessPackageId + "' and state eq 'Delivered'"
$assignments = @(Get-MgEntitlementManagementAssignment -Filter $assignmentFilter -ExpandProperty target -All -ErrorAction Stop)
$sp = $assignments | select-object -Property Id,{$_.Target.id},{$_.Target.ObjectId},{$_.Target.DisplayName},{$_.Target.PrincipalName}
$sp | Export-Csv -Encoding UTF8 -NoTypeInformation -Path ".\assignments.csv"
Eliminar una asignación
Puede quitar la asignación de un usuario con el cmdlet New-MgEntitlementManagementAssignmentRequest
.
$userId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
$filter = "accessPackage/Id eq '" + $accessPackageId + "' and state eq 'Delivered' and target/objectId eq '" + $userId + "'"
$assignment = Get-MgEntitlementManagementAssignment -Filter $filter -ExpandProperty target -all -ErrorAction stop
if ($assignment -ne $null) {
$params = @{
requestType = "adminRemove"
assignment = @{ id = $assignment.id }
}
New-MgEntitlementManagementAssignmentRequest -BodyParameter $params
}