Autenticazione e autorizzazione per l'API Exchange Online Amministrazione

Nota

Le funzionalità descritte in questo articolo sono attualmente disponibili in anteprima, non sono disponibili in tutte le organizzazioni e sono soggette a modifiche.

Questo articolo illustra i requisiti di autenticazione e autorizzazione per l'uso degli endpoint per l'API Exchange Online Amministrazione.

L'API Exchange Online Amministrazione offre un modo basato su REST per eseguire cmdlet di PowerShell specifici, sostituendo scenari legacy di Exchange Web Services (EWS). Per altre informazioni, vedere Panoramica dell'API Exchange Online Amministrazione.

Per accedere all'API Amministrazione, l'app deve stabilire la propria identità, ottenere le autorizzazioni corrette e seguire le procedure consigliate per la gestione sicura dei token. A livello generale, il processo prevede i passaggi chiave seguenti:

Registrare un'app in Microsoft Entra ID

Creare una registrazione dell'app per stabilire un'identità per l'app e configurare le credenziali (segreto client o certificato). Questa registrazione consente all'app di richiedere token da Microsoft Entra ID.
Assegnare le autorizzazioni API necessarie

Aggiungere gli ambiti OAuth necessari alla registrazione dell'app:
- Flusso delegato: Exchange.ManageV2.
- Flusso solo app: Exchange.ManageAsAppV2.
Passaggio 3: Assegnare autorizzazioni di controllo degli accessi in base al ruolo

Exchange Online usa il controllo degli accessi in base al ruolo per determinare quali endpoint, cmdlet e oggetti possono essere gestiti dal chiamante. Assegnare i ruoli del controllo degli accessi in base al ruolo appropriati all'utente (per l'accesso delegato) o all'entità servizio dell'app (per l'accesso solo app).
Passaggio 4: Ottenere un token di accesso

Usare i flussi OAuth 2.0 per acquisire token da Microsoft Entra ID:
- Flusso delegato per l'accesso basato sull'utente.
- Flusso solo app per l'accesso da servizio a servizio.
Passaggio 5: Usare il token di accesso

Passaggio 1: Registrare un'app in Microsoft Entra ID

Per chiamare l'API Exchange Online Amministrazione, devi prima registrare l'app in Microsoft Entra ID. Un'app è simile a un oggetto classe. Un'entità servizio è simile a un'istanza della classe . Per altre informazioni, vedere Oggetti applicazione e entità servizio in Microsoft Entra ID. Per un flusso visivo dettagliato sulla creazione di applicazioni in Microsoft Entra ID, vedere https://aka.ms/azuread-app.

Aprire il Interfaccia di amministrazione di Microsoft Entra all'indirizzo https://entra.microsoft.com.
Nella casella di ricerca nella parte superiore della pagina immettere Registrazioni app e selezionarla dai risultati.
Nella pagina Registrazioni app selezionare Nuova registrazione.
Nella pagina Registra un'applicazione configurare le impostazioni dell'applicazione:
- Nome: immettere un nome descrittivo, ad esempio Exchange Amministrazione CLIENT API.
- Tipi di account supportati: selezionare uno dei valori seguenti:
  - App a organizzazione singola: selezionare Account solo in questa directory organizzativa.
  - Scenari delegati multi-tenant: selezionare Account in qualsiasi directory organizzativa.
- URI di reindirizzamento (facoltativo): obbligatorio per il flusso delegato.
  - Piattaforma: selezionare Web.
  - URI: immettere l'URL in cui viene inviato il token di accesso, https://localhost ad esempio per il test.
Al termine, nella pagina Registra un'applicazione selezionare Registra.

Viene visualizzata la pagina Panoramica dell'app registrata. Rimanere nella pagina per il passaggio successivo.

Nota

Non è possibile creare credenziali per le applicazioni native perché non possono essere usate per chiamate automatizzate da servizio a servizio.

Passaggio 2: Assegnare le autorizzazioni API necessarie

Nella pagina Panoramica dell'app creata nel passaggio precedente selezionare Autorizzazioni API nella sezione Gestione .
Nella pagina Autorizzazioni API per l'app selezionare Aggiungi un'autorizzazione.
Nel riquadro a comparsa Richiedi autorizzazioni API visualizzato selezionare la scheda API usate dall'organizzazione, immettere Office 365 Exchange Online nella casella di ricerca e quindi selezionarla dai risultati.
Nel riquadro a comparsa Quale tipo di autorizzazioni richiede l'applicazione? effettuare una delle selezioni seguenti:
- Flusso solo app: selezionare Autorizzazioni applicazione, espandere Exchange, selezionare Exchange.ManageAsAppV2 e quindi selezionare Aggiungi autorizzazioni.
- Flusso delegato: selezionare Autorizzazioni delegate, espandere Exchange, selezionare Exchange.ManageV2 e quindi selezionare Aggiungi autorizzazioni.
Tornare alla pagina autorizzazioni API , verificare che le selezioni del passaggio precedente siano elencate:
- > Office 365 Exchange Online Exchange.ManageAsApp:
  - Tipo: applicazione
  - Amministrazione consenso richiesto: Sì
- > Office 365 Exchange Online Exchange.ManageV2:
  - Tipo: Delegato
  - Amministrazione consenso richiesto: Sì
Selezionare Concedi consenso amministratore per, esaminare la finestra di dialogo di conferma e selezionare Sì.

Passaggio 3: Assegnare autorizzazioni di controllo degli accessi in base al ruolo

Dopo aver registrato l'app e aver concesso le autorizzazioni api, è necessario configurare i ruoli controllo degli accessi in base al ruolo di Exchange. Gli ambiti OAuth consentono all'app di ottenere token, ma il controllo degli accessi in base al ruolo determina quali cmdlet e oggetti possono essere gestiti dal chiamante. Senza le assegnazioni di ruolo controllo degli accessi in base al ruolo appropriate, anche i token validi hanno esito negativo con l'errore : 403 Non consentito.

Usa i passaggi descritti in una delle sottosezioni seguenti in base alla natura dell'app.

Autorizzazioni per il flusso delegato (utente)

Per gli scenari delegati, l'utente per conto del quale l'app acquisisce il token deve avere i ruoli di controllo degli accessi in base al ruolo necessari assegnati in Exchange Online. Esempi di ruoli comuni:

Gestione destinatari per le operazioni di cassette postali e cartelle.
Gestione dell'organizzazione per le impostazioni a livello di organizzazione.
Gestione dell'organizzazione di sola visualizzazione per le operazioni dell'organizzazione di sola lettura.

Assegnare questi ruoli tramite l'interfaccia di amministrazione di Exchange o Exchange Online PowerShell. Per istruzioni, vedere Gestire i gruppi di ruoli in Exchange Online.

Autorizzazioni per il flusso solo app

Per gli scenari solo app, l'entità servizio che rappresenta l'app deve avere autorizzazioni sufficienti. Sono disponibili le opzioni seguenti:

Assegnare Microsoft Entra ruoli (consigliato per semplicità): concedere un ruolo di Microsoft Entra predefinito all'applicazione aziendale. Ad esempio, Amministratore di Exchange per autorizzazioni di Exchange Online complete:
1. Nel Interfaccia di amministrazione di Microsoft Entra in https://entra.microsoft.comselezionare Ruoli & amministratori.
2. In Ruoli e amministratori | Nella pagina Tutti i ruoli selezionare il ruolo Amministratore di Exchange facendo clic in un punto qualsiasi della riga diversa dalla casella di controllo accanto alla prima colonna.
3. Nell'amministratore di Exchange | Pagina Assegnazioni visualizzata, selezionare Aggiungi assegnazioni, scegliere l'app e quindi selezionare Conferma.
Assegnare gruppi di ruoli predefiniti o personalizzati del controllo degli accessi in base al ruolo di Exchange (privilegi minimi): creare o usare gruppi di ruoli personalizzati esistenti in Exchange Online che contengono solo i cmdlet necessari per l'app e aggiungere l'entità servizio a tali gruppi. Questo approccio evita privilegi generali e si allinea alla sicurezza con privilegi minimi. Per altre informazioni, vedere Autenticazione solo app in Exchange Online PowerShell.

La tabella seguente elenca il ruolo RBAC predefinito necessario per ogni endpoint.

Endpoint	Gruppo di ruoli di Exchange obbligatorio
/OrganizationConfig /AcceptedDomain	Gestione organizzazione sola visualizzazione
/Cassetta postale /MailboxFolderPermission /DistributionGroupMember /DynamicDistributionGroupMember	Gestione destinatari

Per un controllo ancora più granulare, è consigliabile usare gruppi di ruoli personalizzati che includono solo i ruoli di gestione specifici (set di cmdlet) necessari per l'applicazione. Questo approccio segue la sicurezza con privilegi minimi e riduce i rischi rispetto a ruoli generali come Amministratore di Exchange o Amministratore globale, che superano l'ambito necessario per le tipiche operazioni API Amministrazione.

Passaggio 4: Ottenere un token di accesso

Per chiamare l'API Exchange Online Amministrazione, l'app deve ottenere un token di accesso OAuth 2.0 da Microsoft Entra ID. Come accennato in precedenza, Amministrazione API supporta i flussi seguenti:

Flusso di codice di autorizzazione (delegato) con token di aggiornamento: l'app agisce per conto di un utente connesso e può anche ottenere un token di aggiornamento per il rinnovo invisibile all'utente se la richiesta include l'ambito offline_access .
Flusso delle credenziali client (solo app): l'app funziona da sola (nessun utente). Usato per scenari di servizio/in background. I token di aggiornamento non vengono rilasciati in questo flusso.

Usare l'ambito /.default della risorsa quando si richiedono token , https://outlook.office365.com/.defaultad esempio . Questo metodo indica a Microsoft Entra ID di emettere un token contenente le autorizzazioni dell'applicazione (ruoli) concesse in precedenza per tale risorsa.

Flusso di codice di autorizzazione (delegato) con token di aggiornamento

Usare questo flusso quando è necessario il contesto utente. Per ottenere un token di aggiornamento, è necessario richiedere offline_access nelle richieste di autorizzazione e token. Per altre informazioni, vedere Aggiornare i token nel Microsoft Identity Platform e Gli ambiti e le autorizzazioni nel Microsoft Identity Platform.

L'utente deve autorizzare l'app ad agire per suo conto. L'app reindirizza l'utente all'endpoint /authorize nel Microsoft Identity Platform. Tramite questo endpoint, Microsoft Entra ID accede all'utente e richiede il consenso per le autorizzazioni richieste dall'app. Dopo il consenso, Microsoft Entra ID restituisce un codice di autorizzazione all'app. L'app può quindi riscattare questo codice nell'endpoint /token del Microsoft Identity Platform per un token di accesso.

Nell'esempio seguente viene illustrata una richiesta all'endpoint /authorize . Nell'URL della richiesta si chiama l'endpoint /authorize e si specificano le proprietà necessarie e consigliate come parametri di query. Ad esempio:

GET https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/authorize
    ?client_id=<ClientID>
    &response_type=code
    &redirect_uri=<RedirectURI> # must exactly match the app registration
    &response_mode=query
    &scope=https://outlook.office365.com/.default offline_access
    &state=12345

I parametri sono descritti nella tabella seguente:

Parametro	Obbligatorio	Descrizione
TENANTID	Obbligatorio	L'organizzazione in cui si richiede l'autorizzazione. Il valore può essere il GUID TenantID o il nome descrittivo.
client_id	Obbligatorio	ID client assegnato all'app dal portale di registrazione. Noto anche come appId.
response_type	Obbligatorio	Deve includere il valore `code` per il flusso del codice di autorizzazione OAuth 2.0.
redirect_uri	Consigliata	URI di reindirizzamento dell'app in formato con codifica URL, in cui le risposte di autenticazione vengono inviate e ricevute dall'app. Deve corrispondere a uno degli URI di reindirizzamento registrati nel portale di registrazione dell'app.
portata	Obbligatorio	Elenco delimitato da spazi delle autorizzazioni dell'API Exchange Online Amministrazione a cui si vuole che l'utente acconsenta. Queste autorizzazioni possono includere autorizzazioni per le risorse (`https://outlook.office365.com/.default` in questo scenario) e ambiti OIDC, ad `offline_access`esempio , che indica che l'app necessita di un token di aggiornamento per l'accesso di lunga durata alle risorse.
response_mode	Consigliata	Specifica il metodo per inviare nuovamente il token risultante all'app. I valori validi sono `query` o `form_post`.
stato	Consigliata	Valore incluso nella richiesta che viene restituito anche nella risposta del token. Può essere una stringa di qualsiasi contenuto. In genere si usa un valore univoco casuale per evitare attacchi di falsificazione di richieste tra siti. Questa proprietà codifica anche le informazioni sullo stato dell'utente nell'app prima che si verificasse la richiesta di autenticazione, ad esempio la pagina o la visualizzazione in cui si trovava.

L'utente accede e acconsente. Microsoft Entra ID reindirizza all'utente redirect_uri con ?code=<authorization_code>.
L'uso offline_access di abilita l'emissione di un token di aggiornamento in un secondo momento. Per altre informazioni, vedere Aggiornare i token nel Microsoft Identity Platform e Gli ambiti e le autorizzazioni nel Microsoft Identity Platform.

Passaggio 2: Riscattare il codice di autorizzazione per i token

L'app usa il codice di autorizzazione del passaggio precedente per richiedere un token di accesso inviando una richiesta POST all'endpoint /token .

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                  # confidential clients only
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<RedirectURI>
&scope=https://outlook.office365.com/.default offline_access

I parametri sono descritti nella tabella seguente:

Parametro	Obbligatorio	Descrizione
TENANTID	Obbligatorio	L'organizzazione in cui si richiede l'autorizzazione. Il valore può essere il GUID TenantID o il nome descrittivo.
client_id	Obbligatorio	ID client assegnato all'app dal portale di registrazione. Noto anche come appId.
grant_type	Obbligatorio	Il valore deve essere `authorization_code` per il flusso del codice di autorizzazione.
portata	Obbligatorio	Elenco di ambiti separati da spazi. Gli ambiti richiesti dall'app devono essere equivalenti o un subset degli ambiti richiesti nel passaggio 1: Inviare l'utente all'accesso e al consenso.
code	Obbligatorio	Codice di autorizzazione ottenuto nel passaggio 1: Inviare l'utente per l'accesso e il consenso.
redirect_uri	Obbligatorio	Lo stesso valore URI di reindirizzamento usato per acquisire il codice di autorizzazione nel passaggio 1: Inviare l'utente all'accesso e al consenso.
client_secret	Obbligatorio per le app Web	Segreto client creato nel portale di registrazione dell'app per l'app.

Una risposta riuscita include:

access_token:Portatore. In genere, circa 60 minuti.
refresh_token: presente, perché offline_access è stato richiesto.
id_token:Opzionale. Restituito se l'ambito openid è stato richiesto. Per altre informazioni, vedere Microsoft Identity Platform tipi di app e flussi di autenticazione e Token di aggiornamento nel Microsoft Identity Platform.

Consiglio

Archiviare il valore TenantID (tid) dalle attestazioni del token. È necessario che formi Amministrazione URL API e richieste di token future. Per altre informazioni, vedere Microsoft Identity Platform tipi di app e flussi di autenticazione.

Passaggio 3: Aggiornare il token di accesso in modo invisibile all'utente (nessun prompt utente)

I token di accesso sono di breve durata e l'app deve aggiornarli dopo la scadenza per continuare ad accedere alle risorse. L'app aggiorna un token di accesso inviando un'altra richiesta POST all'endpoint /token :

Specificare invece refresh_token di code nel corpo della richiesta.
Specificare refresh_token anziché authorization_code come grant_type.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>
&grant_type=refresh_token
&refresh_token=<refresh_token>
&scope=https://outlook.office365.com/.default offline_access

I parametri sono descritti nella tabella seguente:

Parametro	Obbligatorio	Descrizione
TENANTID	Obbligatorio	L'organizzazione in cui si richiede l'autorizzazione. Il valore può essere il GUID TenantID o il nome descrittivo.
client_id	Obbligatorio	ID client assegnato all'app dal portale di registrazione. Noto anche come appId.
grant_type	Obbligatorio	Il valore deve essere `refresh_token`.
refresh_token	Obbligatorio	Il refresh_token ottenuto dall'app durante la richiesta di token nel passaggio 2: Riscattare il codice di autorizzazione per i token.
portata	Obbligatorio	Elenco di ambiti separati da spazi. Gli ambiti richiesti dall'app devono essere equivalenti o un subset degli ambiti richiesti nel passaggio 2: Riscattare il codice di autorizzazione per i token.
client_secret	Obbligatorio per le app Web	Segreto client creato nel portale di registrazione dell'app per l'app.

Una risposta riuscita include i risultati seguenti:

Restituisce un nuovo access_token e spesso un nuovo refresh_token per sostituire quello precedente.
I token di aggiornamento durano più a lungo dei token di accesso. Il valore predefinito è di circa 90 giorni per i client riservati e di 24 ore per gli URI di reindirizzamento spa. I token possono essere revocati in qualsiasi momento, quindi gestire la riautenticazione quando necessario. Per altre informazioni, vedere Aggiornare i token nel Microsoft Identity Platform.

Flusso delle credenziali client (solo app)

Usare questo flusso per le chiamate da servizio a servizio senza un utente. Dopo il consenso dell'amministratore per le autorizzazioni dell'applicazione (ad esempio, Exchange.ManageAsAppV2) e l'assegnazione dei ruoli di controllo degli accessi in base al ruolo necessari, richiedere un token usando le credenziali dell'app. Non viene emesso alcun token di aggiornamento. Richiedere nuovi token di accesso in base alle esigenze.

Per acquisire un token di accesso, inviare una richiesta POST all'endpoint della /token piattaforma di identità. In questa richiesta il client usa il segreto client.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                   # or client assertion (certificate)
&grant_type=client_credentials
&scope=https://outlook.office365.com/.default

I parametri sono descritti nella tabella seguente:

Parametro	Condizione	Descrizione
TENANTID	Obbligatorio	L'organizzazione in cui si richiede l'autorizzazione. Il valore può essere il GUID TenantID o il nome descrittivo.
client_id	Obbligatorio	ID applicazione assegnato all'app dal portale di registrazione.
portata	Obbligatorio	URI dell'ID app della risorsa con il `.default` suffisso . Per l'API Exchange Online Amministrazione, l'URI dell'ID dell'app della risorsa è `https://outlook.office365.com/`, quindi il valore dell'ambito è `https://outlook.office365.com/.default`. Questo valore informa l'endpoint Microsoft Identity Platform di includere tutte le autorizzazioni a livello di app a cui l'amministratore ha acconsentito nel token di accesso.
client_secret	Obbligatorio	Segreto client generato per l'app nel portale di registrazione dell'app. Verificare che il valore sia codificato in URL.
grant_type	Obbligatorio	Il valore deve essere `client_credentials`.

Passaggio 5: Usare il token di accesso

Dopo aver ottenuto un token di accesso come descritto in Passaggio 4: Ottenere un token di accesso, includere il token di accesso nell'intestazione Authorization per ogni chiamata API successiva:

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json

 { "CmdletInput": { "CmdletName": "Get-OrganizationConfig" } }

Usare Microsoft Authentication Library (MSAL)

Questo articolo contiene i dettagli del protocollo necessari quando si crea manualmente un problema di richieste HTTP non elaborate per ottenere token per i segreti client. Nelle app di produzione usare una libreria di autenticazione predefinita o supportata per ottenere token di sicurezza e chiamare API Web protette. Ad esempio, Microsoft Authentication Library (MSAL).

MSAL e altre librerie di autenticazione supportate semplificano il processo gestendo i dettagli in modo da poter concentrarsi sulle funzionalità dell'app. Ad esempio:

Convalida.
Gestione dei cookie.
Memorizzazione nella cache dei token.
Connessioni sicure.

Microsoft gestisce un'ampia selezione di esempi di codice che illustrano le librerie di autenticazione supportate con il Microsoft Identity Platform. Per accedere a questi esempi di codice, vedere Microsoft Identity Platform esempi di codice.

Per esempi su come ottenere token usando i certificati, vedere Microsoft Identity Platform e il flusso delle credenziali client OAuth 2.0.

Last updated on 2025-11-17

Autenticazione e autorizzazione per l'API Exchange Online Amministrazione

Passaggio 1: Registrare un'app in Microsoft Entra ID

Passaggio 2: Assegnare le autorizzazioni API necessarie

Passaggio 3: Assegnare autorizzazioni di controllo degli accessi in base al ruolo

Autorizzazioni per il flusso delegato (utente)

Autorizzazioni per il flusso solo app

Passaggio 4: Ottenere un token di accesso

Flusso di codice di autorizzazione (delegato) con token di aggiornamento

Passaggio 1: Inviare all'utente l'accesso e il consenso

Passaggio 2: Riscattare il codice di autorizzazione per i token

Passaggio 3: Aggiornare il token di accesso in modo invisibile all'utente (nessun prompt utente)

Flusso delle credenziali client (solo app)

Passaggio 5: Usare il token di accesso

Usare Microsoft Authentication Library (MSAL)

Risorse aggiuntive