Microsoft Graph postafiók-hozzáférés beállítása

Készítsd elő a Microsoft Graph alkalmazás-hozzáférést, mielőtt importálnál vagy szinkronizálnál Microsoft-postafiókot. Ez az útmutató a MailGen backend alkalmazásidentitását fedi le. Az interaktív bejelentkezést külön, a fiók-bejelentkezés beállításán keresztül állítsd be.

Mielőtt elkezded

Szükséged van Microsoft Entra-bérlőre, kezelhető alkalmazásregisztrációra, a hozzájárulás megadásához szükséges adminisztrátori jogosultságra és Exchange Online postafiókra. Kell a deployment támogatott futtatókörnyezeti konfigurációja is.

A három identitás különböző célt szolgál:

Identitás	Cél
App-bejelentkezés / actor	A bejelentkezett MailGen-felhasználó, aki műveletet kér
Csatlakoztatott fiók / postafiók	Az ellenőrzött kötés egy adott szolgáltatói postafiókhoz
Backend szolgáltatásazonosító (service principal)	Az alkalmazásidentitás, amely Graph-tokent kap és hívja a Microsoftot

A Better Auth hozzáférési és frissítési tokenjei az app-bejelentkezést azonosítják. A MailGen nem használja őket backendoldali Graph-postafiók-hitelesítő adatként. A backend Graph-hívások alkalmazásjogosultságokat és a kliens-hitelesítő adatos .default hatókört használnak. Lásd a Microsoft csak alkalmazásszintű hitelesítési szerződését.

Az alkalmazás regisztrálása és engedélyezése

1. Nyisd meg a Microsoft Entra admin center → App registrations (Microsoft Entra adminisztrációs központ → Alkalmazásregisztrációk) oldalt, és válaszd ki vagy hozd létre a backend-alkalmazást.
2. Jegyezd fel a Directory (tenant) ID (bérlőazonosító) és az Application (client) ID (alkalmazásazonosító) értékét a deployment titkos konfigurációjába.
3. Készítsd elő a támogatott alkalmazás-hitelesítő adatot. A titkos értékeket és a privát fájlokat tartsd verziókezelésen kívül.
4. Nyisd meg az API permissions → Add a permission → Microsoft Graph → Application permissions (API-jogosultságok → Jogosultság hozzáadása → Microsoft Graph → Alkalmazásjogosultságok) menüpontot.
5. Add hozzá az alábbi, engedélyezett műveletekhez szükséges jogosultságokat.

Ezután válaszd a Grant admin consent (Adminisztrátori hozzájárulás megadása) lehetőséget a bérlődhöz. A jogosultságnevek hozzáadása hozzájárulás nélkül nem engedélyezi a service principal számára a műveleteket. A bejelentkezési hozzájárulás külön művelet.

Funkció	Graph-alkalmazásjogosultság
Kötelező éles onboarding-export	MailboxItem.Export.All
Levelek olvasása/importálása	Mail.Read, vagy az írásokhoz szükséges szélesebb Mail.ReadWrite
Piszkozat-, üzenet- és mappaírás	Mail.ReadWrite
Küldés	Mail.Send
Személyes névjegyek olvasása	Contacts.Read
Személyes névjegyek írása	Contacts.ReadWrite
Naptárolvasás	Calendars.Read
Naptárírás, ha engedélyezve van	Calendars.ReadWrite
Postafiók-beállítások és kategória-olvasás	MailboxSettings.Read
Postafiók-beállítások és kategória-írás	MailboxSettings.ReadWrite
Címtári személyek és felhasználói licencadatok	User.Read.All
Nyilvános címtári csoportok és tagazonosítók	GroupMember.Read.All
Bérlői licenckatalógus	LicenseAssignment.Read.All
Aktív Global Administrator-igazolás	RoleManagement.Read.Directory

Az éles onboardinghoz MailboxItem.Export.All jogosultság és bérlői adminisztrátori hozzájárulás kell a POST /admin/exchange/mailboxes/{id}/exportItems művelethez. A normál levelezési olvasási és írási jogosultságok nem engedélyezik ezt az exportot. Az importáló a nyers exportot és a melléklet-kinyerést igényli, mielőtt a befejezési akadálya átmehet. A MailboxItem.ImportExport.All szélesebb, és ehhez a csak exportos munkafolyamathoz nem szükséges. Lásd az exportItems jogosultsági szerződést.

A címtári csoportokhoz a személyektől külön olvasási jogosultság kell. Adj GroupMember.Read.All jogosultságot bérlői hozzájárulással a csoportlistázáshoz és a tagok felsorolásához. Egy már meglévő, szélesebb olvasási jogosultság is kielégítheti ezeket az endpointokat. Címtár-írási jogosultság nem kell. A csoport-frissítés elbukhat, miközben a személyek alapfrissítése sikeres.

A különálló CLI és a laboratóriumi műszerfal nem futtatja az éles importálót. Normál postafiók-műveleteikhez nincs szükség az exportjogosultságra. Csak a kiválasztott munkafolyamathoz szükséges jogosultságokat használd. Egy szélesebb jogosultság nem valósít meg támogatatlan MailGen-funkciót. Csak jogosultság-ellenőrzésekhez ne adj címtár-írási szerepkört. A jogosultsági és visszaállítási hatókörhöz lásd a külső szolgáltatások előfeltételeit.

Az Exchange-alkalmazáskorlátozások a bérlői hozzájárulás után is korlátozhatják, mely postafiókokat éri el az alkalmazás. Győződj meg róla, hogy a kívánt postafiók a megengedett hatókörön belül van. Írások engedélyezése előtt tesztelj kijelölt postafiókkal.

Futtatókörnyezeti hitelesítő adatok csatlakoztatása

A backend bootstrap és a GraphOneTimeUserOnboarder a BACKEND_TENANT_ID, BACKEND_CLIENT_ID és BACKEND_CLIENT_SECRET változókat igényli, az önálló worker-futtatást is beleértve. A gyökér Compose-környezet ezeket a neveket változatlanul továbbítja. A worker .env.example fájlja még elavult, előtag nélküli Graph-neveket mutat. Használd helyettük a futtatókörnyezeti szerződés BACKEND_* neveit.

A különálló CLI és a laboratóriumi műszerfal a TENANT_ID, CLIENT_ID és CLIENT_SECRET változókat használja. Ezek nem cserélhetők fel az éles worker nevével. Lásd a környezeti referenciát.

A postafiók-hatókörű Graph-átvitel a msintegrationv2.tenant_connections táblát oldja fel. Tokenkérés előtt ellenőrzi a megadott hozzájárulást és a hitelesítő adat lejáratát. A támogatott kapcsolati módok között van kliens-titok, tanúsítvány, felügyelt identitás és munkaterhelés-identitás. Hiányzó postafiók-kapcsolat nem esik vissza másik bérlő hitelesítő adatára.

A deployment módjának és hivatkozási formátumának megfelelően használd a beállított módot. Az env:// hivatkozás egy megnevezett futásidejű értéket old fel. A file:// hivatkozás egy csatolt hitelesítő fájlt azonosít. Sem a böngészőnek, sem az adminisztrátori űrlapnak nincs szüksége magára a Graph-titokra.

Értesítések és tárolás beállítása

Állítsd be a deployment saját, nyilvános HTTPS-callback URL-jeit:

GRAPH_WEBHOOK_URL=https://<your-public-host>/graph/webhook
GRAPH_LIFECYCLE_WEBHOOK_URL=https://<your-public-host>/graph/lifecycle

Mindkét útvonalat irányítsd a WebhookCatcherre a teljes útvonal megtartásával. Ne használj más fejlesztő alagútját vagy az InstantUserDataGettert külső webhook-célpontként. Állíts be stabil GRAPH_WEBHOOK_CLIENT_STATE értéket.

Az értesítési tanúsítványhoz, privát kulcshoz, tanúsítványazonosítóhoz és a DELTA_LINK_ENCRYPTION_KEY változóhoz kövesd a Graph-kriptográfiai beállítást. Ezek különböznek az alkalmazás-hitelesítő adattól és a személyes levéltitkosítási kulcstól.

A PostgreSQL-t, a Kafkát, az S3-at és a keresést a telepítésen keresztül készítsd elő. Az import a törzseket és mellékleteket az objektumtárolóban tárolja. Önmagában az adatbázis-kapcsolat nem elegendő.

Egy postafiók csatlakoztatása és előkészítése

Ez az eljárás előkészített Microsoft-deploymentet igényel. Végezd el a fiók-bejelentkezés beállítását és a fenti Graph-, értesítési, tárolási és sorbaállítási előfeltételeket. A bejelentkezett actornak mail.onboarding jogosultság kell. Az actor-jogokhoz lásd a jogosultságkezelést.

A Microsoft-összekötőhöz megőrzött bérlőkapcsolat is kell, megadott hozzájárulással, service principal azonosítóval és hitelesítő adat hivatkozással. A hitelesítő adat nem lehet lejárt. A kapcsolatnak meg kell felelnie a beállított Microsoft-bérlőválasztásnak. A környezeti hitelesítő adatok önmagukban nem elégítik ki ezt az elérhetőségi ellenőrzést.

Ez az eljárás az előkészített bérlőkapcsolattal indul. Nem inicializálja az első bérlőkapcsolatot egy üres adatbázisban. Egy elérhetetlen Microsoft-művelet azt jelenti, hogy az összekötő konfigurációja vagy a megőrzött kapcsolat elérhetőségi ellenőrzése nem ment át. Nem jelenti azt, hogy előbb postafiók-sort kell létrehozni.

1. Jelentkezz be a MailGenbe, majd nyisd meg a /onboarding oldalt. Az oldal címe Connect Account (kapcsolt fiók csatlakoztatása), a felületen angolul.
2. Ha a kívánt Microsoft-fiók nincs összekapcsolva, válaszd a Folytatás Microsofttal lehetőséget, ha elérhető. Végezd el a Microsoft-identitás összekapcsolását, és térj vissza a /onboarding?sync=1 oldalra.
3. Válaszd ki a MailGen-bejelentkezésedhez tartozó, kívánt csatlakoztatott fiókot. Ahol elérhető, használd a Switch mailbox (postafiók váltása) lehetőséget. Indítás előtt ellenőrizd az e-mail-címet és a Microsoft-szolgáltatót.
4. Válaszd a Kezdeti beállítás indítása lehetőséget. A munkaterület-beállítási kapu az ezzel egyenértékű Postafiók beállítása műveletet használja.
5. Kövesd a kiválasztott fiók mentett lépésállapotát ready állapotig. A felület ezután megnyitja a munkaterületet. Az import és a keresési készenlét ellenőrzését külön végezd el.

A Microsoft-identitás-összekapcsolás a openid, profile, email, offline_access, User.Read és Mail.ReadWrite hatóköröket kéri. Ezek delegált identitási és összekapcsolási jogosultságok. Nem adják meg a backendnek az alkalmazásszintű jogosultságait. Az importáló a fent leírt, külön BACKEND_* alkalmazás-hitelesítő adatokat és a bérlői adminisztrátori hozzájárulást használja.

Az indítási művelet ellenőrzi a csatlakoztatott fiók tulajdonjogát és a friss mail.onboarding jogosultságot. Elfogadja a kérést a sorba. Nem követeli meg a meglévő postafiók-sort vagy nem null mailboxId értéket.

A .NET worker feloldja az összekapcsolt e-mail-címet Graphon keresztül. Ellenőrzi, hogy a visszaadott felhasználó egyezik-e a jogosult Entra-alannyal. Ezután létrehozza vagy frissíti a helyi postafiók- és bérlőkapcsolat-rekordokat. A kérés elfogadása nem import befejezése. Kövesd a mentett futás és lépésállapot állapotát, ne indíts újabb importot, mert a haladás késve jelenik meg.

failed vagy failedRetryable állapotnál nézd meg a megjelenített lépéshibát, és ha felkínálja, használd a Retry onboarding (újrapróbálás) lehetőséget. A munkaterület-kapu ezt Retry mailbox setup (postafiók-beállítás újrapróbálása) néven hívja. Ha a Microsoft-összekapcsolás nem talál használható identitást, csatlakozz újra a Microsoft-művelettel, és hagyd jóvá a kért profiljogosultságokat. A tartalomkulcs-kérés a megfelelő meglévő kulcsmentést és feloldást igényli.

Az eredmény ellenőrzése

Használd az egy postafiók csatlakoztatását és előkészítését, majd kövesd az onboarding haladását. Az import készenlétét és a keresés készenlétét külön ellenőrizd. Az előfizetés és a műveletek állapotának vizsgálatához nyisd meg a Szinkronizálási központot.

Egy webhook-nyugtázás azt jelenti, hogy a rendszer elfogadta a tartós jelzést. A delta-egyeztetés állapítja meg az aktuális szolgáltatói tartalmat. A accepted állapotú művelet nem bizonyítja a szolgáltatói írást. Megerősítettként csak a végső állapot után kezeld.

Hiba	Ellenőrzés
Tokenszerzés sikertelen	Bérlő- és kliensazonosító, hitelesítő adat hivatkozása, lejárat, hozzájárulás állapota
Graph 403	Alkalmazásjogosultság, adminisztrátori hozzájárulás, Exchange-postafiók-hatókör
A bejelentkezés működik, a postafiók nem	Külön backend Graph-kapcsolat és postafiók-kötés
Hiányzó értesítések	Nyilvános HTTPS-útvonal, előfizetés állapota, tanúsítvány, kliensállapot
A tartalmi munka kulcsra vár	A helyes tulajdonosi titkosítási kulcs és az aktív feloldás

Google-postafiókokhoz használd a Google Cloud beállítást. A Microsoft-alkalmazás hozzájárulása nem engedélyezi a Gmailt.