Graph-szinkronizálás kulcsai és tanúsítványai

A Graph-szinkronizálás kétféle kriptográfiai anyagot használ. Mielőtt beállítod a szolgáltatóhozzáférést, fejezd be a Microsoft Graph setup lépéseit.

Anyag	Cél	Titkos anyag	Fogyasztó
Delta data key (delta-adatkulcs)	AES-256-GCM titkosítás az átlátszatlan @odata.nextLink / @odata.deltaLink URL-ekhez	Adatkulcs	A szinkronizációs lekérő és helyreállító futásidejű rész
Rich-notification certificate (gazdag értesítési tanúsítvány)	Nyilvános kulcsú titkosítás a Graph-értesítési feliratkozásokhoz	Csak a privát kulcs	A feliratkozáskezelő és a titkosított erőforrások feldolgozása

Egyik sem helyettesíti a böngésző HTTPS-tanúsítványait, a bejelentkezési adatokat vagy a személyes e-mail-kulcsokat.

1. Stabil delta-kulcs megtartása

Új, üres deploymenthez generálj pontosan 32 véletlen bajtot:

openssl rand -base64 32

Mentsd az eredményt DELTA_LINK_ENCRYPTION_KEY néven az egységes gyökér .env fájlba. A jelenlegi Compose továbbítja ezt a kulcsot, és a local-dev-v1 futásidejű hivatkozást használja. A DELTA_LINK_ENCRYPTION_KEY_REFERENCE változót nem továbbítja. Ha ezt a gyökér .env-be felveszed, a folyamat hivatkozása nem változik.

Az önálló (standalone) backend megkaphatja a saját kulcsát és explicit DELTA_LINK_ENCRYPTION_KEY_REFERENCE értékét. A megtartott állapot mellé az eredeti, kompatibilis kulcsot és hivatkozást őrizd meg. Másik hivatkozás alatt létrehozott állapot áthelyezéséhez ellenőrzött, kompatibilis futásidejű beállítás vagy explicit migráció kell.

A dekódolt kulcsnak pontosan 32 bajtot kell tartalmaznia. A futásidejű rész a teljes, átlátszatlan Graph-URL-eket titkosítja a mappa- és üzenet-delta tokenekben, valamint a staging-ellenőrzőpontokban. Nyers URL-ek és titkos kulcsok nem kerülhetnek böngészőválaszba, logba vagy dead-letter payloadba.

Minden olyan újraindítás után használd újra az eredeti kulcsot, amely titkosított delta-állapotot tart meg. Productionben explicit kulcsanyag kötelező. Nem production kódban, ha nincs explicit kulcs, a rendszer determinisztikus fejlesztői kulcsot származtathat a generált helyi tanúsítványanyagból. Ez a visszalépés a kulcsot ezekhez a fájlokhoz köti. Megtartott adatokhoz konfiguráld és őrizd meg az explicit kulcsot, ne az újragenerált tanúsítványokra támaszkodj.

A régi GRAPH_SYNC_DATA_KEY_BASE64 / GRAPH_SYNC_DATA_KEY_REFERENCE aliasok továbbra is támogatottak. A kanonikus DELTA_LINK_ENCRYPTION_KEY* neveket részesítsd előnyben.

Elveszett vagy rotált kulcsok

Először állítsd vissza az eredeti titkot és hivatkozást. A csere nem fejti vissza a régi delta-URL-eket. Ha a visszaállítás nem lehetséges, tervezz explicit delta-állapot-resetet és teljes egyeztetést. Egy tiszta, eldobható fejlesztési adatbázis engedélyezett reset után újra végigvihető az onboarding folyamatán.

Soha ne tegyél csendben új kulcsot régi hivatkozás mögé. Normál reset esetén nem kell megtartott kulcsot rotálni. A kulcsok biztonsági másolatát az adatbázis-helyreállítási anyaggal együtt tartsd.

2. Gazdag értesítési tanúsítványfájlok előkészítése

Alapértelmezett, a Gitből kizárt fájlok a backendben:

Fájl	Tartalom	Jogosultság
mailGen/msmicroservices-architexture/certs/cert/certificate.pem	Önaláírt X.509 nyilvános tanúsítvány	600
mailGen/msmicroservices-architexture/certs/private_key/private_key.pem	RSA privát kulcs	600
mailGen/msmicroservices-architexture/certs/cert_id/certificate_id	SHA-256 ujjlenyomat kettőspontok nélkül	600

A szülőkönyvtárak jogosultsága 700. A privát anyagot tartsd a Gitből kizárva.

A normál inicializálás meghívja a meglévő tanúsítvány-előkészítést. Önálló, kézi ellenőrzéshez a motherrepo gyökeréből indulj:

cd mailGen/msmicroservices-architexture
bash certgen.sh
pnpm graph-sync:preflight

A certgen.sh ellenőrzi mindhárom fájlt, a tanúsítvány formátumát és lejáratát, a privát kulcs formátumát, a nyilvános kulcsok egyezését és az ujjlenyomat azonosságát. Ha a teljes készlet hiányzik, 2048 bites RSA/SHA-256 önaláírt tanúsítványt hoz létre. A generált tanúsítvány érvényessége 3650 nap. Részleges, lejárt, sérült vagy nem egyező készlet esetén a szkript leáll, és nem írja felül automatikusan.

A TypeScript-útvonalbetöltő ellenőrzi a PEM-párt, és a nyilvános tanúsítványt Base64 DER formátumra alakítja a Graph-feliratkozási kérésekhez.

Feloldási sorrend

A következő közvetlen és egyéni útvonal-beállítások önálló futtatásra vagy más olyan deploymentre vonatkoznak, amely explicit módon továbbítja őket. A jelenlegi egységes gyökér Compose nem teszi elérhetővé ezeket a tetszőleges közvetlen bemeneteket. Rögzített /runtime/graph/... csatolásokat és opcionális tanúsítványazonosítót ad.

Önálló folyamatnál a teljes, explicit beállítás élvez elsőbbséget:

GRAPH_WEBHOOK_ENCRYPTION_CERTIFICATE=<Base64 DER public certificate>
GRAPH_WEBHOOK_ENCRYPTION_CERTIFICATE_ID=<certificate ID>
GRAPH_WEBHOOK_ENCRYPTION_CERTIFICATE_REFERENCE=vault://graph-webhook/v1

A közvetlen tanúsítványbemenethez azonosító kell. Ellenkező esetben az útvonal-mód ezt használja:

GRAPH_WEBHOOK_ENCRYPTION_CERTIFICATE_PATH=certs/cert
GRAPH_WEBHOOK_ENCRYPTION_PRIVATE_KEY_PATH=certs/private_key
GRAPH_WEBHOOK_ENCRYPTION_CERTIFICATE_ID=certs/cert_id

A tanúsítvány és a privát kulcs útvonala párt alkot. Mindkettő megnevezhet olyan fájlt vagy könyvtárat, amely érvényes PEM-fájlt tartalmaz. Az azonosító lehet literál, fájl vagy könyvtár. Teljes útvonal-módban a hiányzó azonosító alapértelmezés szerint a tanúsítvány ujjlenyomata lesz.

Productionben a részleges közvetlen vagy útvonal-beállítást a rendszer elutasítja. Nem production feloldás figyelmeztet, és megpróbálja a generált fájlok visszalépését. A tanúsítványszkript a sérült vagy részleges fájlkészletet továbbra is elutasítja.

A GRAPH_SYNC_CERTS_DIR egy másik gyökeret jelölhet ki, amely a cert/, private_key/ és cert_id/ mappákat tartalmazza. A szkript a kanonikus útvonalneveket is olvassa a támogatott környezeti bemenetekből.

Az egységes Compose rögzíti a GRAPH_SYNC_CERTS_DIR=/runtime/graph értéket, a tanúsítvány útvonalát /runtime/graph/cert/certificate.pem, a privát kulcs útvonalát pedig /runtime/graph/private_key/private_key.pem. A normál inicializálás ezeket a fájlokat a példányhoz tartozó helyi állapotból adja. Ezek konténerútvonalak. Ne cseréld őket gazdagép abszolút fájlneveire. Önálló futtatás a saját folyamatkörnyezetét és helyi útvonalait használja.

3. Feliratkozási callbackek beállítása

A tanúsítvány önmagában nem engedélyezi a feliratkozásokat. Adj meg mindkét nyilvános HTTPS callbacket és egy stabil client-state titkot:

GRAPH_WEBHOOK_URL=https://your-public-host.example/graphWebhook
GRAPH_LIFECYCLE_WEBHOOK_URL=https://your-public-host.example/graphWebhook
GRAPH_WEBHOOK_CLIENT_STATE=<private random value>

Ezek egy támogatott, közvetlen WebhookCatcher-útvonalat mutatnak be. Használd a deploymentedhez beállított pontos ingress-útvonalakat. Mindkettő a WebhookCatcherhez irányít, rendszerint a 3080 belső porton. Ugyanaz a kezelő fogadhat értesítési és lifecycle-kötegeket.

A client-state legfeljebb 128 karakter legyen, és a feliratkozások élettartama alatt maradjon stabil. A Microsoft nem éri el a http://localhost címet. Ehhez a fejlesztő saját nyilvános HTTPS ingressét vagy alagútját használd, ne más fejlesztő megosztott domainjét.

A hiányos lifecycle-beállítás a következőt eredményezheti:

Rich subscription lifecycle disabled because its runtime configuration is incomplete.

Ez letiltja a gazdag feliratkozás létrehozását, megújítását és újralétrehozását. A rendszeres mappa- és üzenet-delta, valamint a kategórialekérdezés külön mechanizmus. A böngésző tanúsítványellenőrzése nem bizonyítja, hogy a nyilvános webhook elérhető.

4. Tanúsítványok tudatos rotálása

A rotálás előtt készíts biztonsági másolatot a meglévő anyagról. A backend könyvtárából:

bash certgen.sh --force

Ezután indítsd újra az érintett szolgáltatásokat, és egyeztesd vagy hozd létre újra azokat a feliratkozásokat, amelyek még a régi tanúsítványt nevezik meg. A régi privát kulcsot addig őrizd meg, amíg a régi titkosított értesítések még érkezhetnek. Eldobható helyi környezetben engedélyezett reset- vagy onboarding-útvonal használható, a megtartott adatokhoz azonban szabályozott helyreállítás kell.

A tanúsítvány-rotálás és a delta-kulcs-rotálás külön művelet. A --force nem írja át az explicit delta-kulcsot. A származtatott fejlesztői kulcs megváltozhat, ha a tanúsítványanyaga változik.

5. Konfigurációs hibák diagnosztizálása

Hiba	Jelentés	Következő lépés
DELTA_LINK_ENCRYPTION_KEY ... required	Hiányzik az explicit production-kulcs, vagy nem elérhető a fejlesztői visszalépés	Állítsd vissza vagy konfiguráld a helyes, stabil kulcsot
must be valid base64 encoding exactly 32 bytes	Érvénytelen kódolás vagy dekódolt méret	Állítsd vissza a helyes titkot, vagy csak üres adathoz generálj újat
certificate set is partial, expired, corrupt, or mismatched	Érvénytelen fájlkészlet	Készíts biztonsági másolatot, és vizsgáld meg. Csak szándékosan rotálj.
must be configured together	Hiányos production-beállítási csoport	Add meg a teljes csoportot
must use public HTTPS	Érvénytelen vagy csak helyi callback	Javítsd a nyilvános ingresst vagy alagutat
encryption key reference unavailable	A tárolt URL másik kulcsot vagy hivatkozást igényel	Állítsd vissza, vagy indíts explicit helyreállítást

Soha ne naplózd a titkos vagy tanúsítványtartalmat. A hivatkozások, azonosítók és fájlútvonalak segíthetnek a diagnózisban. Az adatkulcsokat, a privát kulcsokat és a nyers delta-URL-eket tartsd távol a BFF-től és a böngészőtől. Production anyaghoz titokkezelőt használj.