Informazioni sulle API di Privileged Identity Management

È possibile eseguire attività Privileged Identity Management (PIM) usando le API di Microsoft Graph per i ruoli Azure Active Directory (Azure AD) e l'API azure Resource Manager per i ruoli di Azure. Questo articolo descrive concetti importanti per l'uso delle API per Privileged Identity Management.

Per le richieste e altri dettagli sulle API PIM, vedere:

Cronologia API PIM

Ci sono state diverse iterazioni dell'API PIM negli ultimi anni. Sono disponibili alcune sovrapposizioni nelle funzionalità, ma non rappresentano una progressione lineare delle versioni.

Iterazione 1 - Deprecato

Nell'endpoint /beta/privilegedRoles Microsoft aveva una versione classica dell'API PIM che supportava solo i ruoli di Azure AD e non è più supportata. L'accesso a questa API è stato deprecato nel giugno 2021.

Iterazione 2: supporta i ruoli di Azure AD e i ruoli delle risorse di Azure

Nell'endpoint /beta/privilegedAccess Microsoft è supportato sia /aadRoles che /azureResources. Questo endpoint è ancora disponibile nel tenant, ma Microsoft consiglia di avviare qualsiasi nuovo sviluppo con questa API. Questa API beta non verrà mai rilasciata alla disponibilità generale e verrà successivamente deprecata.

Iterazione corrente: ruoli di Azure AD in Microsoft Graph e ruoli delle risorse di Azure in Azure Resource Manager

Attualmente in disponibilità generale, questa è l'iterazione finale dell'API PIM. In base al feedback dei clienti, l'API PIM per la gestione dei ruoli di Azure AD è ora sotto il set unifiedRoleManagement di API e l'API PIM di Risorse di Azure è ora sotto l'API di assegnazione dei ruoli di Azure Resource Manager. Queste posizioni offrono anche alcuni vantaggi aggiuntivi, tra cui:

  • Allineamento dell'API PIM per l'API di assegnazione di ruolo regolare per i ruoli di Azure AD e i ruoli delle risorse di Azure.
  • Riduzione della necessità di chiamare un'API PIM aggiuntiva per eseguire l'onboarding di una risorsa, ottenere una risorsa o ottenere la definizione del ruolo.
  • Supporto delle autorizzazioni solo app.
  • Nuove funzionalità, ad esempio l'approvazione e la configurazione della notifica tramite posta elettronica.

Nell'iterazione corrente non è disponibile alcun supporto API per gli avvisi PIM e i gruppi di accesso con privilegi.

Autorizzazioni correnti necessarie

Ruoli di Azure AD

Per comprendere le autorizzazioni necessarie per chiamare pim Microsoft API Graph per i ruoli di Azure AD, vedere Autorizzazioni di gestione dei ruoli.

Il modo più semplice per specificare le autorizzazioni richieste consiste nell'usare il framework di consenso di Azure AD.

Ruoli delle risorse di Azure

L'API PIM per i ruoli delle risorse di Azure viene sviluppata nel framework di Azure Resource Manager. Sarà necessario concedere il consenso a Gestione risorse di Azure, ma non sarà necessaria alcuna autorizzazione di Microsoft API Graph. È anche necessario assicurarsi che l'utente o l'entità servizio che chiama l'API abbia almeno il ruolo Proprietario o Amministratore accesso utente nella risorsa che si sta tentando di amministrare.

Chiamata dell'API PIM con un token solo app

Ruoli di Azure AD

L'API PIM supporta ora le autorizzazioni solo app per le autorizzazioni delegate.

  • Per le autorizzazioni solo per l'app, è necessario chiamare l'API con un'applicazione già consentita con le autorizzazioni di ruolo di Azure AD o azure necessarie.
  • Per l'autorizzazione delegata, è necessario chiamare l'API PIM con un utente e un token dell'applicazione. L'utente deve essere assegnato al ruolo Amministratore globale o amministratore ruolo con privilegi e assicurarsi che l'entità servizio che chiama l'API abbia almeno il ruolo Proprietario o Amministratore accesso utente nella risorsa che si sta tentando di amministrare.

Ruoli delle risorse di Azure

L'API PIM per le risorse di Azure supporta solo le chiamate utente e dell'applicazione. Assicurarsi semplicemente che l'entità servizio abbia il ruolo amministratore di accesso utente o proprietario nella risorsa.

Progettazione dell'iterazione dell'API corrente

L'API PIM è costituita da due categorie coerenti sia per l'API per i ruoli di Azure AD che per i ruoli delle risorse di Azure: assegnazione e richieste API di attivazione e impostazioni dei criteri.

API di assegnazione e attivazione

Per rendere idonee le assegnazioni, le assegnazioni idonee o attive associate a tempo e per attivare le assegnazioni idonee, PIM fornisce le risorse seguenti:

Queste entità funzionano insieme alle risorse roleDefinition e roleAssignment preesistenti per i ruoli di Azure AD e i ruoli di Azure per consentire di creare scenari end-to-end.

  • Se si sta tentando di creare o recuperare un'assegnazione di ruolo persistente (attiva) che non ha un pianificare (ora di inizio o di fine), è consigliabile evitare queste entità PIM e concentrarsi sulle operazioni di lettura/scrittura nell'entità roleAssignment

  • Per creare un'assegnazione idonea con o senza scadenza, è possibile usare l'operazione di scrittura nella risorsa unifiedRoleEligibilityScheduleRequest

  • Per creare un'assegnazione persistente (attiva) con una pianificare (ora di inizio o di fine), è possibile usare l'operazione di scrittura nella risorsa unifiedRoleAssignmentScheduleRequest

  • Per attivare un'assegnazione idonea, è necessario usare anche l'operazione di scrittura nel ruoloAssignmentScheduleRequest con una selfActivate proprietà action.

Ognuno degli oggetti richiesta crea gli oggetti di sola lettura seguenti:

Gli oggetti unifiedRoleAssignmentSchedule e unifiedRoleEligibilitySchedule mostrano un pianificare di tutte le assegnazioni correnti e future.

Quando viene attivata un'assegnazione idonea, l'unifiedRoleEligibilityScheduleInstance continua a esistere. UnifiedRoleAssignmentScheduleRequest per l'attivazione creerebbe un oggetto unifiedRoleAssignmentSchedule e un unifiedRoleAssignmentScheduleInstance per tale durata attivata.

Gli oggetti dell'istanza sono le assegnazioni effettive attualmente esistenti se si tratta di un'assegnazione idonea o di un'assegnazione attiva. È consigliabile usare l'operazione GET nell'entità dell'istanza per recuperare un elenco di assegnazioni idonee/assegnazioni attive a un ruolo/utente.

Per altre informazioni sull'assegnazione e sulle API di attivazione, vedere API PIM per la gestione delle assegnazioni e delle idoneità dei ruoli.

API delle impostazioni dei criteri

Per gestire le impostazioni dei ruoli di Azure AD, sono disponibili le entità seguenti:

La risorsa unifiedroleManagementPolicy tramite la relazione regole definisce le regole o le impostazioni del ruolo Azure AD. Ad esempio, se è necessaria l'autenticazione a più fattori o l'approvazione, se e chi inviare le notifiche tramite posta elettronica o se le assegnazioni permanenti sono consentite o meno. L'oggetto unifiedroleManagementPolicyAssignment associa i criteri a un ruolo specifico.

Usare le API supportate da queste risorse recuperano le assegnazioni di criteri di gestione dei ruoli per tutti i ruoli di Azure AD o filtrano l'elenco da un roleDefinitionId e quindi aggiornano le regole o le impostazioni nei criteri associati al ruolo di Azure AD.

Per altre informazioni sulle API delle impostazioni dei criteri, vedere Impostazioni del ruolo e PIM.

Relazione tra entità PIM e entità di assegnazione di ruolo

L'unico collegamento tra l'entità PIM e l'entità di assegnazione del ruolo per l'assegnazione persistente (attiva) per i ruoli di Azure AD o i ruoli di Azure è unifiedRoleAssignmentScheduleInstance. Esiste un mapping uno-a-uno tra le due entità. Tale mapping significa che roleAssignment e unifiedRoleAssignmentScheduleInstance includerebbero entrambi:

  • Assegnazioni persistenti (attive) effettuate all'esterno di PIM
  • Assegnazioni persistenti (attive) con un pianificare effettuato all'interno di PIM
  • Assegnazioni idonee attivate

Passaggi successivi