Nu bouwen

Microsoft Graph OAuth: Authenticeer Outlook en Microsoft 365 Mailboxes (Handleiding 2026)

Microsoft Graph OAuth 2026

Microsoft Graph OAuthOutlook- en Microsoft 365-e-mailaccounts verifiëren

Een complete gids voor 2026 voor Microsoft Graph OAuth voor SaaS-ontwikkelaars. Behandelt Microsoft Entra-appregistratie, autoriteit-endpoints, mail-scopes, gedelegeerde versus applicatiemachtigingen, beheerdersgoedkeuring, autorisatiecode + PKCE, rotatie van vernieuwingstokens, AADSTS-foutcodes, en hoe Unipile 5 weken aan OAuth-installatie in 5 minuten elimineert.

Bouw het met Unipile MS Graph Gids
link_outlook_account.py
importeer verzoekt # Stap 1: Een gehoste authenticatielink genereren response = requests.post( "https://apiXXX.unipile.com:XXX /api/v1/hosted/accounts/koppelen", headers={"X-API-SLEUTEL": api_key}, json={ "type": "maken", "providers": ["MICROSOFT"], "api_url": jouw_dsn, "verlooptOp": "2026-12-31T23:59:59Z" } ) # Stap 2: Leid je gebruiker om naar de URL auth_url = response.json()["url"] # Unipile verzorgt de volledige OAuth-procedure # incl. Entra, scopes, tokens, vernieuwing
Microsoft OAuth afgehandeld. Mailbox klaar.
2026 Context

Waarom Microsoft Graph OAuth in 2026 niet onderhandelbaar is

Als uw SaaS-applicatie e-mail van Outlook of Microsoft 365 leest, verzendt of synchroniseert, is Microsoft Graph OAuth niet langer optioneel. Drie belangrijke verouderingen hebben Basic Auth, verouderde protocollen en wachtwoorden voor apps overbodig gemaakt. OAuth 2.0 via de Microsoft Graph API is de enige ondersteunde methode.

Basic Auth - Volledig verouderd
Microsoft heeft basic authenticatie voor Exchange Online in oktober 2022 uitgeschakeld. Dit beïnvloedt IMAP, POP3, SMTP, EWS, MAPI, OAB, Outlook Anywhere en RPC over HTTP. Er zijn geen uitzonderingen en er zijn geen respijtperiodes meer beschikbaar.
Uitgeschakeld okt 2022
EWS - Tijdlijn Zonsondergang
Exchange Web Services (EWS) is in onderhoudsmodus. Microsoft heeft aangekondigd geen nieuwe functies meer te zullen uitbrengen en raadt aan te migreren naar Microsoft Graph. Hoewel het nog niet volledig is stopgezet, zal het bouwen van nieuwe integraties op EWS in 2026 een technische schuld zijn waar u spijt van zult krijgen.
Onderhoudsmodus
OAuth 2.0 - De Vereiste Standaard
Microsoft Graph OAuth via Microsoft Entra ID (voorheen Azure AD) is de enige officieel ondersteunde authenticatiemethode voor productie SaaS-applicaties die in 2026 toegang krijgen tot Outlook en Microsoft 365 mailboxen. Deze gids behandelt de volledige implementatie.
Vereiste norm
Wat Microsoft Graph OAuth ontgrendelt
Lees, verzend en synchroniseer Outlook-mailboxen namens geauthenticeerde gebruikers
Toegang tot Microsoft 365 en persoonlijke Outlook.com-postvakken met één app-registratie
Langdurige vernieuwingstokens met automatische rotatie (geen herauthenticatie voor actieve gebruikers)
Granulaire toegangscontrole: vraag alleen de machtigingen aan die je app echt nodig heeft
Ondersteuning voor meerdere tenants: één app-registratie bedient alle klantent ODER Multi-tenant ondersteuning: één app registratie dient alle klantent
Naleving van bedrijfsregels voor voorwaardelijke toegang en meervoudige verificatie
OAuth-stromen

De 3 OAuth-stromen die Microsoft ondersteunt (en welke SaaS nodig heeft)

Microsoft's identiteitsplatform ondersteunt verschillende OAuth 2.0-autorisatietypes. Het kiezen van de verkeerde is een veelvoorkomende oorzaak van verspilde ontwikkeltijd. Hier is de uitleg voor SaaS-toepassingen die namens hun gebruikers toegang krijgen tot e-mail.

Aanbevolen voor SaaS
Autorisatiecode + PKCE
RFC 6749 Sectie 4.1 + RFC 7636
De gebruiker wordt omgeleid naar de Microsoft-inlogpagina, verifieert zich en geeft toestemming. Uw app wisselt de geretourneerde autorisatiecode in voor toegangs- en vernieuwingstokens. PKCE (Proof Key for Code Exchange) voorkomt aanvallen met codeonderschepping en is verplicht voor publieke clients en aanbevolen voor alle clients in 2026.
Gebruik dit voor SaaS-apps die toegang krijgen tot gebruikers-e-mailboxen
Clientreferenties
OAuth 2.0 Sectie 4.4 (alleen-app)
Geen gebruikersinteractie. Uw app authenticeert zichzelf met een client-ID en geheim (of certificaat). Vereist Toepassingsmachtigingen (geen Gedelegeerde), wat betekent dat een tenantbeheerder toestemming moet verlenen om toegang te krijgen tot alle postvakken in de organisatie. Geen scherm voor gebruikersgoedkeuring.
Alleen voor interne tooling met toegang verleend door beheerders
Apparaatcode-stroom
OAuth 2.0 apparaatmachtigingsverlening
Ontworpen voor apparaten zonder browser (CLIs, IoT, smart-tv's). De gebruiker bezoekt een URL op een ander apparaat om te authenticeren. Niet relevant voor SaaS-webapplicaties waarbij een omleiding mogelijk is.
Niet van toepassing op standaard SaaS-webapps
Begin met het bouwen van uw Microsoft OAuth-stroom
Unipile - Microsoft Entra App Registratie
Stapsgewijze installatie

Microsoft Entra App Registratie: 7 Stappen

Voordat uw app OAuth-tokens kan aanvragen, moet u een geregistreerde toepassing hebben in Microsoft Entra ID (voorheen Azure Active Directory). Hier zijn de exacte stappen, inclusief welke veldwaarden belangrijk zijn en welke cosmetisch zijn.

1
Maak een appregistratie in het Azure-portaal
Navigeer naar portal.azure.com, ga naar Microsoft Entra ID (zoek in de bovenste balk), dan Appregistraties, klik dan + Nieuwe registratie. Zie de Volledige Microsoft OAuth-documentatie voor extra context.
Naam
Jouw app-naam. Dit is wat gebruikers zien op het Microsoft-toestemmingsscherm. Gebruik je productnaam, geen technische identificatie.
Ondersteunde accounttypes
Voor een multi-tenant SaaS die zowel zakelijke als persoonlijke gebruikers bedient: selecteer Accounts in elke organisatiedirectory (elke Microsoft Entra ID-tenant - multitenant) en persoonlijke Microsoft-accounts. Dit komt overeen met de /gemeenschappelijk autoriteit eindpunt.
Tip: Als u alleen Microsoft 365 zakelijke accounts (geen persoonlijke Outlook.com) bedient, selecteert u alleen "Multitenant". Dit maakt gebruik van de /organisaties autoriteit en verkleint uw contactvlak voor toestemming. Meer over autoriteit-eindpunten in sectie 4.
2
Configureer omleidings-URI's
Na registratie, ga naar Authenticatie in het linkerpaneel. Voeg een platform toe: selecteer Web. Voeg uw omleidings-URI('s) toe, de URL waarnaar Microsoft de gebruiker terugstuurt met de autorisatiecode.
Platformtype
Web voor server-side apps. Gebruik Applicatie met één pagina voor client-side flows (schakelt PKCE automatisch in).
Omleidings URI
Moet HTTPS zijn in productie. Voorbeeld: https://app.yourproduct.com/auth/microsoft/callback. Exacte overeenkomst vereist, elke afwijking veroorzaakt AADSTS50011.
Uitlog-URL (optioneel)
Microsoft zal deze URL aanroepen wanneer de gebruiker zich afmeldt bij een app in hun tenant. Optioneel voor alleen-e-mailintegraties.
Veelvoorkomende fout: localhost URI's zijn toegestaan tijdens de ontwikkeling (http://localhost:3000/callback) maar productie URI's moeten HTTPS gebruiken. Registreer beide afzonderlijk.
3
Microsoft Graph API-machtigingen toevoegen
Ga naar API-machtigingen. Klik + Een machtiging toevoegen, selecteren Microsoft Graph, dan Gedelegeerde machtigingen. Voeg de scopes toe die je app nodig heeft.
Minimum om te lezen
Mail.lezen, offline_access, openid, profiel
Voor lezen + verzenden
Mail.ReadWrite, Mail.verzenden, offline_access, openid, profiel
offline_access
Cruciaal. Zonder deze scope geeft Microsoft geen vernieuwingstoken uit. Uw gebruikers moeten zich elke 60-90 minuten opnieuw authenticeren.
Opmerking: Het toevoegen van permissies hier verleent ze niet, maar verklaart uw intentie. De gebruiker geeft toestemming wanneer zij de OAuth-flow voltooien. Admin-toestemming is vereist voor enkele scopes met hogere privileges (zie sectie 7).
4
Genereer een clientgeheim
Ga naar Certificaten en geheimen. Klik + Nieuw clientgeheim. Stel een beschrijving en verlopen in.
Vervaldatumadvies
730 dagen (24 maanden) is het maximum. Stel een agendaherinnering in 60 dagen voor het verlopen, willekeurig een verlopen geheim roteren veroorzaakt onmiddellijke authenticatiefouten bij alle gebruikers.
Kopieer de waarde onmiddellijk
De geheime waarde wordt slechts één keer weergegeven. Sla deze op in uw secrets manager (bijv. AWS Secrets Manager, HashiCorp Vault, Azure Key Vault). Deze zal nooit meer worden weergegeven nadat u deze pagina verlaat.
Aanbevolen alternatief: Gebruik voor productie een certificaat in plaats van een clientgeheim. Certificaten zijn veiliger (asymmetrische sleutel), verlopen nooit per ongeluk en hebben de voorkeur van Microsoft voor apps van bedrijfsniveau.
5
Kopieer uw client-ID en tenant-ID
Van de Overzicht pagina van uw app-registratie, kopieer twee waarden die u in elke OAuth-aanvraag nodig hebt:
Applicatie (client) ID
Een UUID die uw app-registratie uniek identificeert. Wordt gebruikt als de klant_id parameter in alle authenticatieverzoeken.
Directory (tenant) ID
De tenant-id van uw organisatie. Wordt gebruikt in autorisatie-URL's met één tenant. Voor multi-tenantapps gebruikt u /gemeenschappelijk in plaats daarvan, maar behoud deze waarde voor beheerdersgoedkeurings-URL's.
6
Schakel ID-tokens in (optioneel maar aanbevolen)
Terug in Authenticatie, onder Impliciete machtiging en hybride stromen, je kunt inschakelen ID-tokens. Dit laat je een JWT ontvangen met identiteitsclaims van de gebruiker (naam, e-mail, tenant-ID) naast de toegangstoken, handig voor onboarding-stromen waarbij je de gegevens van het gebruikersprofiel wilt vooraf invullen.
2026 richtlijn: Voor pure auth-code + PKCE flows worden ID-tokens geretourneerd via het token-eindpunt, niet via impliciete toekenning. U hoeft geen impliciete toekenning in te schakelen. Schakel deze alleen in als u een verouderde SPA hebt die PKCE niet kan gebruiken.
7
Optioneel: Verifieer uw uitgeversdomein
In Merkidentiteit en eigenschappen, stel uw uitgeversdomein in op het domein van uw product. Dit vervangt het label "niet geverifieerd" op het toestemmingsscherm door uw domeinnaam. Voor multitenant-apps gericht op zakelijke klanten, verwijdert het voltooien van de Microsoft Partner Network-verificatie en het worden van een "geverifieerde uitgever" de prominente waarschuwing "Deze app wordt niet vaak gebruikt".
Uitgeversdomein
Een domein dat u bezit en dat u hebt geverifieerd via een TXT-record of via de App Service-domeinvalidatiestroom.
Geverifieerde uitgever
Vereist een Microsoft Partner Network (MPN) ID die gekoppeld is aan een geverifieerde zakelijke identiteit. Duurt 1-5 werkdagen. Verbetert de conversie van zakelijke klanten op toestemmingsschermen aanzienlijk.
Sla de installatie over: bouw in plaats daarvan met Unipile
Autoriteit Endpoints

Het Kiezen van de Juiste Microsoft Authoriteit Endpoint

De autoriteits-URL die u gebruikt in uw OAuth-verzoeken bepaalt welke soorten Microsoft-accounts kunnen authenticeren en welke tokens u ontvangt. Als u dit verkeerd krijgt, treden er stille fouten op waarbij sommige gebruikers helemaal niet kunnen authenticeren.

Autoriteits-URL Accepteert Gebruikscasus Voorbehouden
/gemeenschappelijkMeeste SaaS Zowel Microsoft Entra (werk/school) als persoonlijke Microsoft-accounts (Outlook.com, Hotmail, Live) Multi-tenant SaaS dat alle Microsoft-gebruikers bedient. Eén eindpunt beheert uw gehele gebruikersbestand. Tokens worden uitgegeven door de thuis tenant van elke gebruiker, niet door de jouwe. Tokenvalidatie moet tenant-specifieke uitgevers gebruiken of meerdere uitgevers accepteren. Kan Geen Voorwaardelijke Toegang-beleid afdwingen.
/organisaties Alleen Microsoft Entra ID-accounts (werk/school). Geen persoonlijke Microsoft-accounts. B2B SaaS gericht uitsluitend op zakelijke klanten, nooit consumenten Outlook.com-gebruikers. Gebruikers met persoonlijke Microsoft-accounts zullen een foutmelding ontvangen. Eenvoudigere tokenvalidatie (single issuer patroon acceptabel).
consumenten Alleen persoonlijke Microsoft-accounts (Outlook.com, Hotmail, Live). Consumentenapps gericht op persoonlijke inboxen. Zeldzaam voor B2B SaaS. Enterprise Microsoft 365-accounts worden afgewezen. Niet bruikbaar voor SaaS die zakelijke gebruikers bedient.
/{tenant-id} Accounts in een specifieke Microsoft Entra-tenant alleen. Single-tenant interne tools (een app van je eigen bedrijf). Admin consent-stromen gericht op een specifieke tenant. Wordt ook gebruikt in het admin consent redirect URL-patroon. Elke andere gebruiker van de huurder wordt geweigerd. Alleen geschikt voor interne apps of wanneer bewust vergrendeld op de tenant van één klant.
/gemeenschappelijk Meeste SaaS
Accepteert Zowel Microsoft Entra (werk/school) als persoonlijke Microsoft-accounts (Outlook.com, Hotmail, Live)
Gebruikssituatie Multi-tenant SaaS dat alle Microsoft-gebruikers bedient. Eén eindpunt beheert uw gehele gebruikersbestand.
Voorbehouden Tokens worden uitgegeven door de thuis tenant van elke gebruiker, niet door de jouwe. Tokenvalidatie moet tenant-specifieke uitgevers gebruiken of meerdere uitgevers accepteren. Kan Geen Voorwaardelijke Toegang-beleid afdwingen.
/organisaties
Accepteert Alleen Microsoft Entra ID-accounts (werk/school). Geen persoonlijke Microsoft-accounts.
Gebruikssituatie B2B SaaS gericht uitsluitend op zakelijke klanten, nooit consumenten Outlook.com-gebruikers.
Voorbehouden Gebruikers met persoonlijke Microsoft-accounts zullen een foutmelding ontvangen. Eenvoudigere tokenvalidatie (single issuer patroon acceptabel).
consumenten
Accepteert Alleen persoonlijke Microsoft-accounts (Outlook.com, Hotmail, Live).
Gebruikssituatie Consumentenapps gericht op persoonlijke inboxen. Zeldzaam voor B2B SaaS.
Voorbehouden Enterprise Microsoft 365-accounts worden afgewezen. Niet bruikbaar voor SaaS die zakelijke gebruikers bedient.
/{tenant-id}
Accepteert Accounts in een specifieke Microsoft Entra-tenant alleen.
Gebruikssituatie Single-tenant interne tools (een app van je eigen bedrijf). Admin consent-stromen gericht op een specifieke tenant. Wordt ook gebruikt in het admin consent redirect URL-patroon.
Voorbehouden Elke andere gebruiker van de huurder wordt geweigerd. Alleen geschikt voor interne apps of wanneer bewust vergrendeld op de tenant van één klant.
Tokenvalidatie-opmerking voor /common: Wanneer u de /gemeenschappelijk eindpunt, de is claim in the JWT zal zijn https://login.microsoftonline.com/{tenantId}/v2.0 waar {tenantId} varieert per gebruiker. Configureer uw JWT-validatiebibliotheek om elke issuer te accepteren die overeenkomt met https://login.microsoftonline.com/{tenantId}/v2.0 in plaats van een vaste afzenderreeks.
Mailbereik

Microsoft Graph Mail Scopes: Gedetailleerde Uitsplitsing

Microsoft Graph gebruikt toestemmingsbereiken (scopes) om te bepalen wat uw toepassing kan doen. Te veel bereiken aanvragen vergroot de wrijving op het toestemmingsscherm en vermindert de conversie. Te weinig aanvragen leidt tot runtimefouten. Hier zijn alle Mail-bereiken die u moet weten.

Reikwijdte Type Wat het mogelijk maakt Admin toestemming?
Mail.lezen Gedelegeerd Lees alle berichten in de mailbox van de geauthenticeerde gebruiker. Inclusief headers, body, bijlagen. Alleen-lezen - kan niet wijzigen of verzenden. Gebruiker
Mail.LezenBasis Gedelegeerd Lees beperkte bericht-eigenschappen: onderwerp, afzender, ontvangers, datum. Kan bericht-inhoud of bijlagen niet lezen. Nuttig voor een lichtgewicht inbox-lijst zonder volledige inhouds-toegang. Gebruiker
Mail.ReadWrite Gedelegeerd Alle berichten lezen en bewerken. Inclusief het aanmaken, bijwerken en verwijderen van berichten en mappen. Superset van Mail.Read - vraag niet beide aan. Gebruiker
Mail.verzenden Gedelegeerd Verzend e-mails als de geauthenticeerde gebruiker. Vereist, zelfs als je ook Mail.ReadWrite hebt - verzenden is een aparte machtiging in Microsoft Graph. Gebruiker
Mail.Read.Shared Gedelegeerd E-mail lezen in gedeelde postvakken of postvakken van andere gebruikers waartoe de geauthenticeerde gebruiker toegang heeft gekregen. Niet voor het lezen van het eigen postvak van de gebruiker. Gebruiker
Mail.LeesSchrijf.Gedeeld Gedelegeerd E-mails lezen en wijzigen in gedeelde postvakken waartoe de gebruiker toegang heeft. Gebruiker
E-mail.Verzenden.Gedeeld Gedelegeerd E-mail verzenden vanuit gedeelde postbussen of "verzenden namens" een andere gebruiker (als die gebruiker toegang heeft verleend). Gebruiker
offline_access Gedelegeerd Instrueert Microsoft om een vernieuwingstoken uit te geven. Zonder dit ontvangt u alleen een kortstondig toegangstoken waarmee het niet kan worden vernieuwd. Altijd vereist voor SaaS-toepassingen. Gebruiker
openid Gedelegeerd Geeft een ID-token terug met basale gebruikeridentificatie. Vereist als je wilt weten wie er is geauthenticeerd zonder een aparte /me API-aanroep te doen. Gebruiker
profiel Gedelegeerd Voegt de claims name en preferred_username toe aan de ID-token. Meestal inbegrepen bij openid. Gebruiker
E-mail.Lezen (App) Toepassing Lees alle e-mail in alle postvakken in de tenant zonder gebruikersinteractie. Gebruikt door daemon-services. Vereist tenantadministrator-toestemming. Admin vereist
Mail.LezenSchrijven (App) Toepassing Lees en schrijf alle e-mails in alle postbussen van tenants. Zeer brede toestemming. Alleen voor vertrouwd intern gereedschap met expliciete goedkeuring van de tenant-administrator. Admin vereist
Mail.lezen Gedelegeerd
Lees alle berichten in de mailbox van de geauthenticeerde gebruiker. Inclusief headers, body, bijlagen. Alleen-lezen - kan niet wijzigen of verzenden.
Gebruikersinstemming
Mail.LezenBasis Gedelegeerd
Lees beperkte bericht-eigenschappen: onderwerp, afzender, ontvangers, datum. Kan bericht-inhoud of bijlagen niet lezen. Nuttig voor een lichtgewicht inbox-lijst zonder volledige inhouds-toegang.
Gebruikersinstemming
Mail.ReadWrite Gedelegeerd
Alle berichten lezen en bewerken. Inclusief het aanmaken, bijwerken en verwijderen van berichten en mappen. Superset van Mail.Read - vraag niet beide aan.
Gebruikersinstemming
Mail.verzenden Gedelegeerd
Verzend e-mails als de geauthenticeerde gebruiker. Vereist, zelfs als je ook Mail.ReadWrite hebt - verzenden is een aparte machtiging in Microsoft Graph.
Gebruikersinstemming
Mail.Read.Shared Gedelegeerd
E-mail lezen in gedeelde postvakken of postvakken van andere gebruikers waartoe de geauthenticeerde gebruiker toegang heeft gekregen. Niet voor het lezen van het eigen postvak van de gebruiker.
Gebruikersinstemming
Mail.LeesSchrijf.Gedeeld Gedelegeerd
E-mails lezen en wijzigen in gedeelde postvakken waartoe de gebruiker toegang heeft.
Gebruikersinstemming
E-mail.Verzenden.Gedeeld Gedelegeerd
E-mail verzenden vanuit gedeelde postbussen of "verzenden namens" een andere gebruiker (als die gebruiker toegang heeft verleend).
Gebruikersinstemming
offline_access Gedelegeerd
Instrueert Microsoft om een vernieuwingstoken uit te geven. Zonder dit ontvangt u alleen een kortstondig toegangstoken waarmee het niet kan worden vernieuwd. Altijd vereist voor SaaS-toepassingen.
Gebruikersinstemming
openid Gedelegeerd
Geeft een ID-token terug met basale gebruikeridentificatie. Vereist als je wilt weten wie er is geauthenticeerd zonder een aparte /me API-aanroep te doen.
Gebruikersinstemming
profiel Gedelegeerd
Voegt de claims name en preferred_username toe aan de ID-token. Meestal inbegrepen bij openid.
Gebruikersinstemming
E-mail.Lezen (App) Toepassing
Lees alle e-mail in alle postvakken in de tenant zonder gebruikersinteractie. Gebruikt door daemon-services. Vereist tenantadministrator-toestemming.
Admin vereist
Mail.LezenSchrijven (App) Toepassing
Lees en schrijf alle e-mails in alle postbussen van tenants. Zeer brede toestemming. Alleen voor vertrouwd intern gereedschap met expliciete goedkeuring van de tenant-administrator.
Admin vereist
Minimale reikwijdte set: inbox reader
scope=Mail.Readoffline_accessopenidprofile
Berichten lezen, tokens vernieuwen, gebruikersidentiteit. Geen schrijf- of verzendmogelijkheden.
Standaard scope ingesteld: volledige e-mailintegratie
scope=Mail.ReadWriteMail.Sendoffline_accessopenidprofile
Lezen, schrijven, verzenden. De meest voorkomende set voor CRM- en verkooptoolintegraties.
Bekijk de volledige gids over de E-mail API
Machtigingenmodel

Gedelegeerde versus toepassingsmachtigingen: wanneer elke van toepassing is

Microsoft Graph gebruikt twee fundamenteel verschillende machtigingsmodellen. De meeste SaaS-ontwikkelaars kiezen standaard voor het verkeerde model, wat leidt tot onnodige vereisten voor beheerdersgoedkeuring en een slechte gebruikerservaring. Hier lees je precies wanneer je elk model moet gebruiken.

Gedelegeerde machtigingen
Handelen namens de aangemelde gebruiker
De app krijgt toegang tot Microsoft Graph met de identiteit van de geauthenticeerde gebruiker. De app kan alleen doen wat de gebruiker zelf zou kunnen doen. Als de gebruiker een map niet kan lezen, kan uw app dat ook niet.
Gebruiker stemt in tijdens OAuth-stroom - geen beheerder vereist voor standaardbereiken
Toegang is beperkt tot de mailbox van elke individuele gebruiker
Gebruikers kunnen toegang te allen tijde intrekken via de instellingen van hun Microsoft-account
Respecteert machtigingen op gebruikersniveau, roltaken en e-mailtoegangsbeleidslijnen
Gebruik dit voor SaaS-applicaties waarbij elke gebruiker individueel authenticeert
Toepassingsmachtigingen
Gedraag je als de applicatie zelf
De app heeft toegang tot Microsoft Graph zonder dat er een gebruiker aanwezig is. Gebruikt voor achtergrondservices, daemons en geautomatiseerde workflows. De app authenticeert met zijn eigen inloggegevens (client credentials-stroom).
Vereist goedkeuring van de tenantbeheerder - een aanzienlijke drempel voor externe gebruikers
Toegang is tenant-breed - kan ALLE postvakken lezen nadat de beheerder toestemming heeft gegeven
Geen interactieve gebruikersaanmelding vereist - werkt voor headless automatisering
Geschikt voor interne IT-tools waar de beheerder van uw organisatie de implementatie beheert
Alleen voor interne tooling waarbij de beheerder van uw organisatie volledige toegang tot de tenant verleent
De SaaS-beslissingsregel
Als je een bouwt product gebruikt door externe klanten wie zich individueel aanmeldt, gebruikt Gedelegeerde machtigingen. Elke klant authenticeert zich met zijn eigen Microsoft-account, geeft toestemming voor de scopes van uw app en uw app opereert namens die geauthenticeerde gebruiker. Toepassingsmachtigingen vereisen dat een tenantbeheerder uw app vooraf goedkeurt voor hun hele organisatie - een conversie-dodende stap in een selfservice SaaS-funnel. De enige uitzondering is als u een intern bedrijfstool bouwt die door uw eigen IT-team binnen uw eigen tenant wordt geïmplementeerd.
Volledige walkthrough

Auth Code + PKCE: Stap-voor-stap Curl Voorbeelden

Hier is de volledige Microsoft Graph OAuth 2.0-autorisatiecodestroom met PKCE, van het genereren van de codeverifieerder tot het uitwisselen van tokens. Dit zijn productierijpe voorbeelden die u direct kunt aanpassen aan uw stack.

Stap 1 van 4 - Genereer PKCE-parameters
Genereer code_verifier en code_challenge
PKCE werkt door een willekeurig geheim (code_verifier) te genereren, vervolgens een SHA-256 hash daarvan (code_challenge). Je stuurt de uitdaging in stap 2 en de verificatie in stap 4. Microsoft controleert of ze overeenkomen, wat code-onderschepping voorkomt.
pkce_genereer.py
importeer os, base64, hashlib # 1. Genereer code_verifier (43-128 tekens, URL-veilige Base64) code_verifier = base64.urlsafe_b64encode( os.willekeurig(32) ).ontcijfer('utf-8').rstrip('=') # 2. Genereer code_challenge = BASE64URL(SHA256(code_verifier)) code_uitdaging = base64.urlsafe_b64encode( hashlib.sha256(gecodeerde_verificatie.coderen('utf-8')).verteren() ).ontcijfer('utf-8').rstrip('=') # Sla code_verifier op in de sessie – je hebt deze nodig in stap 4 # Verzend code_challenge in de autorisatie-URL
Stap 2 van 4 - Autorisatieverzoek
Bouw de /authorize URL en stuur de gebruiker door
Leid de browser van de gebruiker om naar het autorisatie-eindpunt van Microsoft. De gebruiker ziet de aanmeldpagina van Microsoft, authenticeert zich en geeft toestemming voor de bereiken van uw app. Microsoft stuurt vervolgens een autorisatiecode terug naar uw redirect_uri.
klant_id
Uw Applicatie (client) ID uit Entra app-registratie
reactietype
code - vraagt om een autorisatiecode
omleiding_uri
Moet exact overeenkomen met een URI die is geregistreerd in je Entra-app. URL-gecodeerd.
bereik
Spatie-gescheiden lijst. Altijd inclusief offline_access voor vernieuwingstokens.
staat
Ondoorzichtige waarde die je genereert. Onveranderd teruggegeven in de callback. Gebruik het om CSRF te voorkomen en de UI-status te herstellen.
code_uitdaging
De BASE64URL(SHA256(code_verifier))-waarde uit stap 1.
code_uitdagingsmethode
S256 - gebruik altijd SHA-256, nooit plat
authorize_url.sh
# Stel de autorisatie-URL samen (in een overzichtelijke indeling) AUTH_URL="https://login.microsoftonline.com/common/oauth2/v2.0/authorize ?client_id=JOUW_CLIENT_ID &response_type=code &redirect;_uri=https://3aapp.com/3aauth/3ams/3acb &scope;=Mail.ReadWriteMail.Sendoffline_access &staat=WIILLEKEURIGE_STAATSWAARDE &code_challenge=JOUW_CODE_UITDAGING &code_challenge_method=S256" # De gebruiker doorverwijzen naar $AUTH_URL # Microsoft verzorgt de aanmelding, MFA en het toestemmingsscherm # Bij succes: redirect_uri?code=AUTH_CODE&state;=...
Stap 3 van 4 - Verwerk de Callback
Ontvang de autorisatiecode op uw redirect_uri
Microsoft stuurt door naar uw redirect_uri met een code query parameter. Valideer de staat parameter komt overeen met wat je hebt gestuurd. De code verloopt over 10 minuten - wissel deze onmiddellijk in bij stap 4.
Stap 4 van 4 - Tokenuitwisseling
Ruil de autorisatiecode in voor access- en refresh-tokens.
POST naar het token-eindpunt met de code en je code_verifier. Microsoft retourneert een toegangstoken (geldig voor ~60-90 minuten) en een refresh token (langdurig). Sla beide veilig op.
token_uitwisseling.sh
#-uitwisselingsautorisatiecode voor tokens curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=JOUW_CLIENT_ID" \ -d "client_secret=JOUW_CLIENT_GEHEIM" \ -d "grant_type=authorization_code" \ -d "code=AUTH_CODE_VAN_CALLBACK" \ -d "redirect_uri=https://app.com/auth/ms/cb" \ -d "code_verifier=JOUW_CODE_VERIFIER" \ -d "scope=Mail.ReadWrite Mail.Send offline_access"
Retourneert: access_token, refresh_token, expires_in, scope
token_antwoord.json
{ "token_type": "Houder", "bereik": "Mail.LezenSchrijven Mail.Verzenden offline_toegang", "verloopt_in": 3600, "toegangstoken": "eyJ0eXAiOiJKV1Qi...", "vernieuwings_token": "0.ARoAi7W...", "id_token": "eyl0eXAi..." }
Token Levenscyclus

Vernieuwingstokenbeheer: rotatie, verlopen en voorwaardelijke toegang

Microsoft Graph-vernieuwings-tokens zijn langdurig, maar niet permanent. Verschillende omstandigheden kunnen ze stilzwijgend ongeldig maken. Het begrijpen van deze randgevallen is wat een hoogwaardige Microsoft OAuth-integratie onderscheidt van een die willekeurig faalt voor zakelijke gebruikers.

90 dagen inactief verlopen
Microsoft ververstokens verlopen na 90 dagen inactiviteit. Als een gebruiker uw app 90 dagen niet gebruikt, wordt hun ververstoken ongeldig en moeten ze opnieuw authenticeren. Er is geen manier om dit te verlengen zonder interactie van de gebruiker. Handel altijd ongeldige_verlening verwerkt fouten gracieus en vraagt om herauthenticatie.
Conditional Access-beleidswijzigingen
Enterprise-tenants gebruiken voorwaardelijke toegang beleidslijnen (MFA-vereisten, apparaatnaleving, locatiebeperkingen). Als een beleid wordt gewijzigd na authenticatie van een gebruiker, kan hun vernieuwingstoken ongeldig worden bevonden bij het volgende gebruik. Dit is een beslissing aan de kant van de klant - u kunt dit niet beheersen of voorspellen. Zend authenticatiefouten altijd terug naar gebruikers met een duidelijke prompt voor herauthenticatie.
Vernieuwingstokens rotatie
Wanneer u een vernieuwingstoken gebruikt om een nieuw toegangstoken te verkrijgen, kan Microsoft een nieuw vernieuwingstoken uitgeven. Sla altijd het nieuwe vernieuwingstoken uit het antwoord op en vervang het oude. Als u het oude vernieuwingstoken blijft gebruiken nadat het is geroteerd, krijgt u uiteindelijk te maken met een ongeldige_verlening fout.
Intrekken van beheerdersrechten
Een tenantbeheerder kan op elk moment alle vernieuwingstokens voor een gebruiker of de hele organisatie intrekken (bijvoorbeeld wanneer een medewerker vertrekt of tijdens een beveiligingsincident). Je app ontvangt ongeldige_verlening. Dit is verwacht gedrag - handel dit af door het gekoppelde account te markeren als opnieuw te autoriseren.
ververs_token.sh
# Vernieuw het toegangstoken met behulp van het opgeslagen vernieuwingstoken curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=JOUW_CLIENT_ID" \ -d "client_secret=JOUW_CLIENT_GEHEIM" \ -d "grant_type=refresh_token" \ -d "verversings_token=OPGESLAGEN_VERVERSINGS_TOKEN" \ -d "scope=Mail.ReadWrite Mail.Send offline_access" # Controleer ALTIJD of er een nieuw refresh_token in het antwoord staat. # Indien aanwezig, vervang dan onmiddellijk het opgeslagen exemplaar. # Als je de foutmelding `invalid_grant` krijgt, vraag de gebruiker dan om zich opnieuw te authenticeren.
Probleemoplossing

Veelvoorkomende AADSTS-fouten uitgelegd

Microsoft Graph OAuth-fouten volgen een consistent AADSTS-foutcodepatroon. Dit zijn de meest voorkomende fouten die u tijdens de ontwikkeling en productie zult tegenkomen, met exacte oorzaken en oplossingen.

Foutcode Wat het betekent Oorzaak en oplossing
AADSTS65001 Er is geen toestemming verleend voor een of meer van de aangevraagde bereiken De gebruiker heeft geen toestemming gegeven voor de bereiken van uw app, of een tenantbeheerder heeft toestemming van gebruikers voor uw app geblokkeerd. Oplossing: Inclusief toestemming in uw autorisatie-URL om een nieuwe toestemmingsscherm af te dwingen, of de admin-toestemmings-URL naar de tenant-beheerder te sturen.
Prompt=toestemming of vraag om beheerdersgoedkeuring
AADSTS50011 Redirect URI-mismatch De omleiding_uri uw aanvraag komt niet exact overeen met een geregistreerde redirect URI in uw Entra app-registratie. Zelfs een verschil in de schuine streep aan het einde kan dit veroorzaken. Oplossing: Kopieer de exacte URI uit uw Entra app-registratie en gebruik deze letterlijk.
Oplossing: exacte URI-match in Entra app-registratie
AADSTS700016 Applicatie niet gevonden in tenant De klant_id bestaat niet in de tenant waartegen wordt geauthenticeerd. Komt vaak voor bij het gebruik van een tenant-specifieke autoriteit (/{tenant-id}) voor een multi-tenant app. Oplossing: Gebruik /gemeenschappelijk of /organisaties autorisatie voor multi-tenant apps.
Corrigeer: schakel over naar de machtiging /common of /organizations
AADSTS90099 Applicatie is niet geautoriseerd in deze tenant (toestemming_vereist) De app bestaat, maar is niet geaccordeerd in het tenant van de gebruiker. Verschilt van AADSTS65001 doordat de volledige app is geblokkeerd, niet slechts specifieke bereiken. Oplossing: Stuur de beheerdersgoedkeurings-URL naar de IT-beheerder van de klant.
Herstel: admin toestemmings-URL naar klanttenant-admin
AADSTS70011 Verleende subsidie is ongeldig of verlopen Het ververstoken (refresh token) of de autorisatiecode is verlopen of ingetrokken. Autorisatiecodes verlopen na 10 minuten. Ververstokens verlopen na 90 dagen inactiviteit of na intrekking door de beheerder. Oplossing: Vraag de gebruiker om opnieuw te authenticeren vanaf het begin van de OAuth-stroom.
Herstel: volledige herauthenticatieprompt
AADSTS50076: Er is een sterke verificatie vereist om u te kunnen aanmelden. MFA is vereist door het voorwaardelijke toegangsbeleid De tenant van de gebruiker vereist multifactorauthenticatie voor uw app. Dit is een beslissing aan de klantzijde die wordt afgedwongen door de tenantbeheerder. Uw app kan dit niet omzeilen. De gebruiker moet MFA voltooien. Bij gebruik van de autorisatiecodestroom zal Microsoft de MFA-prompt automatisch in de browser weergeven. Problemen doen zich voor bij geautomatiseerde stromen (clientreferenties) die MFA niet kunnen voltooien.
Verwacht: gebruiker moet MFA voltooien
AADSTS50020 Gebruikersaccount van externe identiteitsprovider bestaat niet in tenant De gebruiker probeert te authenticeren met een persoonlijk Microsoft-account in een tenant die alleen organisatorische accounts toestaat, of vice versa. Oplossing: Controleer het autoriteitseindpunt - indien gebruikt /organisaties, persoonlijke accounts kunnen niet authenticeren. Schakel over naar /gemeenschappelijk als je ze allebei nodig hebt.
Corrigeer: schakel autoriteit naar /common
AADSTS53003 Toegang geblokkeerd door voorwaardelijk toegangsbeleid Het Conditional Access-beleid van de tenant heeft deze authenticatiepoging volledig geblokkeerd (bijv. geblokkeerd land, niet-beheerd apparaat, geblokkeerde app). Dit is een beslissing aan de kant van de klant. U kunt dit niet overschrijven. Toon de fout aan de gebruiker en adviseer hen contact op te nemen met hun IT-beheerder.
Klantzijde: adviseer gebruiker contact op te nemen met IT-beheerder
Laat Unipile dit allemaal voor je regelen
Het Unipile Alternatief

Sla 5 weken aan OAuth-installatiewerk over met Unipile

Alles in deze handleiding - Entra app-registratie, autoriteit-eindpunten, scope-selectie, PKCE, token-rotatie, AADSTS-foutafhandeling - is engineeringtijd die uw product niet verder brengt. Unipile beheert de volledige Microsoft Graph OAuth-stack als een beheerde service, zodat uw team één API-aanroep schrijft in plaats van 500 regels OAuth-functionaliteit.

Het zelf bouwen
Entra app-registratie en configuratie
PKCE-implementatie en generatie van codegeneratie
Opslag, rotatie en afhandeling van verlopen refresh tokens
Admin toestemmingsstroom voor zakelijke klanten
AADSTS foutafhandeling en opnieuw authenticeren bij prompts
Rotatie van clientgeheimen vóór de vervaldatum
Afhandeling van kanttekeningen bij voorwaardelijke toegang per tenant
Scheid OAuth-stacks voor Gmail- en IMAP-providers
Met Unipile
Eén POST om een gehoste authenticatielink te genereren
Unipile beheert PKCE, tokens en verversing automatisch
Tokens worden nooit opgeslagen in uw database - Unipile handelt dit af
Zelfde API voor Microsoft, Gmail en IMAP-accounts
Webhookmeldingen wanneer accounts opnieuw geauthenticeerd moeten worden
Branded toestemmingsscherm met uw eigen Entra app-gegevens
Verzend uw e-mailintegratie in uren, niet in weken
Hoe Unipile Microsoft OAuth host
Uw backend roept één eindpunt aan om een gehoste authenticatielink te genereren. Uw gebruiker klikt erop, authenticeert zich bij Microsoft en Unipile beheert de volledige OAuth-stroom - Entra-omleiding, scope-afhandeling, tokenwisseling en vernieuwing. Het gekoppelde account is vervolgens beschikbaar via Unipile's unificatede e-mail-API.
unipile_microsoft_oauth.py
importeer verzoekt UNIPILE_API_URL = "https://apiXXX.unipile.com:XXX" UNIPILE_API_SLEUTEL = "je-api-sleutel" # Stap 1: Genereer een gehoste authenticatielink voor Microsoft response = requests.post( "{UNIPILE_API_URL}/api/v1/hosted/accounts/link", headers={ "X-API-SLEUTEL": UNIPILE_API_KEY, "Content-Type": "application/json" }, json={ "type": "maken", "providers": ["MICROSOFT"], "api_url"UNIPILE_API_URL, "verlooptOp": "2026-12-31T23:59:59Z", # Optioneel: koppel deze link aan een specifieke gebruiker "naam": "gebruikers_id_123", # Optioneel: ontvang een melding wanneer het account is gekoppeld "notificatie_url": "https://app.yourproduct.com/webhooks/account-linked" } ) # Stap 2: Leid je gebruiker door naar deze URL gehoste_authenticatie_url = antwoord.json()["url"] Voorbeeld van #: https://account.unipile.com/[encoded-token] # Unipile-functies: Entra-omleiding, toestemmingsscherm, PKCE, #-tokenuitwisseling, vernieuwing van de tokenopslag, bereikbeheer # Stap 3: Gebruik na authenticatie de e-mail-API van Unipile om e-mails te lezen of te versturen emails = requests.krijgen( f"{UNIPILE_API_URL}/api/v1/emails", headers={"X-API-SLEUTEL": UNIPILE_API_KEY}, params={"account_id": "gekoppeld-account-id"} )
Microsoft OAuth voltooid. Mailbox beschikbaar via unified API.
Hosted-authenticatiestroom
Unipile host het OAuth-toestemmingsscherm. Uw gebruikers zien een nette merkontwikkeling. Geen onderhoud aan redirect URI's, geen CORS-problemen, geen gedoe met localhost versus productie-URL's.
Tokenbeheer
Unipile slaat Microsoft OAuth-tokens voor u op en roteert deze. Rotatie van vernieuwingstokens, bewaking van 90 dagen inactiviteit en meldingen voor herautorisatie worden automatisch afgehandeld.
Gecombineerde e-mail API
Na koppeling reageren Microsoft-, Gmail- en IMAP-mailboxen allemaal op dezelfde Unipile e-mail-endpoints. Eén integratie dient voor alle drie de providers.
Uw eigen Entra-gegevens
Configureer uw eigen Microsoft Entra app-gegevens in het Unipile-dashboard. Uw gebruikers zien de naam van uw app op het toestemmingsscherm van Microsoft, niet die van Unipile.
Webhookmeldingen
Ontvang een webhook wanneer een gekoppeld account opnieuw moet worden geauthenticeerd (verlopen vernieuwingstoken, intrekking door beheerder, wijziging van voorwaardelijke toegang). Toon prompt voor opnieuw authenticeren onmiddellijk in uw product.
Lezen, verzenden en synchroniseren
Na Microsoft OAuth via Unipile kunt u e-mails lezen, e-mails verzenden, threads synchroniseren, mappen beheren en bijlagen afhandelen - allemaal via de uniforme e-mail-API van Unipile. Geen aparte Microsoft Graph-client nodig.
Hoe Unipile werkt
Unipile is een onafhankelijke technische tussenpersoon die optreedt namens elke geauthenticeerde gebruiker via door Microsoft uitgegeven OAuth-tokens. Wanneer een gebruiker zijn of haar Outlook- of Microsoft 365-mailbox koppelt, werkt Unipile uitsluitend met de gedelegeerde machtigingen van die gebruiker. Unipile is niet aangesloten bij, goedgekeurd door of gesponsord door Microsoft. We gebruiken de openbare Microsoft Graph API namens geauthenticeerde eindgebruikers. Elk account functioneert binnen de eigen Microsoft Entra-identiteit van de gebruiker en de voorwaardelijke toegangsprotocollen van hun organisatie.
Begin met het bouwen van uw Microsoft OAuth-stroom MS Graph E-mail Gids
FAQ

Veelgestelde vragen

De meest gestelde vragen over Microsoft Graph OAuth voor e-mailintegratie, van scope selectie tot tokenlevenscyclus en enterprise consent flows.

01
Werkt Microsoft Graph OAuth voor zowel Outlook.com als Microsoft 365-accounts?
Ja. Gebruikmakend van de /gemeenschappelijk het autorisatie-eindpunt, een enkele Microsoft Entra-appregistratie handelt authenticatie af voor zowel persoonlijke Outlook.com-accounts als werk-/schoolaccounts van Microsoft 365. De sleutel is het selecteren van "Accounts in elke organisatiedirectory en persoonlijke Microsoft-accounts" bij het registreren van uw app in de Azure-portal.
02
De OAuth-tokens worden ingetrokken.
Wanneer een IT-beheerder een gebruikersaccount in Microsoft Entra ID uitschakelt of verwijdert, worden alle vernieuwingstokens van die gebruiker onmiddellijk ingetrokken. Uw volgende poging om een token te vernieuwen retourneert een ongeldige_verlening fout. Ga hiermee soepel om: markeer het gekoppelde account als het dat opnieuw moet worden geauthenticeerd en toon een duidelijke prompt voor opnieuw authenticeren in uw product. Dit is verwacht gedrag - een beslissing aan de kant van de klant waar u geen controle over heeft.
03
Is adminconsent vereist om Outlook-e-mails te lezen via Microsoft Graph OAuth?
Nee, voor standaard Gedelegeerde machtigingen. Mail.lezen, Mail.ReadWriteen Mail.verzenden gebruikersgoedkeuringsbereiken - individuele gebruikers kunnen deze goedkeuren tijdens het OAuth-proces. Toestemming van de beheerder is alleen vereist voor toepassingsmachtigingen of bereiken met hoge bevoegdheden, zoals Gebruiker.Lees.Alles. Sommige enterprise tenants configureren beleidsregels die alle toestemming voor apps van derden blokkeren. Dat is een beslissing van de klant.
04
Hoe lang duren Microsoft Graph-verlooptokens?
Vernieuwingstokens verlopen na 90 dagen inactiviteit. Zolang uw app het vernieuwingstoken regelmatig gebruikt (wat automatisch gebeurt bij het vernieuwen van toegangstokens voordat deze elke 60-90 minuten verlopen), blijft het vernieuwingstoken actief. Beleidswijzigingen voor voorwaardelijke toegang, wachtwoordherstel of intrekking door een beheerder kunnen ze voortijdig ongeldig maken. Verwerk altijd ongeldige_verlening fouten en vernieuw de oude refresh tokens met de nieuwe die bij elke token respons wordt geretourneerd.
05
Wat is het verschil tussen AADSTS65001 en AADSTS90099?
AADSTS65001: De gebruiker heeft nog geen toestemming gegeven voor één of meer specifieke bereiken. Oplossing: toevoegen toestemming naar uw autorisatie-URL om een nieuw toestemmingsscherm af te dwingen. AADSTS90099De gehele applicatie is niet geautoriseerd in die tenant; de tenantbeheerder moet uw app vooraf goedkeuren. Stuur de URL voor beheerdersgoedkeuring naar de IT-beheerder van de klant. Beide fouten komen vaak voor in zakelijke scenario's waarbij tenants gebruikerstoestemmingen beperken.
06
Kan ik dezelfde Entra app-registratie gebruiken voor zowel het lezen als het verzenden van e-mails?
Ja. Verzoek beide Mail.ReadWrite en Mail.verzenden in dezelfde scope string. Merk op dat Mail.ReadWrite en Mail.verzenden zijn afzonderlijke scopes - lees-/schrijftoegang verleent niet automatisch verzendpermissie. Neem altijd op offline_access om ervoor te zorgen dat u een vernieuwingstoken ontvangt. Zie de e-mail API-pagina voor implementatiedetails.
07
Slaat Unipile Microsoft OAuth-tokens op in mijn database?
Nee. Wanneer u de gehoste Microsoft authenticatiestroom van Unipile gebruikt, beheert Unipile alle OAuth-tokens namens u. Uw applicatie verwerkt nooit Microsoft toegangs- of vernieuwingstokens direct. U werkt uitsluitend met gekoppelde accounts via de unificated e-mail API van Unipile met uw Unipile API-sleutel. Dit elimineert vereisten voor tokenopslag, rotatie en beveiliging uit uw eigen infrastructuur.
08
Is Unipile aangesloten bij Microsoft?
Nee. Unipile is niet gelieerd aan, goedgekeurd door of gesponsord door Microsoft. Unipile is een onafhankelijke technische tussenpersoon die de openbare Microsoft Graph API gebruikt namens geauthenticeerde eindgebruikers. Elke integratie werkt via door Microsoft uitgegeven OAuth-tokens onder de eigen identiteit van die gebruiker en de Conditional Access-beleidsregels van hun organisatie. Microsoft Graph en Microsoft Entra zijn handelsmerken van Microsoft Corporation.
Heb je nog vragen? Ons team kan u door Microsoft Graph OAuth begeleiden voor uw specifieke use case.
nl_NLNL
en_USEN fr_FRFR es_ESES de_DEDE it_ITIT pt_BRBR pl_PLPL tr_TRTR nl_NLNL