Skapa ett åtkomstpaket i berättigandehantering för ett program med en enda roll med hjälp av PowerShell
I Microsoft Entra-berättigandehantering omfattar ett åtkomstpaket principerna för hur användare kan hämta tilldelningar för en eller flera resursroller. Resurserna kan innehålla grupper, program och SharePoint Online-webbplatser.
Den här artikeln beskriver hur du skapar ett åtkomstpaket för ett enda program med en enda roll med hjälp av Microsoft Graph PowerShell. Det här scenariot gäller främst för miljöer som använder berättigandehantering för att automatisera pågående åtkomst för ett specifikt affärs- eller mellanprogramsprogram. En organisation som har flera resurser eller resurser med flera roller kan också modellera sina åtkomstprinciper med åtkomstpaket:
- Om organisationen redan har en befintlig organisationsrollmodell för sina affärsroller kan de migrera den modellen till Microsoft Entra ID Governance och styra åtkomsten med en organisationsrollmodell.
- Om organisationen har program med flera roller kan de distribuera organisationsprinciper för att styra åtkomsten till program som är integrerade med Microsoft Entra-ID
- Mer information om hur du skapar åtkomstpaket för andra scenarier finns i självstudie: Hantera åtkomst till resurser i berättigandehantering och hur du skapar ett åtkomstpaket i berättigandehantering.
Förutsättningar
För att kunna använda den här funktionen krävs Microsoft Entra ID-styrning eller Microsoft Entra Suite-licenser. Information om hur du hittar rätt licens för dina krav finns i Grunderna för Microsoft Entra ID-styrningslicensiering.
Innan du börjar skapa åtkomstpaketet måste du integrera programmet med Microsoft Entra-ID. Om ditt program inte redan finns i din Microsoft Entra-ID-klient följer du anvisningarna i den artikeln för att skapa ett program och tjänstens huvudnamn för objektet. Se också till att din Microsoft Entra-ID-klientorganisation har uppfyllt kraven innan du konfigurerar Microsoft Entra-ID för identitetsstyrning.
Om du vill skapa åtkomstpaketet och dess associerade principer och tilldelningar måste du ha följande information klar:
Användningsfall | Konfigurationsuppsättning | PowerShell-variabel |
---|---|---|
Alla | Namnet på programmet i din Microsoft Entra ID-klientorganisation | $servicePrincipalName |
Alla | Namnet på programmets roll | $servicePrincipalRoleName |
Alla | Namnet på katalogen som innehåller åtkomstpaketet | $catalogName |
Alla | Namn för att ge åtkomstpaketet | $accessPackageName |
Alla | Beskrivning för att ge åtkomstpaketet | $accessPackageDescription |
Krav på ansvarsfördelning med ett inkompatibelt åtkomstpaket | ID för det inkompatibla åtkomstpaketet | $incompatibleAccessPackageId (om det behövs) |
Användare som inte redan har tilldelningar och inte tilldelas automatiskt | lista över användare | $inputpath (om det behövs) |
Användare med specifika attribut har automatiskt tilldelningar | frågeuttrycket för användarna i omfånget | $autoAssignmentPolicyFilter (om det behövs) |
Tillåt användare som inte har någon tilldelning att begära en tilldelning | omfånget för användare som kan begära, godkännarna och åtkomstgranskningsperioden | beror på kraven |
Automatisera skapande eller borttagning av tilldelningar baserat på koppling eller lämna arbetsflöden i livscykelarbetsflöden | namnen på de arbetsflöden som ger och tar bort åtkomst | beror på kraven |
Autentisera till Microsoft Entra-ID
Det här avsnittet visar hur du interagerar med Microsoft Entra ID-styrning med hjälp av Microsoft Graph PowerShell-cmdletar .
Första gången din organisation använder dessa cmdletar för det här scenariot måste du ha en global administratörsroll så att Microsoft Graph PowerShell kan användas i din klientorganisation. Efterföljande interaktioner kan använda en lägre privilegierad roll, till exempel:
Öppna PowerShell.
Om du inte redan har installerat Microsoft Graph PowerShell-modulerna installerar du modulen
Microsoft.Graph.Identity.Governance
och andra med hjälp av det här kommandot:Install-Module Microsoft.Graph
Om du redan har installerat modulerna kontrollerar du att du använder en ny version:
Update-Module microsoft.graph.users,microsoft.graph.identity.governance,microsoft.graph.applications
Anslut till Microsoft Entra ID:
$msg = Connect-MgGraph -ContextScope Process -Scopes "User.ReadWrite.All,Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All,EntitlementManagement.ReadWrite.All"
Om det är första gången du använder det här kommandot kan du behöva godkänna att Microsoft Graph-kommandoradsverktygen har dessa behörigheter.
Skapa en katalog i Microsoft Entra-berättigandehantering
När en administratör först interagerar med berättigandehantering skapas som standard en standardkatalog automatiskt. Åtkomstpaket för reglerade program bör dock finnas i en angiven katalog.
Ange namnet på katalogen.
$catalogName = "Business applications"
Om du redan har en katalog för ditt programstyrningsscenario fortsätter du i steg 4 i det här avsnittet.
Om du inte redan har en katalog för ditt programstyrningsscenario skapar du en katalog.
$catalog = New-MgEntitlementManagementCatalog -DisplayName $catalogName
Leta upp katalogens ID.
$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
Lägg till programmet som en resurs i katalogen
När katalogen har skapats lägger du till programmet som en resurs i katalogen.
Ange namnet på programmet och namnet på programrollen. Använd namnet på ditt program som värdet för
servicePrincipalName
.$servicePrincipalName = "SAP Cloud Identity Services" $servicePrincipalRoleName = "User"
Leta upp ID:t för programtjänstens huvudnamn.
$servicePrincipalFilter = "displayName eq '" + $applicationName + "'" $servicePrincipal = Get-MgServicePrincipal -Filter $servicePrincipalFilter -all if ($servicePrincipal -eq $null) { throw "service principal $servicePrincipalName not found" } $servicePrincipalId = $servicePrincipal.Id
Kontrollera om programmet redan finns i katalogen som en resurs. Om den redan finns fortsätter du i steg 6 i det här avsnittet.
$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"}
Lägg till programmets tjänsthuvudnamn som en resurs i katalogen.
$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
Hämta ID:t och resursens omfång i katalogen.
$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" }
Hämta programmets roller.
$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" }
Välj den roll som ska ingå i åtkomstpaketet.
$resourceRole = $null foreach ($r in $resourceRoles) { if ($r.DisplayName -eq $servicePrincipalRoleName) { $resourceRole = $r; break; } } if ($resourceRole -eq $null) { throw "role $servicePrincipalRoleName not located" }
Skapa åtkomstpaketet för programmet
Sedan använder du PowerShell för att skapa ett åtkomstpaket i en katalog som innehåller programmets roll.
Ange namnet och beskrivningen av åtkomstpaketet.
$accessPackageName = "SAP Cloud Identity Services" $accessPackageDescription = "A user of SAP Cloud Identity Services" $accessPackageHidden = $true
Kontrollera att åtkomstpaketet inte redan finns.
foreach ($a in $catalog.AccessPackages) { if ($a.DisplayName -eq $accessPackageName) { throw "access package $accessPackageName already exists" } }
Skapa åtkomstpaketet.
$accessPackageParams = @{ displayName = $accessPackageName description = $accessPackageDescription isHidden = $accessPackageHidden catalog = @{ id = $catalog.id } } $accessPackage = New-MgEntitlementManagementAccessPackage -BodyParameter $accessPackageParams $accessPackageId = $accessPackage.Id
Lägg till programrollen i åtkomstpaketet
När du har skapat ett åtkomstpaket länkar du resursens roll i katalogen till åtkomstpaketet.
$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
Skapa tilldelningsprinciper för åtkomstpaket för direkttilldelning
I det här avsnittet skapar du den första principen för tilldelning av åtkomstpaket i åtkomstpaketet, en tilldelningsprincip för åtkomstpaket för direkttilldelning, som kan användas för att spåra de användare som redan har åtkomst till programmet. I exempelprincipen som skapas i det här avsnittet kan endast administratörer eller åtkomstpakettilldelningshanterare tilldela åtkomst, användare behåller åtkomsten på obestämd tid och det finns inga godkännanden eller åtkomstgranskningar.
Skapa en princip.
$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
Konfigurera begränsningar för uppdelning av uppgifter
Microsoft Entra-rättighetshantering kan framtvinga ansvarskontroller för att förhindra att en användare som redan har en befintlig tilldelning till ett annat särskilt åtkomstpaket, eller medlemskap i en utsedd grupp, begär ett åtkomstpaket.
Om du inte har ansvarsfördelningskrav för det här programmet fortsätter du i nästa avsnitt.
Om du har ansvarsfördelningskrav konfigurerar du de inkompatibla åtkomstpaketen eller befintliga grupper för ditt åtkomstpaket.
För varje åtkomstpaket som ska markeras som inkompatibelt med ett annat kan du använda en PowerShell-konfiguration av åtkomstpaket som inkompatibla.
Ange det andra åtkomstpaketet som är inkompatibelt med det här. Ändra värdet
incompatibleAccessPackageId
för till ID för ett annat åtkomstpaket i Microsoft Entra-berättigandehantering.$incompatibleAccessPackageId = "67cc7175-7a3d-4cb2-860f-4d9217ba96ca"
Skapa den inkompatibla referensen för det här åtkomstpaketet.
$incompatible1params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $incompatibleAccessPackageId } New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $accessPackageId -BodyParameter $incompatible1params
Skapa den inkompatibla referensen för det andra åtkomstpaketet.
$incompatible2params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/" + $accessPackageId } New-MgEntitlementManagementAccessPackageIncompatibleAccessPackageByRef -AccessPackageId $incompatibleAccessPackageId -BodyParameter $incompatible2params
Upprepa för andra åtkomstpaket.
Om ditt scenario kräver möjligheten att åsidosätta en ansvarsavgränsningskontroll kan du även konfigurera ytterligare åtkomstpaket för dessa åsidosättningsscenarier.
Lägga till tilldelningar av befintliga användare som redan har åtkomst till programmet
Lägg till tilldelningar av befintliga användare, som redan har åtkomst till programmet, till åtkomstpaketet och dess direkttilldelningsprincip. Du kan tilldela varje användare direkt till ett åtkomstpaket.
Hämta de befintliga programrolltilldelningarna.
$existingAppRoleAssignments = @(Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $servicePrincipalId -All)
Om du vill undvika att skapa duplicerade tilldelningar hämtar du eventuella befintliga tilldelningar till åtkomstpaketet.
$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}
Skapa nya tilldelningar.
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" } }
Lägga till tilldelningar för ytterligare användare som ska ha åtkomst till programmet
Det här skriptet visar hur du använder Microsoft Graph PowerShell-cmdletar för att lägga till tilldelningar för ytterligare användare så att de får åtkomst till programmet. Om du inte har några användare som behöver åtkomst och inte tar emot den automatiskt fortsätter du i nästa avsnitt.
Det här skriptet förutsätter att du har en CSV-indatafil som innehåller en kolumn, UserPrincipalName
, för att tilldela dessa användare till åtkomstpaketet via dess direkttilldelningsprincip.
Ange namnet på indatafilen.
$inputpath = "users.csv"
Om du vill undvika att skapa duplicerade tilldelningar hämtar du eventuella befintliga tilldelningar till åtkomstpaketet.
$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}
Skapa nya tilldelningar.
$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" } }
Lägga till en princip i åtkomstpaketen för automatisk tilldelning
Om organisationens princip för vem som kan tilldelas åtkomst till ett program innehåller en regel som baseras på användarens attribut för att tilldela och ta bort åtkomst automatiskt baserat på dessa attribut, kan du representera detta med hjälp av en automatisk tilldelningsprincip. Ett åtkomstpaket kan ha högst en automatisk tilldelningsprincip. Om du inte har något krav på en automatisk tilldelning fortsätter du i nästa avsnitt.
Ange det automatiska tilldelningsfilteruttrycket för användare som ska ta emot en tilldelning. Ändra värdet
autoAssignmentPolicyFilter
för så att det är ett filter för användarna i ditt Microsoft Entra-ID som finns i omfånget. Syntaxen och de tillåtna attributen finns i regler för dynamiska medlemskapsgrupper i Microsoft Entra-ID.$autoAssignmentPolicyFilter = '(user.city -eq "Redmond")'
Använd PowerShell för att skapa en automatisk tilldelningsprincip i åtkomstpaketet.
$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
Skapa ytterligare principer för att tillåta användare att begära åtkomst
Om användare som inte redan har åtkomst tillåts begära att tilldelas till programmet kan du även konfigurera en tilldelningsprincip för åtkomstpaket så att användarna kan begära ett åtkomstpaket. Du kan lägga till ytterligare principer i ett åtkomstpaket och i varje princip anger du vilka användare som kan begära och vem som måste godkänna. Om du bara vill att användare ska tilldelas åtkomst automatiskt eller av en administratör fortsätter du i nästa avsnitt.
Fler exempel finns i Skapa en tilldelningsprincip via PowerShell, accessPackageAssignmentPolicy och Skapa en tilldelningPolicy.
Ange namn, beskrivning av principen och ID för en Microsoft Entra-användare som ska godkänna.
$policy3Name = "example policy" $policy3Description = "example of a policy for users to request assignment" $policy3ApproverSingleUserId = "1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5"
Skapa principen.
$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
Konfigurera uppgifter för livscykelarbetsflöden
Om du använder Microsoft Entra-livscykelarbetsflöden för medarbetaranslutning , flyttar ledighetshändelser, kan du också lägga till uppgifter i dessa arbetsflöden för att lägga till eller ta bort tilldelningar i det här åtkomstpaketet. Om du inte använder livscykelarbetsflöden fortsätter du i nästa avsnitt.
Det här exemplet illustrerar hur du gör en ändring i arbetsflödena för att ansluta till och lämna händelsen.
joiner
Hämta kategoriarbetsflödet och dess uppgifter med hjälp av kommandot Get-MgIdentityGovernanceLifecycleWorkflow.Lägg till en uppgift i en lista över aktiviteter i arbetsflödet.
Uppgiftsvisningsnamn taskDefinitionId Argument Begära tilldelning av användaråtkomstpaket c1ec1e76-f374-4375-aaa6-0bb6bd4c60be
namn: assignmentPolicyId
värde: Tilldelningsprincipens ID, till exempel värdet från$directAssignmentPolicyId
om inget godkännande krävs, för det åtkomstpaket som du vill tilldela användaren.
namn:accessPackageId
värde: Åtkomstpakets-ID,$accessPackageId
, för det åtkomstpaket som du vill tilldela användaren.Skapa en ny version av arbetsflödet, inklusive den nya uppgiften, med kommandot New-MgIdentityGovernanceLifecycleWorkflowNewVersion .
leaver
Hämta kategoriarbetsflödet och dess uppgifter med hjälp av kommandot Get-MgIdentityGovernanceLifecycleWorkflow.Lägg till en uppgift i en lista över aktiviteter i arbetsflödet.
Uppgiftsvisningsnamn taskDefinitionId Argument Ta bort tilldelning av åtkomstpaket för användare 4a0b64f2-c7ec-46ba-b117-18f262946c50
namn: accessPackageId
värde: Ett giltigt åtkomstpaket-IDaccessPackageId
för det åtkomstpaket som du vill avtilldela från användaren.Skapa en ny version av arbetsflödet, inklusive den nya uppgiften, med kommandot New-MgIdentityGovernanceLifecycleWorkflowNewVersion .
Hantera tilldelningar
När åtkomstpaketen, principerna och de första tilldelningarna har skapats tilldelas användarna åtkomst till programmets roll.
Senare kan du övervaka ändringar i tilldelningarna eller programmatiskt lägga till eller ta bort tilldelningar.
Hämta befintliga tilldelningar
Det här skriptet illustrerar hur du använder ett filter för att hämta tilldelningarna till åtkomstpaketet som är i tillståndet Delivered
. Skriptet genererar en CSV-fil assignments.csv
med en lista över användare som har tilldelningar, med en rad per tilldelning.
$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"
Ta bort en tilldelning
Du kan ta bort en användares tilldelning med cmdleten 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
}