Azure PIM gebruiken om actieve toegang te beheren met de REST API

  • Artikel

Met Azure Privileged Identity Management (PIM) kunt u permanente beheerderstoegang beperken tot bevoorrechte rollen, ontdekken wie toegang heeft en bevoegde toegang controleren. In dit artikel worden de algemene manieren beschreven om toegang te beheren met behulp van de REST API.

Actieve toewijzingen weergeven

Als u actieve roltoewijzingen (lijsttoegang) wilt weergeven, kunt u een van de ROLtoewijzingsplanningsexemplaren - Lijst voor bereik of Roltoewijzingsschema's - Lijst voor bereik GEBRUIKEN. Als u de resultaten wilt verfijnen, geeft u een bereik en een optioneel filter op. Als u de API wilt aanroepen, moet u toegang hebben tot de Microsoft.Authorization/roleAssignments/read bewerking binnen het opgegeven bereik. Alle ingebouwde rollen krijgen toegang tot deze bewerking.

Belangrijk

Het verschil tussen planningen en planningsexemplaren is dat planningexemplaren alleen toewijzingen bevatten die op het huidige tijdstip actief zijn, maar planningen ook toewijzingen bevatten die in de toekomst actief worden.

  1. Begin met de volgende aanvraag:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleInstances?api-version=2020-10-01&$filter={filter}

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentSchedules?api-version=2020-10-01&$filter={filter}

  2. Vervang binnen de URI {scope} door het bereik waarvoor u de roltoewijzingen wilt weergeven.

    Bereik Type
    providers/Microsoft.Management/managementGroups/{mg-name} Beheergroep
    subscriptions/{subscriptionId} Abonnement
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resourcegroep
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Resource

  3. Vervang {filter} door de voorwaarde die u wilt toepassen om de lijst met roltoewijzingen te filteren.

    Filter Beschrijving
    $filter=atScope() Roltoewijzingen weergeven voor alleen het opgegeven bereik, exclusief de roltoewijzingen op subbereiken.
    $filter=principalId%20eq%20'{objectId}' Roltoewijzingen weergeven voor een opgegeven gebruiker, groep of service-principal.
    $filter=roleDefinitionId%20eq%20'{roleDefinitionId}' Roltoewijzingen weergeven voor een opgegeven roldefinitie.
    $filter=assignedTo('{objectId}') Roltoewijzingen weergeven voor een opgegeven gebruiker, inclusief de toewijzingen die zijn overgenomen van groepen.
    $filter=asTarget() Roltoewijzingen weergeven voor de huidige gebruiker of service-principal, inclusief de toewijzingen die zijn overgenomen van groepen.
    $filter=assignedTo('{objectId}')+and+atScope() Geef roltoewijzingen weer voor een opgegeven gebruiker, inclusief de toewijzingen die zijn overgenomen van groepen voor alleen het opgegeven bereik, met inbegrip van de roltoewijzingen op subbereiken.

Actieve toewijzing verlenen

Als u een actieve roltoewijzing wilt maken (toegang verlenen), gebruikt u de ROLtoewijzingsplanningsaanvragen - REST API maken en geeft u de beveiligingsprincipal, roldefinitie, planning, requestType = AdminAssign en bereik op. Als u deze API wilt aanroepen, moet u toegang hebben tot Microsoft.Authorization/roleAssignments/write de bewerking. Van de ingebouwde rollen krijgen alleen Eigenaar en Beheerder van gebruikerstoegang toegang tot deze bewerking.

  1. Gebruik de REST API Roldefinities - Lijst of zie Ingebouwde rollen om de id op te halen voor de roldefinitie die u wilt toewijzen.

  2. Gebruik een GUID-hulpprogramma om een unieke id te genereren die wordt gebruikt voor de roltoewijzings-id. De id heeft de volgende indeling: 00000000-0000-0000-0000-000000000000

  3. Begin met de volgende aanvraag en hoofdtekst:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

    {
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminAssign",
    "ScheduleInfo": {
      "StartDateTime": "2020-09-09T21:31:27.91Z",
      "Expiration": {
        "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
        "EndDateTime": null,
        "Duration": "P30D" // Use ISO 8601 format
      }
    }
  }
}

  4. Vervang binnen de URI {scope} door het bereik voor de roltoewijzing.

    Bereik Type
    providers/Microsoft.Management/managementGroups/{mg-name} Beheergroep
    subscriptions/{subscriptionId} Abonnement
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resourcegroep
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Resource

  5. Vervang {roleAssignmentScheduleRequestName} door de GUID-id van de roltoewijzing.

  6. Vervang {subscriptionId} in de aanvraagbody door uw abonnements-id.

  7. Vervang {roleDefinitionId} door de roldefinitie-id.

  8. Vervang {principalId} door de object-id van de gebruiker, groep of service-principal waaraan de rol wordt toegewezen.

Actieve toewijzing verwijderen

Als u een actieve roltoewijzing wilt verwijderen (toegang verwijderen), gebruikt u de ROLtoewijzingsplanningsaanvragen - REST API maken om een nieuwe aanvraag te maken om de toewijzing in te trekken en geeft u de beveiligingsprincipal, roldefinitie, requestType = AdminRemove en bereik op. Als u deze API wilt aanroepen, moet u toegang hebben tot de Microsoft.Authorization/roleAssignments/write bewerking. Van de ingebouwde rollen krijgen alleen Eigenaar en Beheerder van gebruikerstoegang toegang tot deze bewerking.

  1. Gebruik een GUID-hulpprogramma om een unieke id te genereren die wordt gebruikt voor de roltoewijzings-id. De id heeft de volgende indeling: 00000000-0000-0000-0000-000000000000

  2. Begin met de volgende aanvraag:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

    {
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminRemove"
    }
}

  3. Vervang binnen de URI {scope} door het bereik voor het verwijderen van de roltoewijzing.

    Bereik Type
    providers/Microsoft.Management/managementGroups/{mg-name} Beheergroep
    subscriptions/{subscriptionId} Abonnement
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resourcegroep
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

  4. Vervang {roleAssignmentScheduleRequestName} door de GUID-id van de roltoewijzing.

Een in aanmerking komende roltoewijzing activeren

Als u een in aanmerking komende roltoewijzing wilt activeren (geactiveerde toegang verkrijgen), gebruikt u de ROLtoewijzingsplanningsaanvragen - REST API maken om een nieuwe aanvraag te maken en de beveiligingsprincipal, roldefinitie, requestType = SelfActivate en bereik op te geven. Als u deze API wilt aanroepen, moet u een in aanmerking komende roltoewijzing voor het bereik hebben.

  1. Gebruik een GUID-hulpprogramma om een unieke id te genereren die wordt gebruikt voor de roltoewijzings-id. De id heeft de volgende indeling: 00000000-0000-0000-0000-000000000000

  2. [Optioneel] Kies een RoleEligibilitySchedule die u wilt activeren en haal de RoleEligibilityScheduleId op uit de API voor rol geschiktheidsschema's om door te geven als de LinkedRoleEligibilityScheduleId. Dit is optioneel en als dit niet wordt doorgegeven, kiest het systeem een RoleEligibilitySchedule.

  3. Begin met de volgende aanvraag:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

     {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfActivate",
     "ScheduleInfo": {
       "StartDateTime": "2020-09-09T21:31:27.91Z",
       "Expiration": {
         "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
         "EndDateTime": null,
         "Duration": "PT8H" // Use ISO 8601 format
       }
     },
     "LinkedRoleEligibilityScheduleId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignmentSchedules/{roleAssignmentScheduleId}" //Optional
   }
 }

  4. Vervang binnen de URI {scope} door het bereik voor het verwijderen van de roltoewijzing.

    Bereik Type
    providers/Microsoft.Management/managementGroups/{mg-name} Beheergroep
    subscriptions/{subscriptionId} Abonnement
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resourcegroep
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

  5. Vervang {roleAssignmentScheduleRequestName} door de GUID-id van de roltoewijzing.

Een actieve roltoewijzing deactiveren

Als u een geactiveerde roltoewijzing ongedaan wilt maken (geactiveerde toegang verwijderen), gebruikt u de REST API Roltoewijzingsplanningsaanvragen - Maken om een nieuwe aanvraag te maken en de beveiligingsprincipal, roldefinitie, requestType = SelfDeactivate en bereik op te geven. Als u deze API wilt aanroepen, moet u een geactiveerde roltoewijzing voor het bereik hebben.

  1. Gebruik een GUID-hulpprogramma om een unieke id te genereren die wordt gebruikt voor de roltoewijzings-id. De id heeft de volgende indeling: 00000000-0000-0000-0000-000000000000

  2. Begin met de volgende aanvraag:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

     {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfDeactivate"        
   }
 }

  3. Vervang binnen de URI {scope} door het bereik voor het verwijderen van de roltoewijzing.

    Bereik Type
    providers/Microsoft.Management/managementGroups/{mg-name} Beheergroep
    subscriptions/{subscriptionId} Abonnement
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resourcegroep
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

  4. Vervang {roleAssignmentScheduleRequestName} door de GUID-id van de roltoewijzing.

Just-Enough-Access (JEA)

Als een gebruiker een in aanmerking komende roltoewijzing heeft bij een resource (bovenliggend), kan deze ervoor kiezen om de rol te activeren op onderliggend niveau van de bovenliggende resource in plaats van het hele bovenliggende bereik. Als een gebruiker bijvoorbeeld een in aanmerking komende rol heeft Contributor in een abonnement, kan deze de rol activeren op het niveau van een onderliggende resourcegroep van het abonnement.

Als u een lijst wilt ophalen met alle onderliggende elementen van een resource waarvoor u in aanmerking komende toegang hebt, kunt u de API voor in aanmerking komende onderliggende resources gebruiken.

  1. Begin met de volgende aanvraag:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}

  2. Vervang binnen de URI {scope} door het bereik waarvoor u de roltoewijzingen wilt weergeven.

    Bereik Type
    providers/Microsoft.Management/managementGroups/{mg-name} Beheergroep
    subscriptions/{subscriptionId} Abonnement
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resourcegroep

  3. Vervang {filter} door de voorwaarde die u wilt toepassen om de lijst met roltoewijzingen te filteren.

    Filter Beschrijving
    $filter=resourceType+eq+'Subscription' Lijst met resources van het type = 'Abonnement'.
    $filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup'' Lijst met resources van het type = 'Abonnement' of type = 'ResourceGroup'.

  4. Gebruik de id van een onderliggende resource om te gebruiken als de scope voor de activering RoleAssignmentScheduleRequest

Veelvoorkomende fouten die worden geretourneerd voor een nieuwe aanvraag

Hieronder volgt een lijst met veelvoorkomende fouten die kunnen optreden tijdens het maken van een nieuwe aanvraag en hoe u deze kunt verhelpen.

Foutbericht Toelichting Oplossing
code: RoleAssignmentExists
message: de roltoewijzing bestaat al.		 Er bestaat al een vergelijkbare roltoewijzing U kunt GET deze roltoewijzing controleren en de planning controleren.
code: RoleAssignmentRequestPolicyValidationFailed
message: De volgende beleidsregels zijn mislukt: ["ExpirationRule"]		 De ScheduleInfo opgegeven in de aanvraag overschrijdt de maximaal toegestane duur U kunt GET hiervoor het RoleManagementPolicyRoleDefinitionId gebruiken en de RoleManagementPolicyExpirationRule
code: RoleAssignmentRequestPolicyValidationFailed
message: De volgende beleidsregels zijn mislukt: ["JustificationRule"]		 U moet een Justification opgeven in de hoofdtekst van de aanvraag U kunt GET hiervoor het RoleManagementPolicyRoleDefinitionId gebruiken en de RoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: De volgende beleidsregels zijn mislukt: ["EligibilityRule"]		 Er bestaat geen geldige RoleEligibilityScheduleInstance functie om deze rol te activeren Een resourcebeheerder moet een RoleEligibilityScheduleRequest maken voor deze principal
code: RoleAssignmentRequestPolicyValidationFailed
message: De volgende beleidsregels zijn mislukt: ["TicketingRule"]		 U moet een TicketInfo opgeven in de hoofdtekst van de aanvraag U kunt GET hiervoor het RoleManagementPolicyRoleDefinitionId gebruiken en de RoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: De volgende beleidsregels zijn mislukt: ["MfaRule"]		 U moet Azure Multi-Factor Authentication voltooien om deze aanvraag in te dienen U kunt GET hiervoor het RoleManagementPolicyRoleDefinitionId gebruiken en de RoleManagementPolicyEnablementRule