Crea ora

Microsoft Graph OAuth: Autenticare cassette postali di Outlook e Microsoft 365 (Guida 2026)

Microsoft Graph OAuth 2026

Microsoft Graph OAuthAutenticare cassette postali di Outlook e Microsoft 365

Una guida completa al 2026 per Microsoft Graph OAuth per sviluppatori SaaS. Copre la registrazione delle app Microsoft Entra, gli endpoint di autorità, gli ambiti di Mail, i permessi delegati vs applicativi, il consenso dell'amministratore, il codice di autorizzazione + PKCE, la rotazione dei token di aggiornamento, i codici di errore AADSTS e come Unipile elimina 5 settimane di plumbing OAuth in 5 minuti.

Costruiscilo con Unipile Guida a MS Graph
link_account_outlook.py
import richieste # Fase 1: Generare un link di autenticazione ospitato response = requests.posta( "https://apiXXX.unipile.com:XXX /api/v1/hosted/accounts/collegare", intestazioni={"X-API-KEY": api_key}, json={ "tipo": "creare", "fornitori": ["MICROSOFT"], "url_api": il_tuo_dsn, "scadenza": "2026-12-31T23:59:59Z" } ) # Fase 2: Reindirizza l'utente all'URL auth_url = risposta.json()["url"] # Unipile gestisce l'intero flusso OAuth #, inclusi Entra, scope, token e refresh
Microsoft OAuth gestito. Casella di posta pronta.
Contesto 2026

Perché Microsoft Graph OAuth è Non-Negozabile nel 2026

Se la tua applicazione SaaS legge, invia o sincronizza e-mail di Outlook o Microsoft 365, Microsoft Graph OAuth non è più opzionale. Tre importanti depreciazioni hanno reso obsoleti i Basic Auth, i protocolli legacy e le password per app. OAuth 2.0 tramite l'API Microsoft Graph è l'unico percorso supportato.

Basic Auth - Completamente deprecato
Microsoft ha disabilitato l'autenticazione di base per Exchange Online nell'ottobre 2022. Ciò interessa IMAP, POP3, SMTP, EWS, MAPI, OAB, Outlook Anywhere e RPC su HTTP. Nessuna eccezione, non ci sono più estensioni del periodo di grazia.
Disabilitato Ottobre 2022
EWS - Tempistiche di tramonto
Exchange Web Services (EWS) è in modalità di manutenzione. Microsoft ha annunciato che non introdurrà nuove funzionalità e raccomanda la migrazione a Microsoft Graph. Sebbene non sia ancora completamente dismesso, creare nuove integrazioni basate su EWS nel 2026 sarà una decisione di debito tecnico di cui ti pentirai.
Modalità di manutenzione
OAuth 2.0 - Lo standard richiesto
Microsoft Graph OAuth tramite Microsoft Entra ID (precedentemente Azure AD) è l'unico metodo di autenticazione ufficialmente supportato per le applicazioni SaaS di produzione che accedono alle cassette postali di Outlook e Microsoft 365 nel 2026. Questa guida copre l'implementazione completa.
Standard Richiesto
Cosa sblocca Microsoft Graph OAuth
Leggere, inviare e sincronizzare le caselle di posta elettronica di Outlook per conto di utenti autenticati
Accedi alle caselle di posta Microsoft 365 e Outlook.com personali con una singola registrazione dell'app
Token di aggiornamento di lunga durata con rotazione automatica (nessun riautenticazione per gli utenti attivi)
Controllo granulare dell'ambito: richiedi solo le autorizzazioni di cui la tua app ha veramente bisogno
Supporto multi-tenant: una singola registrazione dell'app serve tutti i tenant dei clienti
Conformità alle policy aziendali di Conditional Access e MFA
Flussi OAuth

I 3 Flussi OAuth Supportati da Microsoft (e Quale Serve alla SaaS)

La piattaforma di identità di Microsoft supporta diversi tipi di concessione OAuth 2.0. Scegliere quello sbagliato è una fonte comune di tempo di ingegneria sprecato. Ecco la suddivisione per applicazioni SaaS che accedono all'e-mail per conto dei propri utenti.

Consigliato per SaaS
Codice di autorizzazione + PKCE
Sezione 4.1 di RFC 6749 + RFC 7636
L'utente viene reindirizzato alla pagina di accesso di Microsoft, esegue l'autenticazione e concede il consenso. L'app scambia il codice di autorizzazione restituito con token di accesso e di aggiornamento. PKCE (Proof Key for Code Exchange) impedisce gli attacchi di intercettazione del codice ed è obbligatorio per i client pubblici e consigliato per tutti i client nel 2026.
Usalo per app SaaS che accedono alle caselle di posta degli utenti
Credenziali del client
OAuth 2.0 Sezione 4.4 (solo app)
Nessuna interazione utente. La tua app si autentica come se stessa utilizzando un ID client e un segreto (o certificato). Richiede autorizzazioni a livello di applicazione (non delegate), il che significa che un amministratore del tenant deve concedere il consenso per accedere a tutte le cassette postali dell'organizzazione. Nessuna schermata di consenso utente.
Solo per strumenti interni con accesso concesso dall'amministratore
Device Code Flow
Concessione di autorizzazione del dispositivo OAuth 2.0
Progettato per dispositivi senza browser (CLI, IoT, smart TV). L'utente visita un URL su un altro dispositivo per autenticarsi. Non pertinente per le applicazioni web SaaS in cui è possibile un reindirizzamento.
Non applicabile alle normali applicazioni web SaaS
Inizia a costruire il tuo flusso di autenticazione OAuth di Microsoft
Unipile - Registrazione dell'app Microsoft Entra
Impostazione passo passo

Registrazione di un'app in Microsoft Entra: 7 passaggi

Prima che la tua app possa richiedere token OAuth, è necessaria un'applicazione registrata in Microsoft Entra ID (precedentemente Azure Active Directory). Ecco i passaggi esatti, inclusi i valori dei campi che contano e quelli che sono estetici.

1
Crea una registrazione dell'app nel portale di Azure
Naviga verso portal.azure.com, vai a Microsoft Entra ID (cerca nella barra in alto), poi Registrazioni app, quindi clicca + Nuova registrazione. Vedi il documentazione completa di Microsoft OAuth per ulteriore contesto.
Nome
Nome della tua app. Questo è ciò che gli utenti vedono nella schermata di consenso di Microsoft. Usa il nome del tuo prodotto, non un identificatore tecnico.
Tipi di account supportati
Per un SaaS multi-tenant che serve sia utenti aziendali che personali: seleziona Account in qualsiasi directory organizzativa (qualsiasi tenant Microsoft Entra ID - multitenant) e account Microsoft personali. Ciò corrisponde al Comune endpoint di autorizzazione.
Suggerimento: Se servi solo account aziendali di Microsoft 365 (non Outlook.com personali), seleziona solo "Multitenant". Questo utilizza l' /organizzazioni autorità e riduce la tua superficie di consenso. Maggiori informazioni sugli endpoint di autorità nella sezione 4.
2
Configurare URI di reindirizzamento
Dopo la registrazione, vai a Autenticazione nel pannello di sinistra. Aggiungi una piattaforma: seleziona Web. Aggiungi il tuo URI di reindirizzamento, l'URL a cui Microsoft reindirizzerà l'utente con il codice di autorizzazione.
Tipo di piattaforma
Web per le app lato server. Usa Applicazione a pagina singola (SPA) per i flussi lato client (abilita automaticamente PKCE).
URI di reindirizzamento
Deve essere HTTPS in produzione. Esempio: https://app.yourproduct.com/auth/microsoft/callback. Corrispondenza esatta richiesta, qualsiasi deviazione causa AADSTS50011.
URL di logout (facoltativo)
Microsoft chiamerà questo URL quando l'utente esce da qualsiasi app nel proprio tenant. Facoltativo per le integrazioni solo via e-mail.
Errore comune: localhost URIs sono ammessi durante lo sviluppohttp://localhost:3000/callbackma gli URI di produzione devono usare HTTPS. Registra entrambi separatamente.
3
Aggiungi autorizzazioni per Microsoft Graph API
Vai a Permessi API. Clicca + Aggiungi un permesso, Seleziona Microsoft Graph, poi Permessi delegati. Aggiungi gli ambiti di cui la tua app ha bisogno.
Minimo per leggere
Posta.Leggi, accesso offline, openid, profilo
Per leggere + inviare
Mail.ReadWrite, Mail.Send, accesso offline, openid, profilo
accesso offline
Fondamentale. Senza questo ambito, Microsoft non rilascia un token di aggiornamento. I tuoi utenti dovranno autenticarsi nuovamente ogni 60-90 minuti.
Nota: L'aggiunta di autorizzazioni qui non le concede, ma dichiara la tua intenzione. L'utente acconsente quando completa il flusso OAuth. Il consenso dell'amministratore è richiesto per alcune autorizzazioni di livello superiore (vedere la sezione 7).
4
Genera un segreto client
Vai a Certificati e segreti. Clicca + Nuovo segreto del client. Imposta una descrizione e una scadenza.
Raccomandazione di scadenza
730 giorni (24 mesi) è il massimo. Imposta un promemoria del calendario 60 giorni prima della scadenza, la rotazione di un segreto scaduto causa fallimenti di autenticazione immediati per tutti gli utenti.
Copia il valore immediatamente
Il valore segreto viene mostrato una sola volta. Memorizzalo nel tuo gestore di segreti (ad esempio, AWS Secrets Manager, HashiCorp Vault, Azure Key Vault). Non verrà più mostrato dopo aver lasciato questa pagina.
Alternativa consigliata: Per la produzione, utilizza un certificato anziché un segreto client. I certificati sono più sicuri (chiave asimmetrica), non scadono mai per errore e sono preferiti da Microsoft per le app di livello aziendale.
5
Copia il tuo ID client e ID tenant
Dal Panoramica pagina di registrazione della tua app, copia due valori che ti serviranno in ogni richiesta OAuth:
ID applicazione (client)
Un UUID che identifica univocamente la registrazione della tua app. Utilizzato come ID cliente parametro in tutte le richieste di autenticazione.
ID directory (tenant)
L'ID tenant della tua organizzazione. Utilizzato negli URL di autorizzazione a tenant singolo. Per le app multitenant, usi Comune invece, ma conserva questo valore per gli URL di consenso dell'amministratore.
6
Abilita i token ID (facoltativo ma consigliato)
Di ritorno Autenticazione, sotto Flussi impliciti e ibridi, puoi abilitare Token ID. Ciò ti consente di ricevere un JWT con attestazioni sull'identità dell'utente (nome, email, ID tenant) insieme al token di accesso, utile per i flussi di onboarding in cui desideri precompilare i dati del profilo utente.
Previsioni per il 2026: Per i flussi auth-code puri + PKCE, i token ID vengono restituiti tramite il punto di accesso del token, non tramite la concessione implicita. Non è necessario abilitare la concessione implicita. Abilitatela solo se si dispone di una SPA legacy che non può utilizzare PKCE.
7
Opzionale: Verifica il tuo dominio dell'editore
In Marchio e proprietà, imposta il tuo dominio di pubblicazione sul dominio del tuo prodotto. Questo sostituisce l'etichetta "non verificato" nella schermata di consenso con il nome del tuo dominio. Per le app multi-tenant destinate a clienti aziendali, il completamento della verifica Microsoft Partner Network e la qualifica come "publisher verificato" rimuovono l'avviso in evidenza "Questa app non è comunemente utilizzata".
Dominio dell'editore
Un dominio di tua proprietà e verificato tramite record TXT o tramite il flusso di validazione del dominio di App Service.
Editore verificato
Richiede l'ID Microsoft Partner Network (MPN) collegato a un'identità aziendale verificata. Richiede 1-5 giorni lavorativi. Migliora significativamente la conversione dei clienti aziendali nelle schermate di consenso.
Salta la configurazione: costruisci con Unipile invece
Punti di accesso all'autorità

Scegliere l'endpoint di autorizzazione Microsoft corretto

L'URL dell'autorità che utilizzi nelle richieste OAuth determina quali tipi di account Microsoft possono autenticarsi e quali token ricevi. Sbagliare questo passaggio causa errori silenziosi per cui alcuni utenti non riescono ad autenticarsi affatto.

URL dell'autorità Accetta Caso d'uso Avvertenze
ComuneLa maggior parte dei SaaS Sia account Microsoft Entra (lavoro/scuola) che account Microsoft personali (Outlook.com, Hotmail, Live) SaaS multi-tenant al servizio di tutti gli utenti Microsoft. Un unico endpoint gestisce tutta la tua base di utenti. I token sono emessi dall'organizzazione principale di ciascun utente, non dalla tua. La convalida dei token deve utilizzare l'emittente specifico dell'organizzazione o accettare più emittenti. Non è possibile applicare criteri di accesso condizionale.
/organizzazioni Solo account Microsoft Entra ID (lavoro/scuola). Nessun account Microsoft personale. SaaS B2B mirato esclusivamente a clienti enterprise, mai a utenti consumer di Outlook.com. Gli utenti con account Microsoft personali riceveranno un errore. Validazione del token più semplice (pattern a emittente singolo accettabile).
consumatori Solo account Microsoft personali (Outlook.com, Hotmail, Live). App consumeristiche che prendono di mira le caselle di posta personali. Rara per il SaaS B2B. Gli account Enterprise Microsoft 365 vengono rifiutati. Non utili per il servizio SaaS rivolto agli utenti aziendali.
/{id-tenant} Account in un tenant Microsoft Entra specifico. Strumenti interni a tenant singolo (app della tua azienda). Flussi di consenso dell'amministratore mirati a un tenant specifico. Utilizzato anche nel pattern URL di reindirizzamento del consenso dell'amministratore. Gli utenti di ogni altro tenant vengono rifiutati. Adatto solo per app interne o quando si blocca deliberatamente a un tenant di un cliente.
Comune La maggior parte dei SaaS
Accetta Sia account Microsoft Entra (lavoro/scuola) che account Microsoft personali (Outlook.com, Hotmail, Live)
Caso d'uso SaaS multi-tenant al servizio di tutti gli utenti Microsoft. Un unico endpoint gestisce tutta la tua base di utenti.
Avvertenze I token sono emessi dall'organizzazione principale di ciascun utente, non dalla tua. La convalida dei token deve utilizzare l'emittente specifico dell'organizzazione o accettare più emittenti. Non è possibile applicare criteri di accesso condizionale.
/organizzazioni
Accetta Solo account Microsoft Entra ID (lavoro/scuola). Nessun account Microsoft personale.
Caso d'uso SaaS B2B mirato esclusivamente a clienti enterprise, mai a utenti consumer di Outlook.com.
Avvertenze Gli utenti con account Microsoft personali riceveranno un errore. Validazione del token più semplice (pattern a emittente singolo accettabile).
consumatori
Accetta Solo account Microsoft personali (Outlook.com, Hotmail, Live).
Caso d'uso App consumeristiche che prendono di mira le caselle di posta personali. Rara per il SaaS B2B.
Avvertenze Gli account Enterprise Microsoft 365 vengono rifiutati. Non utili per il servizio SaaS rivolto agli utenti aziendali.
/{id-tenant}
Accetta Account in un tenant Microsoft Entra specifico.
Caso d'uso Strumenti interni a tenant singolo (app della tua azienda). Flussi di consenso dell'amministratore mirati a un tenant specifico. Utilizzato anche nel pattern URL di reindirizzamento del consenso dell'amministratore.
Avvertenze Gli utenti di ogni altro tenant vengono rifiutati. Adatto solo per app interne o quando si blocca deliberatamente a un tenant di un cliente.
Nota di validazione del token per /common: Quando si utilizza la Comune endpoint, il sì il claim (issuer) nel JWT sarà https://login.microsoftonline.com/{tenantId}/v2.0 dove {tenantId} varia per utente. Configura la tua libreria di convalida JWT per accettare qualsiasi issuer che corrisponda https://login.microsoftonline.com/{tenantId}/v2.0 piuttosto che una stringa emittente fissa.
Ambienti di posta elettronica

Microsoft Graph Mail Scopes: Analisi dettagliata

Microsoft Graph utilizza gli ambiti di autorizzazione per controllare ciò che la tua applicazione può fare. Richiedere troppi ambiti aumenta l'attrito nella schermata di consenso e riduce le conversioni. Richiederne troppo pochi causa errori di runtime. Ecco tutti gli ambiti di posta elettronica che devi conoscere.

Ambito Tipo Cosa consente Consenso dell'amministratore?
Posta.Leggi Delegato Leggi tutti i messaggi nella casella di posta dell'utente autenticato. Include intestazioni, corpo, allegati. Sola lettura - non può modificare né inviare. Utente
Posta.LeggiBase Delegato Leggi le proprietà limitate del messaggio: oggetto, mittente, destinatari, data. Non è possibile leggere il corpo del messaggio o gli allegati. Utile per elenchi di posta in arrivo leggeri senza accesso completo al contenuto. Utente
Mail.ReadWrite Delegato Leggi e modifica tutti i messaggi. Include la creazione, l'aggiornamento, l'eliminazione di messaggi e cartelle. Superset di Mail.Read - non richiedere entrambi. Utente
Mail.Send Delegato Invia e-mail come utente autenticato. Obbligatorio anche se si dispone di Mail.ReadWrite: l'invio è un'autorizzazione separata in Microsoft Graph. Utente
Mail.Read.Shared Delegato Leggere le e-mail in caselle di posta condivise o in quelle di altri utenti a cui l'utente autenticato ha avuto accesso. Non per leggere la casella di posta dell'utente stesso. Utente
Mail.ReadWrite.Shared Delegato Leggere e modificare le e-mail nelle cassette postali condivise a cui l'utente ha accesso. Utente
Mail.Invia.Condivisa Delegato Inviare e-mail da cartelle condivise o "invia per conto" di un altro utente (se l'utente ha concesso l'accesso). Utente
accesso offline Delegato Istruisce Microsoft a emettere un token di aggiornamento. Senza questo, si riceve solo un token di accesso di breve durata senza alcun modo per rinnovarlo. Sempre richiesto per le applicazioni SaaS. Utente
openid Delegato Restituisce un ID token con l'identità base dell'utente. Richiesto se si desidera sapere chi si è autenticato senza effettuare una chiamata API /me separata. Utente
profilo Delegato Aggiunge le dichiarazioni name e preferred_username all'ID token. Solitamente incluso con openid. Utente
Mail.Leggi (App) Applicazione Leggi tutta la posta in tutte le cassette postali nel tenant senza interazione dell'utente. Utilizzato dai servizi daemon. Richiede il consenso dell'amministratore del tenant. Amministratore richiesto
Posta.LetturaScrittura (App) Applicazione Leggere e scrivere tutte le email in tutte le caselle di posta dei tenant. Permesso molto ampio. Solo per strumenti interni fidati con l'approvazione esplicita dell'amministratore del tenant. Amministratore richiesto
Posta.Leggi Delegato
Leggi tutti i messaggi nella casella di posta dell'utente autenticato. Include intestazioni, corpo, allegati. Sola lettura - non può modificare né inviare.
Consenso dell'utente
Posta.LeggiBase Delegato
Leggi le proprietà limitate del messaggio: oggetto, mittente, destinatari, data. Non è possibile leggere il corpo del messaggio o gli allegati. Utile per elenchi di posta in arrivo leggeri senza accesso completo al contenuto.
Consenso dell'utente
Mail.ReadWrite Delegato
Leggi e modifica tutti i messaggi. Include la creazione, l'aggiornamento, l'eliminazione di messaggi e cartelle. Superset di Mail.Read - non richiedere entrambi.
Consenso dell'utente
Mail.Send Delegato
Invia e-mail come utente autenticato. Obbligatorio anche se si dispone di Mail.ReadWrite: l'invio è un'autorizzazione separata in Microsoft Graph.
Consenso dell'utente
Mail.Read.Shared Delegato
Leggere le e-mail in caselle di posta condivise o in quelle di altri utenti a cui l'utente autenticato ha avuto accesso. Non per leggere la casella di posta dell'utente stesso.
Consenso dell'utente
Mail.ReadWrite.Shared Delegato
Leggere e modificare le e-mail nelle cassette postali condivise a cui l'utente ha accesso.
Consenso dell'utente
Mail.Invia.Condivisa Delegato
Inviare e-mail da cartelle condivise o "invia per conto" di un altro utente (se l'utente ha concesso l'accesso).
Consenso dell'utente
accesso offline Delegato
Istruisce Microsoft a emettere un token di aggiornamento. Senza questo, si riceve solo un token di accesso di breve durata senza alcun modo per rinnovarlo. Sempre richiesto per le applicazioni SaaS.
Consenso dell'utente
openid Delegato
Restituisce un ID token con l'identità base dell'utente. Richiesto se si desidera sapere chi si è autenticato senza effettuare una chiamata API /me separata.
Consenso dell'utente
profilo Delegato
Aggiunge le dichiarazioni name e preferred_username all'ID token. Solitamente incluso con openid.
Consenso dell'utente
Mail.Leggi (App) Applicazione
Leggi tutta la posta in tutte le cassette postali nel tenant senza interazione dell'utente. Utilizzato dai servizi daemon. Richiede il consenso dell'amministratore del tenant.
Amministratore richiesto
Posta.LetturaScrittura (App) Applicazione
Leggere e scrivere tutte le email in tutte le caselle di posta dei tenant. Permesso molto ampio. Solo per strumenti interni fidati con l'approvazione esplicita dell'amministratore del tenant.
Amministratore richiesto
Ambito minimo impostato: lettore inbox
scope=Mail.Readaccesso_offlineopenidprofilo
Leggi messaggi, aggiorna token, identità utente. Nessuna capacità di scrittura o invio.
Ambito standard impostato: integrazione completa e-mail
scope=Mail.ReadWriteMail.Sendoffline_accessopenidprofile
Leggere, scrivere, inviare. Il set più comune per le integrazioni di CRM e strumenti di vendita.
Vedi la guida completa all'API Email
Modello di permessi

Permessi Delegati vs Permessi Applicazione: Quando Usare Ciascuno

Microsoft Graph utilizza due modelli di autorizzazione fondamentalmente diversi. La maggior parte degli sviluppatori SaaS sceglie di default quello sbagliato, il che porta a requisiti di consenso dell'amministratore non necessari e a un'esperienza utente compromessa. Ecco esattamente quando usare ciascuno.

Permessi Delegati
Agisci per conto dell'utente connesso
L'app accede a Microsoft Graph utilizzando l'identità dell'utente autenticato. L'app può fare solo ciò che l'utente stesso potrebbe fare. Se l'utente non può leggere una cartella, nemmeno la tua app potrà farlo.
L'utente acconsente durante il flusso OAuth - non è richiesto l'amministratore per gli ambiti standard
L'accesso è limitato alla casella di posta di ciascun singolo utente
Gli utenti possono revocare l'accesso in qualsiasi momento dalle impostazioni del proprio account Microsoft
Rispetta i permessi a livello utente, le assegnazioni di ruolo e le policy di accesso alle cassette postali
Usare questo per applicazioni SaaS in cui ogni utente si autentica individualmente.
Permessi dell'applicazione
Agisci come l'applicazione stessa
L'app accede a Microsoft Graph senza che nessun utente sia presente. Utilizzata per servizi in background, demoni e flussi di lavoro automatizzati. L'app si autentica utilizzando le proprie credenziali (flusso di credenziali client).
Richiede il consenso dell'amministratore tenant - un ostacolo significativo per gli utenti esterni
L'accesso è a livello di tenant: può leggere TUTTE le cassette postali una volta che l'amministratore acconsente
Nessun accesso utente interattivo richiesto: funziona per l'automazione headless
Adatto per strumenti IT interni dove l'amministratore della tua organizzazione controlla il deployment
Solo per strumenti interni dove l'amministratore della tua organizzazione concede l'accesso completo al tenant
La Regola di Decisione SaaS
Se stai costruendo un prodotto utilizzato dai clienti esterni chi si iscrive singolarmente, usa Permessi delegati. Ogni cliente si autentica con il proprio account Microsoft, concede l'autorizzazione agli ambiti della tua app e la tua app opera per conto di quell'utente autenticato. Le autorizzazioni dell'applicazione richiedono a un amministratore di tenant di pre-approvare la tua app per la loro intera organizzazione, un passaggio che uccide le conversioni in un funnel SaaS self-service. L'unica eccezione è se stai creando uno strumento aziendale interno distribuito dal tuo team IT nel tuo tenant.
Passeggiata completa

Codice di autenticazione + PKCE: esempi Curl passo passo

Ecco il flusso completo di Microsoft Graph OAuth 2.0 con codice di autorizzazione e PKCE, dalla generazione del verificatore di codice allo scambio di token. Questi sono esempi di livello di produzione che puoi adattare direttamente al tuo stack.

Passaggio 1 di 4 - Genera parametri PKCE
codice_verificatore e sfida_codice
PKCE funziona generando un segreto casuale (code_verifier), quindi un hash SHA-256 di esso (code_challenge). Invi il challenge nel passaggio 2 e il verifier nel passaggio 4. Microsoft verifica che corrispondano, impedendo l'intercettazione del codice.
pkce_genera.py
import os, base64, hashlib # 1. Genera code_verifier (43-128 caratteri, base64 compatibile con gli URL) code_verifier = base64.urlsafe_b64encode( os.urandom(32) ).decodifica('utf-8').rimuovere gli spazi bianchi alla fine('=') # 2. Generare code_challenge = BASE64URL(SHA256(code_verifier)) sfida_di_codice = base64.urlsafe_b64encode( hashlib.sha256(codice_verificatore.codificare('utf-8')).digest() ).decodifica('utf-8').rimuovere gli spazi bianchi alla fine('=') # Salva code_verifier nella sessione: ti servirà al punto 4 # Inserire il codice di verifica nell'URL di autorizzazione
Passaggio 2 di 4 - Richiesta di autorizzazione
Costruisci l'URL di /authorize e reindirizza l'utente
Reindirizza il browser dell'utente all'endpoint di autorizzazione di Microsoft. L'utente visualizza la pagina di accesso di Microsoft, si autentica e concede il consenso agli ambiti della tua applicazione. Microsoft quindi reindirizza all'indirizzo redirect_uri con un codice di autorizzazione.
ID cliente
ID dell'applicazione (client) dalla registrazione dell'app Entra
tipo_di_risposta
codice - richiede un codice di autorizzazione
uri_di_reindirizzamento
Deve corrispondere esattamente a un URI registrato nella tua app Entra. Codificato in URL.
ambito
Elenco separato da spazi. Includi sempre accesso offline per i token di aggiornamento.
stato
Valore opaco generato. Restituito invariato nella callback. Usalo per prevenire CSRF e ripristinare lo stato dell'interfaccia utente.
sfida_di_codice
Il valore BASE64URL(SHA256(code_verifier)) del passaggio 1.
sfida_codice_metodo
S256 - usa sempre SHA-256, mai normale
authorize_url.sh
# Generazione dell'URL di autorizzazione (formato ottimizzato per la leggibilità) URL_AUTENTICAZIONE="https://login.microsoftonline.com/common/oauth2/v2.0/authorize ?client_id=IL_TUO_CLIENT_ID &response_type=code &redirect;_uri=https://3Aapp.com/3Aauth/3Ams/3Acb &scope;=Mail.ReadWriteMail.Sendoffline_access &stato=VALORE_STATO_CASUALE &code_challenge=LA_TUA_SFIDA_DI_CODICE &code_challenge_method=S256" # Reindirizza l'utente a $AUTH_URL # Microsoft gestisce l'accesso, l'autenticazione a più fattori (MFA) e la schermata di consenso # In caso di esito positivo: redirect_uri?code=AUTH_CODE&state;=...
Passaggio 3 di 4 - Gestire la Callback
Ricevi il codice di autorizzazione al tuo redirect_uri
Microsoft reindirizza al tuo redirect_uri con un codice parametro di query. Validare il stato il parametro corrisponde a quello che hai inviato. Il codice scade tra 10 minuti - scambialo immediatamente al passo 4.
Passaggio 4 di 4 - Scambio di token
Scambia il codice di autorizzazione per i token di accesso + refresh
INVIA al token endpoint con il codice e il tuo code_verifier. Microsoft restituisce un token di accesso (valido per circa 60-90 minuti) e un token di aggiornamento (a lunga durata). Memorizza entrambi in modo sicuro.
token_exchange.sh
Codice di autorizzazione # per i token curl -X POSTA "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=IL_TUO_CLIENT_ID" \ -d "client_secret=IL_TUO_CLIENT_SECRET" \ -d "grant_type=authorization_code" \ -d "code=AUTH_CODE_FROM_CALLBACK" \ -d "redirect_uri=https://app.com/auth/ms/cb" \ -d "code_verifier=IL_TUO_CODE_VERIFIER" \ -d "scope=Mail.ReadWrite Mail.Send accesso_offline"
Restituisce: access_token, refresh_token, expires_in, scope
token_response.json
{ "tipo_token": "Portatore", "ambito": "Mail.ReadWrite Mail.Send offline_access", "scadenza": 3600, "token_di_accesso": "eyJ0eXAiOiJKV1Qi...", "token di aggiornamento": "0.ARoAi7W...", "token_id": "eyJ0eXAi..." }
Ciclo di vita del token

Gestione del Refresh Token: Rotazione, Scadenza e Accesso Condizionale

I token di aggiornamento di Microsoft Graph sono di lunga durata ma non permanenti. Diverse condizioni possono invalidarli silenziosamente. Comprendere questi casi limite è ciò che distingue un'integrazione Microsoft OAuth di livello di produzione da una che si interrompe in modo casuale per gli utenti aziendali.

Scadenza per inattività di 90 giorni
I token di aggiornamento di Microsoft scadono dopo 90 giorni di inattività. Se un utente non utilizza la tua app per 90 giorni, il suo token di aggiornamento diventa non valido e dovrà autenticarsi nuovamente. Non c'è modo di estenderlo senza interazione dell'utente. Gestisci sempre concessione_non_valida gestire gli errori con grazia e richiedere la riautenticazione.
Modifiche alle policy di accesso condizionale
Gli tenant aziendali utilizzano criteri di accesso condizionale (requisiti MFA, conformità del dispositivo, restrizioni di posizione). Se un criterio cambia dopo che un utente si è autenticato, il suo token di aggiornamento potrebbe essere invalidato al prossimo utilizzo. Questa è una decisione lato cliente: non è possibile controllarla o prevederla. Propagare sempre gli errori di autenticazione agli utenti con un chiaro prompt di riautenticazione.
Rotazione del token di aggiornamento
Quando utilizzi un token di aggiornamento per ottenere un nuovo token di accesso, Microsoft potrebbe emettere un nuovo token di aggiornamento. Salva sempre il nuovo token di aggiornamento dalla risposta, sostituendo quello vecchio. Se continui a utilizzare il vecchio token di aggiornamento dopo che è stato ruotato, alla fine raggiungerai un concessione_non_valida errore.
Revoca amministratore
Un amministratore di tenant può revocare tutti i token di aggiornamento per un utente o per l'intera organizzazione in qualsiasi momento (ad es. quando un dipendente lascia l'azienda o durante un incidente di sicurezza). La tua app riceve concessione_non_valida. Questo è il comportamento atteso: gestiscilo contrassegnando l'account collegato come necessitante di riautorizzazione.
refresh_token.sh
# Aggiorna il token di accesso utilizzando il token di aggiornamento memorizzato curl -X POSTA "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=IL_TUO_CLIENT_ID" \ -d "client_secret=IL_TUO_CLIENT_SECRET" \ -d "grant_type=refresh_token" \ -d "refresh_token=TOKEN_DI_REFRESH_MEMORIZZATO" \ -d "scope=Mail.ReadWrite Mail.Send accesso_offline" # Verificare SEMPRE la presenza di un nuovo refresh_token nella risposta. # Se presente, sostituire immediatamente quello immagazzinato. # Se viene restituito un errore "invalid_grant", richiedere all'utente di effettuare nuovamente l'autenticazione.
Risoluzione dei problemi

Errori comuni di AADSTS decodificati

Gli errori di Microsoft Graph OAuth seguono uno schema coerente di codici di errore AADSTS. Questi sono quelli più comuni che incontrerai durante lo sviluppo e la produzione, con cause profonde e correzioni esatte.

Codice di errore Cosa significa Causa principale e correzione
AADSTS65001 Il consenso non è stato concesso per uno o più degli ambiti richiesti L'utente non ha concesso il consenso agli ambiti della tua app, oppure un amministratore del tenant ha bloccato il consenso dell'utente per la tua app. Soluzione: Includi consenso nell'URL di autorizzazione per forzare una schermata di consenso, o inviare l'URL di consenso dell'amministratore all'amministratore del tenant.
Aggiungi prompt=consenso o richiedi il consenso dell'amministratore
AADSTS50011 Errore di reindirizzamento URI Il uri_di_reindirizzamento la tua richiesta non corrisponde esattamente a nessun URI di reindirizzamento registrato nella tua registrazione dell'app Entra. Anche una differenza nella barra finale causa questo problema. Correzione: Copia l'URI esatto dalla tua registrazione dell'app Entra e utilizzalo esattamente come appare.
Correggi: corrispondenza esatta dell'URI nella registrazione dell'app Entra
AADSTS700016 Applicazione non trovata nell'utenza Il ID cliente non esiste nel tenant contro cui ci si sta autenticando. Comune quando si utilizza un'autorità specifica per il tenant (/{id-tenant}) per un'app multi-tenant. Correzione: Usa Comune o /organizzazioni autorità per app multi-tenant.
Correggi: passa all'autorità /common o /organizations
AADSTS90099 L'applicazione non è stata autorizzata in questo tenant (consent_required) L'app esiste ma non è stata acconsentita nel tenant dell'utente. Differisce da AADSTS65001 in quanto l'intera app è bloccata, non solo gli ambiti specifici. Soluzione: inviare l'URL di consenso dell'amministratore all'amministratore IT del cliente.
Correggi: URL di consenso dell'amministratore al tenant amministratore del cliente
AADSTS70011 Concessione non valida o scaduta Il token di aggiornamento o il codice di autorizzazione sono scaduti o sono stati revocati. I codici di autorizzazione scadono dopo 10 minuti. I token di aggiornamento scadono dopo 90 giorni di inattività o revoca da parte dell'amministratore. Soluzione: Richiedere all'utente di autenticarsi nuovamente dall'inizio del flusso OAuth.
Correggi: prompt autenticazione completa
AADSTS50076 L'MFA è richiesto dalla policy di accesso condizionale L'inquilino dell'utente richiede l'autenticazione a più fattori per la tua app. Questa è una decisione lato cliente imposta dall'amministratore dell'inquilino. La tua app non può aggirarla. L'utente deve completare l'MFA. Se si utilizza il flusso del codice di autenticazione, Microsoft visualizzerà automaticamente il prompt MFA nel browser. Sorgono problemi nei flussi automatizzati (credenziali client) che non possono completare l'MFA.
Previsto: l'utente deve completare l'MFA
AADSTS50020 L'account utente dal provider di identità esterno non esiste nel tenant L'utente sta tentando di autenticarsi con un account Microsoft personale in un tenant che consente solo account aziendali, o viceversa. Correzione: Controlla il tuo endpoint di autorizzazione - se stai usando /organizzazioni, gli account personali non possono autenticarsi. Passa a Comune se hai bisogno di entrambi.
Correggi: passa l'autorità a /common
AADSTS53003 Accesso bloccato da una policy di accesso condizionale La policy di Accesso Condizionale del tenant ha completamente bloccato questo tentativo di autenticazione (ad esempio, paese bloccato, dispositivo non gestito, app bloccata). Questa è una decisione lato cliente. Non puoi sovrascriverla. Comunica l'errore all'utente e consiglialo di contattare il proprio amministratore IT.
Lato cliente: consigliare all'utente di contattare l'amministratore IT
Lascia che Unipile gestisca tutto questo per te
L'Alternativa Unipile

Saltate 5 settimane di "idraulica" OAuth con Unipile

Tutto in questa guida - registrazione dell'app Entra, endpoint di autorizzazione, selezione degli ambiti, PKCE, rotazione dei token, gestione degli errori AADSTS - è tempo di ingegneria che non fa avanzare il tuo prodotto. Unipile gestisce l'intero stack OAuth di Microsoft Graph come servizio gestito, in modo che il tuo team scriva una chiamata API invece di 500 righe di codice per l'autenticazione OAuth.

Costruirlo da soli
Registrazione e configurazione dell'applicazione Entra
Implementazione PKCE e generazione del code challenge
Archiviazione, rotazione e gestione della scadenza del token di aggiornamento
Flusso di consenso dell'amministratore per i clienti aziendali
Gestione degli errori AADSTS e richieste di riautenticazione
Rotazione del segreto del client prima della scadenza
Gestione delle avvertenze di accesso condizionale per tenant
Stack OAuth separati per provider Gmail e IMAP
Usando Unipile
Un POST per generare un link di autenticazione ospitato
Unipile gestisce automaticamente PKCE, token e refresh
I token non vengono mai archiviati nel tuo database - Unipile se ne occupa
Stessa API per account Microsoft, Gmail e IMAP
Notifiche webhook quando gli account richiedono una riautenticazione
Schermata di consenso personalizzata con le tue credenziali dell'app Entra
Spedisci la tua integrazione email in ore, non in settimane
Come funziona l'OAuth Microsoft ospitato da Unipile
Il tuo backend chiama un endpoint per generare un link di autenticazione ospitato. L'utente fa clic su di esso, si autentica con Microsoft e Unipile gestisce l'intero flusso OAuth: reindirizzamento Entra, gestione degli scope, scambio di token e refresh. L'account collegato è quindi disponibile tramite l'API unificata di posta elettronica di Unipile.
unipile_microsoft_oauth.py
import richieste UNIPILE_API_URL = "https://apiXXX.unipile.com:XXX" CHIAVE_API_UNIPILE = "la tua-api-chiave" # Fase 1: Generare un link di autenticazione ospitato per Microsoft response = requests.posta( f"{UNIPILE_API_URL}/api/v1/hosted/accounts/link", intestazioni={ "X-API-KEY": UNIPILE_API_KEY, "Content-Type": "application/json" }, json={ "tipo": "creare", "fornitori": ["MICROSOFT"], "url_api": UNIPILE_API_URL, "scadenza": "2026-12-31T23:59:59Z", # (Opzionale): associa questo link a un utente specifico "nome": "id_utente_123", # (opzionale): ricevi una notifica quando l'account viene collegato "notify_url": "https://app.yourproduct.com/webhooks/account-linked" } ) # Fase 2: reindirizza l'utente a questo URL url_autenticazione_ospitata = risposta.json()["url"] Esempio #: https://account.unipile.com/[encoded-token] # Unipile gestisce: reindirizzamento Entra, schermata di consenso, PKCE, Scambio di token #, aggiornamento dell'archivio dei token, gestione dell'ambito # Fase 3: dopo l'autenticazione, utilizzare l'API e-mail di Unipile per leggere/inviare email = richieste.ottenere( f"{UNIPILE_API_URL}/api/v1/emails", intestazioni={"X-API-KEY"{UNIPILE_API_KEY}, parametri={"account_id": "id-account-collegato"} )
Microsoft OAuth completato. Casella di posta disponibile tramite API unificata.
Flusso di autenticazione ospitato
Unipile ospita la schermata di consenso OAuth. I tuoi utenti vedono un flusso brandizzato pulito. Nessuna manutenzione degli URI di reindirizzamento, nessun problema CORS, nessun aggiustamento di URL tra localhost e produzione.
Gestione dei token
Unipile memorizza e ruota i token OAuth di Microsoft per tuo conto. Il rinnovo dei token di aggiornamento, il monitoraggio dell'inattività di 90 giorni e le notifiche di riautenticazione vengono gestiti automaticamente.
API unificata per email
Dopo il collegamento, le caselle di posta Microsoft, Gmail e IMAP rispondono agli stessi endpoint email di Unipile. Un'integrazione serve tutti e tre i provider.
Le tue credenziali Entra
Configura le tue credenziali dell'app Microsoft Entra nella dashboard Unipile. I tuoi utenti vedranno il nome della tua app nella schermata di consenso di Microsoft, non quello di Unipile.
Notifiche webhook
Ricevi un webhook quando un account collegato richiede la riautenticazione (token di aggiornamento scaduto, revoca dell'amministratore, modifica di Accesso condizionale). Mostra immediatamente il prompt di riautenticazione nel tuo prodotto.
Leggi, invia e sincronizza
Dopo l'OAuth di Microsoft tramite Unipile, puoi leggere email, inviare email, sincronizzare thread, gestire cartelle e gestire allegati, tutto tramite l'API email unificata di Unipile. Nessun client Microsoft Graph separato è necessario.
Come funziona Unipile
Unipile è un intermediario tecnico indipendente che agisce per conto di ciascun utente autenticato tramite token OAuth rilasciati da Microsoft. Quando un utente collega la propria casella di posta Outlook o Microsoft 365, Unipile opera esclusivamente utilizzando le autorizzazioni delegate di quell'utente. Unipile non è affiliato, approvato o sponsorizzato da Microsoft. Utilizziamo l'API Microsoft Graph pubblica per conto degli utenti finali autenticati. Ciascun account opera all'interno dell'identità Microsoft Entra dell'utente e delle relative policy di accesso condizionale dell'organizzazione.
Inizia a costruire il tuo flusso di autenticazione OAuth di Microsoft Guida per le e-mail di MS Graph
FAQ

Domande frequenti

Le domande più comuni su Microsoft Graph OAuth per l'integrazione email, dalla selezione degli ambiti al ciclo di vita dei token fino ai flussi di consenso enterprise.

01
Microsoft Graph OAuth funziona sia per gli account Outlook.com che per gli account Microsoft 365?
Sì. Utilizzando il Comune endpoint di autorizzazione, una singola registrazione dell'app Microsoft Entra gestisce l'autenticazione sia per gli account Outlook.com personali che per gli account di lavoro/scuola Microsoft 365. La chiave è selezionare "Account in qualsiasi directory organizzativa e account Microsoft personali" durante la registrazione della tua app nel portale di Azure.
02
Quando un utente di Microsoft 365 lascia la propria azienda, i relativi token OAuth (token di accesso e token di aggiornamento) vengono invalidati o revocati. Questo avviene generalmente in due modi: 1. **Disabilitazione dell'account utente**: Quando un amministratore disabilita l'account dell'utente in Azure Active Directory (ora Microsoft Entra ID), ciò invalida immediatamente tutti i token di aggiornamento e di accesso associati a quell'account. Il sistema non riconoscerà più quei token per autenticare l'utente o le applicazioni per suo conto. 2. **Rimozione dell'account utente**: Se l'account viene eliminato, tutti i token associati vengono irrevocabilmente persi. In sintesi, i token OAuth non continuano a funzionare indefinitamente dopo che un utente ha lasciato un'organizzazione. La revoca e l'invalidazione sono processi automatici o attivati dagli amministratori per garantire la sicurezza dei dati e delle risorse aziendali.
Quando un amministratore IT disabilita o elimina un account utente in Microsoft Entra ID, tutti i token di aggiornamento di quell'utente vengono immediatamente revocati. Il tuo prossimo tentativo di aggiornamento del token restituirà un concessione_non_valida errore. Gestisci questo in modo appropriato: contrassegna l'account collegato come non autenticato e visualizza un chiaro prompt per la riautenticazione nel tuo prodotto. Questo è il comportamento previsto: una decisione lato cliente al di fuori del tuo controllo.
03
È richiesto il consenso dell'amministratore per leggere le e-mail di Outlook tramite OAuth di Microsoft Graph?
No, per le autorizzazioni Delegated standard. Posta.Leggi, Mail.ReadWrite, e Mail.Send sono ambiti di consenso dell'utente: i singoli utenti possono approvarli durante il flusso OAuth. Il consenso dell'amministratore è richiesto solo per le autorizzazioni dell'applicazione o per gli ambiti con privilegi elevati come Utente.Leggi.Tutto. Alcuni tenant aziendali configurano criteri che bloccano il consenso a tutte le app di terze parti, e questa è una decisione lato cliente.
04
Quanto durano i token di aggiornamento di Microsoft Graph?
I token di aggiornamento scadono dopo 90 giorni di inattività. Finché la tua app utilizza regolarmente il token di aggiornamento (cosa che avviene automaticamente durante l'aggiornamento dei token di accesso prima che scadano ogni 60-90 minuti), il token di aggiornamento rimane valido. Modifiche alle policy di accesso condizionale, reimpostazioni della password o revoche dell'amministratore possono invalidarli anticipatamente. Gestisci sempre concessione_non_valida errori e sostituire i vecchi token di refresh con quello nuovo restituito in ciascuna risposta del token.
05
Qual è la differenza tra AADSTS65001 e AADSTS90099?
AADSTS65001: L'utente non ha ancora acconsentito a uno o più ambiti specifici. Correzione: aggiungi consenso al tuo URL di autorizzazione per forzare una schermata di consenso aggiornata. AADSTS90099L'intera applicazione non è stata autorizzata in tale tenant: l'amministratore del tenant deve pre-approvare la tua app. Invia l'URL di consenso dell'amministratore all'amministratore IT del cliente. Entrambi gli errori sono comuni in scenari aziendali in cui i tenant limitano il consenso degli utenti.
06
È possibile utilizzare la stessa registrazione dell'app Entra per leggere e inviare e-mail?
Sì. Richiedi entrambi Mail.ReadWrite e Mail.Send nello stesso ambito della stringa. Notare che Mail.ReadWrite e Mail.Send sono ambiti separati: avere accesso in lettura/scrittura non concede automaticamente l'autorizzazione all'invio. Includere sempre accesso offline per assicurarti di ricevere un token di aggiornamento. Vedi il pagina API email per i dettagli di implementazione.
07
Unipile memorizza i token OAuth di Microsoft nel tuo database?
No. Quando si utilizza il flusso di autenticazione Microsoft ospitato da Unipile, Unipile gestisce tutti i token OAuth per tuo conto. La tua applicazione non gestisce mai direttamente i token di accesso o i token di aggiornamento di Microsoft. Interagisci con gli account collegati esclusivamente tramite l'API email unificata di Unipile utilizzando la tua chiave API Unipile. Ciò elimina le richieste di archiviazione, rotazione e sicurezza dei token dalla tua infrastruttura.
08
Unipile è affiliata a Microsoft?
No. Unipile non è affiliato, approvato o sponsorizzato da Microsoft. Unipile è un intermediario tecnico indipendente che utilizza l'API pubblica Microsoft Graph per conto di utenti finali autenticati. Ogni integrazione opera tramite token OAuth emessi da Microsoft, sotto l'identità del singolo utente e le policy di Conditional Access della loro organizzazione. Microsoft Graph e Microsoft Entra sono marchi registrati di Microsoft Corporation.
Avete ancora domande? Il nostro team può guidarti attraverso Microsoft Graph OAuth per il tuo caso d'uso specifico.
it_ITIT
en_USEN fr_FRFR es_ESES de_DEDE pt_BRBR nl_NLNL pl_PLPL tr_TRTR it_ITIT