Condividi tramite

Usare Azure PIM per gestire l'accesso attivo con l'API REST

  • Articolo

Azure Privileged Identity Management (PIM) consente di limitare l'accesso di amministratore permanente ai ruoli con privilegi, individuare chi ha accesso ed esaminare l'accesso con privilegi. Questo articolo descrive i modi comuni per gestire l'accesso tramite l'API REST.

Elencare le assegnazioni attive

Per elencare le assegnazioni di ruolo attive (accesso elenco), è possibile usare una delle istanze di pianificazione dell'assegnazione di ruolo - Elenco per le pianificazioni dell'ambito o delle assegnazioni di ruolo - Elenco per le API REST di ambito. Per affinare i risultati, specificare un ambito e un filtro facoltativo. Per chiamare l'API, è necessario avere accesso all'operazione Microsoft.Authorization/roleAssignments/read nell'ambito specificato. A tutti i ruoli predefiniti viene concesso l'accesso a questa operazione.

Importante

La differenza tra le pianificazioni e le istanze di pianificazione è che, mentre le istanze di pianificazione includono solo assegnazioni attive all'ora corrente, le pianificazioni includono anche le assegnazioni che diventeranno attive in futuro.

  1. Iniziare con la richiesta seguente:

    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. All'intero dell'URI sostituire {scope} con l'ambito per il quale elencare le assegnazioni di ruolo.

    Scope Tipo
    providers/Microsoft.Management/managementGroups/{mg-name} Gruppo di gestione
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Risorsa

  3. Sostituire {filter} con la condizione da applicare per filtrare l'elenco delle assegnazioni di ruolo.

    Filtra Descrizione
    $filter=atScope() Elencare le assegnazioni di ruolo solo per l'ambito specificato, senza includere le assegnazioni di ruolo negli ambiti secondari.
    $filter=principalId%20eq%20'{objectId}' Elencare le assegnazioni di ruolo per un utente, un gruppo o un'entità servizio specificata.
    $filter=roleDefinitionId%20eq%20'{roleDefinitionId}' Elencare le assegnazioni di ruolo per una definizione di ruolo specificata.
    $filter=assignedTo('{objectId}') Elencare le assegnazioni di ruolo per un utente specificato, incluse quelle ereditate dai gruppi.
    $filter=asTarget() Elencare le assegnazioni di ruolo per l'utente corrente o l'entità servizio, inclusi quelli ereditati dai gruppi.
    $filter=assignedTo('{objectId}')+and+atScope() Elencare le assegnazioni di ruolo per un utente specificato, inclusi quelli ereditati dai gruppi solo per l'ambito specificato, senza includere le assegnazioni di ruolo nei ambiti secondari.

Concedere l'assegnazione attiva

Per creare un'assegnazione di ruolo attiva (concedere l'accesso), usare le richieste di pianificazione delle assegnazioni di ruolo - Creare l'API REST e specificare l'entità di sicurezza, la definizione del ruolo, la pianificazione, requestType = AdminAssign e l'ambito. Per chiamare questa API, è necessario avere accesso all'operazione Microsoft.Authorization/roleAssignments/write . Tra i ruoli predefiniti, l'accesso a questa operazione viene concesso soltanto ai ruoli Proprietario e Amministratore Accesso utenti.

  1. Usare l'API REST per l'elenco delle definizioni del ruolo o vedere Ruoli predefiniti per ottenere l'identificatore per la definizione del ruolo da assegnare.

  2. Usare uno strumento GUID per generare un identificatore univoco che verrà usato per l'identificatore dell'assegnazione di ruolo. Il formato dell'identificatore è: 00000000-0000-0000-0000-000000000000

  3. Iniziare con la richiesta e il corpo seguenti:

    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. All'interno dell'URI sostituire {scope} con l'ambito per l'assegnazione di ruolo.

    Scope Tipo
    providers/Microsoft.Management/managementGroups/{mg-name} Gruppo di gestione
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Risorsa

  5. Sostituire {roleAssignmentScheduleRequestName} con l'identificatore GUID dell'assegnazione di ruolo.

  6. All'interno del corpo della richiesta sostituire {subscriptionId} con l'identificatore della sottoscrizione.

  7. Sostituire {roleDefinitionId} con l'identificatore della definizione del ruolo.

  8. Sostituire {principalId} con l'identificatore di oggetto dell'utente, del gruppo o dell'entità servizio a cui verrà assegnato il ruolo.

Rimuovere l'assegnazione attiva

Per rimuovere un'assegnazione di ruolo attiva (rimuovere l'accesso), usare le richieste di pianificazione delle assegnazioni di ruolo - Creare un'API REST per creare una nuova richiesta per revocare l'assegnazione e specificare l'entità di sicurezza, la definizione del ruolo, requestType = AdminRemove e l'ambito. Per chiamare questa API, è necessario avere accesso all'operazione Microsoft.Authorization/roleAssignments/write. Tra i ruoli predefiniti, l'accesso a questa operazione viene concesso soltanto ai ruoli Proprietario e Amministratore Accesso utenti.

  1. Usare uno strumento GUID per generare un identificatore univoco che verrà usato per l'identificatore dell'assegnazione di ruolo. Il formato dell'identificatore è: 00000000-0000-0000-0000-000000000000

  2. Iniziare con la richiesta seguente:

    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. All'interno dell'URI sostituire {scope} con l'ambito per la rimozione dell'assegnazione di ruolo.

    Scope Tipo
    providers/Microsoft.Management/managementGroups/{mg-name} Gruppo di gestione
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Risorsa

  4. Sostituire {roleAssignmentScheduleRequestName} con l'identificatore GUID dell'assegnazione di ruolo.

Attivare un'assegnazione di ruolo idonea

Per attivare un'assegnazione di ruolo idonea (ottenere l'accesso attivato), usare le richieste di pianificazione delle assegnazioni di ruolo - Creare un'API REST per creare una nuova richiesta e specificare l'entità di sicurezza, la definizione del ruolo, requestType = SelfActivate e l'ambito. Per chiamare questa API, è necessario avere un'assegnazione di ruolo idonea nell'ambito.

  1. Usare uno strumento GUID per generare un identificatore univoco che verrà usato per l'identificatore dell'assegnazione di ruolo. Il formato dell'identificatore è: 00000000-0000-0000-0000-000000000000

  2. [Facoltativo] Scegliere un RoleEligibilitySchedule oggetto da attivare e ottenere dall'API RoleEligibilityScheduleIdPianificazioni ruolo da passare come LinkedRoleEligibilityScheduleId. Questa opzione è facoltativa e, se non viene passato, il sistema selezionerà un oggetto RoleEligibilitySchedule.

  3. Iniziare con la richiesta seguente:

    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. All'interno dell'URI sostituire {scope} con l'ambito per la rimozione dell'assegnazione di ruolo.

    Scope Tipo
    providers/Microsoft.Management/managementGroups/{mg-name} Gruppo di gestione
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Risorsa

  5. Sostituire {roleAssignmentScheduleRequestName} con l'identificatore GUID dell'assegnazione di ruolo.

Disattivare un'assegnazione di ruolo attiva

Per annullare l'attivazione di un'assegnazione di ruolo (rimuovere l'accesso attivato), usare le richieste di pianificazione delle assegnazioni di ruolo - Creare un'API REST per creare una nuova richiesta e specificare l'entità di sicurezza, la definizione del ruolo, requestType = SelfDeactivate e l'ambito. Per chiamare questa API, è necessario avere un'assegnazione di ruolo attivata nell'ambito.

  1. Usare uno strumento GUID per generare un identificatore univoco che verrà usato per l'identificatore dell'assegnazione di ruolo. Il formato dell'identificatore è: 00000000-0000-0000-0000-000000000000

  2. Iniziare con la richiesta seguente:

    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. All'interno dell'URI sostituire {scope} con l'ambito per la rimozione dell'assegnazione di ruolo.

    Scope Tipo
    providers/Microsoft.Management/managementGroups/{mg-name} Gruppo di gestione
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Risorsa

  4. Sostituire {roleAssignmentScheduleRequestName} con l'identificatore GUID dell'assegnazione di ruolo.

Just-Enough-Access (JEA)

Se un utente ha un'assegnazione di ruolo idonea in una risorsa (padre), può scegliere di attivare il ruolo a livello figlio della risorsa padre anziché l'intero ambito padre. Ad esempio, se un utente ha Contributor un ruolo idoneo in una sottoscrizione, può attivare il ruolo a livello di gruppo di risorse figlio della sottoscrizione.

Per ottenere un elenco di tutti gli elementi figlio di una risorsa in cui si ha accesso idoneo, è possibile usare l'API Risorse figlio idonee .

  1. Iniziare con la richiesta seguente:

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

  2. All'intero dell'URI sostituire {scope} con l'ambito per il quale elencare le assegnazioni di ruolo.

    Scope Tipo
    providers/Microsoft.Management/managementGroups/{mg-name} Gruppo di gestione
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group

  3. Sostituire {filter} con la condizione da applicare per filtrare l'elenco delle assegnazioni di ruolo.

    Filtra Descrizione
    $filter=resourceType+eq+'Subscription' Elencare le risorse di tipo = 'Sottoscrizione'.
    $filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup'' Elencare le risorse di tipo = 'Sottoscrizione' o tipo = 'ResourceGroup'.

  4. Usare l'oggetto id di qualsiasi risorsa figlio da usare come scope per l'attivazione RoleAssignmentScheduleRequest

Errori comuni restituiti per una nuova richiesta

Di seguito è riportato un elenco di errori comuni che potrebbero verificarsi durante la creazione di una nuova richiesta e come attenuarli.

Messaggio di errore Explanantion Strategia di riduzione del rischio
code: RoleAssignmentExists
message: l'assegnazione di ruolo esiste già.		 Esiste già un'assegnazione di ruolo simile È possibile GET eseguire questa assegnazione di ruolo e verificare la pianificazione.
code: RoleAssignmentRequestPolicyValidationFailed
message: le regole dei criteri seguenti non sono riuscite: ["ExpirationRule"]		 L'oggetto ScheduleInfo specificato nella richiesta supera la durata massima consentita Per questa RoleDefinitionId operazione è possibile GET selezionare RoleManagementPolicyRoleManagementPolicyExpirationRule
code: RoleAssignmentRequestPolicyValidationFailed
message: le regole dei criteri seguenti non sono riuscite: ["JustificationRule"]		 È necessario specificare un Justification oggetto nel corpo della richiesta Per questa RoleDefinitionId operazione è possibile GET selezionare RoleManagementPolicyRoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: le regole dei criteri seguenti non sono riuscite: ["IdoneitàRule"]		 Un valore valido RoleEligibilityScheduleInstance non esiste per attivare questo ruolo Un amministratore di risorse deve creare un RoleEligibilityScheduleRequest oggetto per questa entità
code: RoleAssignmentRequestPolicyValidationFailed
message: le regole dei criteri seguenti non sono riuscite: ["TicketingRule"]		 È necessario specificare un TicketInfo oggetto nel corpo della richiesta Per questa RoleDefinitionId operazione è possibile GET selezionare RoleManagementPolicyRoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: le regole dei criteri seguenti non sono riuscite: ["MfaRule"]		 È necessario completare Azure Multi-Factor Authentication per inviare questa richiesta Per questa RoleDefinitionId operazione è possibile GET selezionare RoleManagementPolicyRoleManagementPolicyEnablementRule