Google Cloud beállítása a deploymentedhez

Készítsd elő a Google Cloudot a MailGen deploymenthez személyes Gmaillel vagy jóváhagyott Workspace-hozzáféréssel. Ez az útmutató külön OAuth-kliens-hitelesítő adatokat és opcionális, hitelesített push routinget hoz létre.

A helyi géphez olvasd el az első setupot, az alkalmazás identitásához pedig az alkalmazásbejelentkezés beállítását. A Google-alkalmazásbejelentkezés és a Gmail-postafiók-hozzájárulás külön van. A Gmail OAuth-t használ, nem egyszerű API-kulcsot.

A Cloud Shell parancsai a Google hosztolt terminálján futnak. A local machine jelöléssel ellátott parancsok a letöltött motherrepóból futnak Bashben. Helyi Google Cloud CLI-re nincs szükséged.

1. Projekt létrehozása és címek kiválasztása

Nyisd meg a Google Cloud Consolet az operátori fiókkal.
Használd a projektválasztót és a New project gombot. Válaszd ki az elérhető szervezetet/helyet, majd hozd létre a projektet. Személyes fiókok használhatják a No organization lehetőséget.
Válaszd ki az új projektet, és jegyezd fel a Dashboard → Project info → Project ID értékét. Ez eltér a megjelenítendő névtől és a számszerű Project numbertől.
Kösd össze a számlázást, ha a kiválasztott szolgáltatások igénylik. Ellenőrizd a költségeket, és állíts be költségvetési riasztásokat. A riasztás nem automatikus költéskorlát.
Készítsd elő ennek a deploymentnek a nyilvános HTTPS-ingressét az OAuth- és push-útvonalakhoz. A localhost és a .local nem fogadhat Google push-callbacket.

Érték	Jelentés
`PROJECT_ID`	Cloud-projekt azonosítója
`PUBLIC_ORIGIN`	A nyilvános HTTPS origin záró perjel nélkül
`BFF_ORIGIN`	A tényleges böngészős alkalmazás HTTPS-origin, a porttal együtt
Postafiók-callback	`PUBLIC_ORIGIN/v1/oauth/callback`
Alkalmazásbejelentkezési callback	`PUBLIC_ORIGIN/api/auth/callback/google`
Push endpoint és audience	`PUBLIC_ORIGIN/v1/pubsub/push`
Postafiók-befejezés	`BFF_ORIGIN/api/google-mailbox/complete`. Ne regisztráld Google-átirányításként.

Az egységes BFF jellemzően a https://bff.YOUR_INSTANCE.ecas.local:8443 címet használja. A nyilvános ingress ettől külön van. Meglévő adatok átvitelekor őrizd meg a deployment UUID-t, az OAuth-klienseket és a titkosítási kulcsokat.

2. API-k bekapcsolása

Az APIs & Services → Library részben nyisd meg az egyes szükséges API-kat, és válaszd az Enable lehetőséget. Használd a postafiók-kliens projektjét.

API	Azonosító	Szükséges ehhez
Gmail	`gmail.googleapis.com`	Levélhozzáférés
People	`people.googleapis.com`	Névjegyek
Calendar	`calendar-json.googleapis.com`	Naptár elérhetősége
Cloud Pub/Sub	`pubsub.googleapis.com`	Push-értesítések
Admin SDK	`admin.googleapis.com`	Csak jóváhagyott Workspace-könyvtár-hozzáféréshez

Alternatívaként nyisd meg a Activate Cloud Shell gombot a felső sávban. Amikor kéri, hagyd jóvá a hozzáférést. Indítsd el a Bash-t, és cseréld le a példa projekt- és domain-értékeket:

bash
set -euo pipefail
PROJECT_ID='YOUR_PROJECT_ID'
PUBLIC_ORIGIN='https://YOUR_PUBLIC_DOMAIN'
TOPIC_ID='mailgen-gmail-watch'
SUBSCRIPTION_ID='mailgen-gmail-push'
PUSH_ACCOUNT_ID='mailgen-pubsub-push'
gcloud config set project "$PROJECT_ID"
gcloud services enable gmail.googleapis.com people.googleapis.com \
  calendar-json.googleapis.com pubsub.googleapis.com --project="$PROJECT_ID"
gcloud services list --enabled --project="$PROJECT_ID"

A Console- és a shell-útvonal ugyanazt az előkészítést végzi. A további Cloud Shell-blokkokat ebben a munkamenetben futtasd. A set -e hiba után leállítja a shellt. Új shellben a folytatás előtt állítsd vissza ezeket a változókat.

A PERMISSION_DENIED azt jelenti, hogy az operátornak projekt-, API-, Pub/Sub-erőforrás- vagy service-account IAM-hozzáférés kell. A postafiók-hozzájárulás nem ad Cloud-adminisztrációt.

A Google Auth Platform → Overview részben szükség esetén fejezd be a Get started lépést. Állítsd be a Branding alkalmazásnevet, a támogatási e-mail-címet és a fejlesztői kapcsolattartót. Ahol kérik, regisztráld a domainedet, és végezd el a tulajdonosi ellenőrzést.

Személyes Gmailhez válaszd az External lehetőséget. Az Internal csak a kiválasztott Workspace-szervezetet engedi. Fejlesztéshez tartsd meg a Testing állapotot, és vedd fel minden Google-fiókot a Test users alá.

A Data Access részben add hozzá a szükséges scope-okat:

Cél	Scope
Identitás	`openid`, `https://www.googleapis.com/auth/userinfo.email`, `https://www.googleapis.com/auth/userinfo.profile`
Levelek olvasása és módosítása	`https://www.googleapis.com/auth/gmail.modify`
Névjegyek	`https://www.googleapis.com/auth/contacts`
Naptár elérhetősége	`https://www.googleapis.com/auth/calendar.events.freebusy`

Az alkalmazás rövid OIDC-neveket, az email és a profile értéket kérheti. A Console megjelenítheti a teljes userinfo URI-kat. Az alkalmazásbejelentkezés csak identitást kér. A postafiók-kapcsolat külön kéri a postafiók-scope-okat.

Gmail-scope-okkal rendelkező External Testing refresh tokenek általában hét nap után lejárnak. Tartós használathoz publikáld a szükséges production-folyamaton keresztül, és végezd el a Google vonatkozó ellenőrzését. A gmail.modify korlátozott scope. Nyilvános, szerveroldali adathasználat biztonsági felmérést is igényelhet. A publikálás önmagában nem jelent jóváhagyást.

4. Két külön Web OAuth-kliens létrehozása

A Google Auth Platform → Clients → Create client részben válaszd a Web application lehetőséget.

A postafiók-kliensnél regisztráld a pontos PUBLIC_ORIGIN/v1/oauth/callback címet. A létrehozáskor mentsd biztonságosan a Client ID-t és a Client secretet. A titok később nem biztos, hogy látható marad. Ne használd újra az alkalmazásbejelentkezési klienst.

Hozz létre egy második Web application-t az alkalmazásbejelentkezéshez a pontos PUBLIC_ORIGIN/api/auth/callback/google címmel. Ha a felhasználók Microsofttal jelentkeznek be, és csak Gmailt kapcsolnak össze, kihagyhatod ezt a klienst, és a GOOGLE_APP_LOGIN_ENABLED=false értéken hagyhatod.

Az Authorized JavaScript origins nem helyettesítik az átirányítási URI-kat. Kerüld ott a wildcardokat és a callback-útvonalakat. Az átirányítás-regisztrációnak pontosan egyeznie kell a HTTPS-sel, a domainnel, a porttal, az útvonallal és a záró perjellel.

A local machine gépen változónként egy értékadást adj hozzá a gyökér .env fájlhoz:

GOOGLE_APP_LOGIN_ENABLED=true
BFF_GOOGLE_LOGIN_CLIENT_ID=APP_LOGIN_CLIENT_ID.apps.googleusercontent.com
BFF_GOOGLE_LOGIN_CLIENT_SECRET='APP_LOGIN_CLIENT_SECRET'
GOOGLE_APP_LOGIN_CALLBACK_URL=https://YOUR_PUBLIC_DOMAIN/api/auth/callback/google
GOOGLE_APP_LOGIN_PROXY_SECRET='YOUR_SEPARATE_PROXY_SECRET'
GOOGLE_MAILBOX_OAUTH_ENABLED=true
GOOGLE_MAILBOX_SYNC_ENABLED=true
GOOGLE_MAILBOX_WATCH_ENABLED=false
GOOGLE_MAILBOX_CLIENT_ID=MAILBOX_CLIENT_ID.apps.googleusercontent.com
GOOGLE_MAILBOX_CALLBACK_URL=https://YOUR_PUBLIC_DOMAIN/v1/oauth/callback
GOOGLE_MAILBOX_BFF_COMPLETION_URL=https://bff.YOUR_INSTANCE.ecas.local:8443/api/google-mailbox/complete
ECAS_DEPLOYMENT_TENANT_ID=YOUR_STABLE_UUID

Új, csak Google-os deploymentnél a UUID-t ezzel generáld: python3 -c 'import uuid; print(uuid.uuid4())'. A külön proxy-titkot az openssl rand -hex 32 paranccsal generáld.

Csak Google-os deploymentnél állítsd be a MICROSOFT_CONNECTOR_ENABLED=false értéket, a Microsoft/Graph mezőket pedig hagyd üresen. Vegyes deploymentnél a meglévő tenant-identitás és a Microsoft-beállítások megmaradnak. A teljes worker-kiválasztás az ECS_MEMORY_GIB=44 értéket használja, plusz a gép- és build-tartalékokat a kapacitáskövetelményekből.

A local machine gépen mentsd a postafiók-titkokat úgy, hogy a szövegük ne kerüljön a shell-előzményekbe:

umask 077
mkdir -p .docker-state/google
chmod 700 .docker-state/google
if [ -e .docker-state/google/oauth-client-secret ]; then
  printf '%s\n' 'Mailbox secret already exists. Preserve it or rotate credentials deliberately.'
else
  read -r -s -p 'Mailbox Client secret: ' mailbox_secret
  printf '\n'
  test -n "$mailbox_secret" && printf '%s' "$mailbox_secret" > .docker-state/google/oauth-client-secret
  unset mailbox_secret
fi
if [ ! -e .docker-state/google/mailbox-grant.key ]; then
  openssl rand -base64 32 > .docker-state/google/mailbox-grant.key
fi
chmod 600 .docker-state/google/oauth-client-secret .docker-state/google/mailbox-grant.key

A client-secret fájl nyers titkos szöveget tartalmaz, nem letöltött OAuth JSON-t. Ne találj ki GOOGLE_MAILBOX_CLIENT_SECRET nevű gyökér-titkos bemenetet. A futtatókörnyezet a privát fájlt olvassa.

A grant-kulcs a szerveroldali OAuth-jogosultságokat titkosítja. Nem a személyes e-mail-kulcs. Megtartott jogosultságok mellett őrizd meg az eredeti értékét. Lásd a külön titokmentéseket.

5. Hitelesített Gmail push-útvonal létrehozása

Csak lekérdezéshez hagyd ki ezt a szakaszt, és a watch legyen kikapcsolva. Push-hoz a postafiók OAuth-kliensének projektjét használd. A létrehozáshoz válassz Console- vagy shell-módot, ne mindkettőt. A meglévő erőforrásokat ellenőrizni kell, nem újra létrehozni a create parancsokkal.

Console-útvonal

Hozz létre egy Pub/Sub topicot, például mailgen-gmail-watch néven, alapértelmezett subscription nélkül. Ezen a topicon add meg a Pub/Sub Publisher szerepkört a gmail-api-push@system.gserviceaccount.com azonosítónak. A szervezeti domain-korlátozások kivételt kérhetnek.

Hozz létre egy service accountot, például mailgen-pubsub-push néven. Nincs szüksége széles projektszerepkörre vagy privát JSON-kulcsra. Jegyezd fel az e-mail-címét és a számszerű Unique ID-t, amely eltér a Project numbertől.

Hozd létre és engedélyezd a Pub/Sub service agentet ezzel: gcloud beta services identity create --service=pubsub.googleapis.com --project="$PROJECT_ID". A push service accounton add meg a Service Account Token Creator szerepkört a service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com azonosítónak.

A subscriptiont létrehozó felhasználónak add meg a Service Account User szerepkört ezen a push accounton az actAs jogosultsághoz. Ezután hozd létre a subscriptiont:

Mező	Érték
Topic	Az előkészített topic
Kézbesítés	Push
Endpoint URL	Pontosan `PUBLIC_ORIGIN/v1/pubsub/push`
Hitelesítés	Engedélyezve, a kiválasztott push service account
Audience	Pontosan ugyanaz a push endpoint
Payload unwrapping	Kikapcsolva
Lejárat	Soha nem jár le
Üzenetmegőrzés	Hét nap

Cloud Shell-útvonal

Használd a 2. szakasz változóit:

PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
PUSH_SA="${PUSH_ACCOUNT_ID}@${PROJECT_ID}.iam.gserviceaccount.com"
PUSH_ENDPOINT="${PUBLIC_ORIGIN}/v1/pubsub/push"
OPERATOR_EMAIL="$(gcloud config get-value account)"
gcloud beta services identity create --service=pubsub.googleapis.com --project="$PROJECT_ID"
gcloud pubsub topics create "$TOPIC_ID" --project="$PROJECT_ID"
gcloud pubsub topics add-iam-policy-binding "$TOPIC_ID" --project="$PROJECT_ID" \
  --member='serviceAccount:gmail-api-push@system.gserviceaccount.com' --role=roles/pubsub.publisher
gcloud iam service-accounts create "$PUSH_ACCOUNT_ID" --project="$PROJECT_ID" \
  --display-name='MailGen authenticated push'
gcloud iam service-accounts add-iam-policy-binding "$PUSH_SA" --project="$PROJECT_ID" \
  --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \
  --role=roles/iam.serviceAccountTokenCreator
gcloud iam service-accounts add-iam-policy-binding "$PUSH_SA" --project="$PROJECT_ID" \
  --member="user:${OPERATOR_EMAIL}" --role=roles/iam.serviceAccountUser
gcloud pubsub subscriptions create "$SUBSCRIPTION_ID" --project="$PROJECT_ID" \
  --topic="$TOPIC_ID" --push-endpoint="$PUSH_ENDPOINT" \
  --push-auth-service-account="$PUSH_SA" --push-auth-token-audience="$PUSH_ENDPOINT" \
  --message-retention-duration=7d --expiration-period=never

Ne add hozzá a --push-no-wrapper kapcsolót. A szerver a szokásos JSON-borítékot várja. Ezek a parancsok az aktuális operátor-felhasználót használják. A service-account impersonation más IAM-principalt használ.

Routing JSON előállítása

A Cloud Shellben add meg a nyilvános postafiók-kliens ID-t. A Console-útvonalat használóknak a 2. szakasz változóit is definiálniuk kell:

MAILBOX_CLIENT_ID='YOUR_MAILBOX_CLIENT_ID.apps.googleusercontent.com'
PUSH_SA="${PUSH_ACCOUNT_ID}@${PROJECT_ID}.iam.gserviceaccount.com"
PUSH_ENDPOINT="${PUBLIC_ORIGIN}/v1/pubsub/push"
PUSH_SUBJECT="$(gcloud iam service-accounts describe "$PUSH_SA" \
  --project="$PROJECT_ID" --format='value(uniqueId)')"
export PROJECT_ID TOPIC_ID SUBSCRIPTION_ID PUSH_SA PUSH_ENDPOINT PUSH_SUBJECT MAILBOX_CLIENT_ID
python3 - <<'PY'
import json
import os
routing = [{
    'topicName': f"projects/{os.environ['PROJECT_ID']}/topics/{os.environ['TOPIC_ID']}",
    'subscriptionId': f"projects/{os.environ['PROJECT_ID']}/subscriptions/{os.environ['SUBSCRIPTION_ID']}",
    'pushAudience': os.environ['PUSH_ENDPOINT'],
    'pushServiceAccountEmail': os.environ['PUSH_SA'],
    'pushServiceAccountSubject': os.environ['PUSH_SUBJECT'],
    'oauthClientId': os.environ['MAILBOX_CLIENT_ID'],
}]
print("GOOGLE_PUBSUB_CONFIG_JSON='" + json.dumps(routing, separators=(',', ':')) + "'")
PY

Másold a teljes kiírt értékadást a helyi gyökér .env fájlba. Állítsd be a GOOGLE_MAILBOX_WATCH_ENABLED=true értéket a GOOGLE_MAILBOX_SYNC_ENABLED=true mellett. Meglévő routing-tömböket bővíts, ne cseréld le őket más projektekre.

Minden bejegyzés azonosít egy teljes topic/subscription-párt egy projektben, a pontos audience-t, a service account e-mail-címét, a számszerű subject-et és az OAuth-kliens vagy Workspace-hitelesítő adat hivatkozását. A futtatókörnyezet 1–50 bejegyzést fogad el, és elutasítja az ismétlődő subscription-azonosítókat. A backend ellenőrzi a Google aláírt OIDC-tokenjét. Nincs szükség push service account privát kulcsára.

6. Routing ellenőrzése és indítás

A Cloud Shellben ellenőrizd az IAM-et és a pontos subscription-routinget:

gcloud pubsub topics get-iam-policy "$TOPIC_ID" --project="$PROJECT_ID"
gcloud iam service-accounts get-iam-policy "$PUSH_SA" --project="$PROJECT_ID"
gcloud pubsub subscriptions describe "$SUBSCRIPTION_ID" --project="$PROJECT_ID" \
  --format='yaml(name,topic,pushConfig,expirationPolicy,messageRetentionDuration)'

Az OIDC e-mail-címének és audience-ének egyeznie kell a JSON-nal. A payload wrapping maradjon bekapcsolva. A soha nem jár le beállítás azt jelenti, hogy nincs lejárati TTL. Hiányzó IAM-jogosultságokért kérd a projektoperátort, ne gyengítsd a hitelesítést.

A local machine gépen folytasd az első setuppal, vagy egy beállított deploymenthez használd a szokásos életciklust. A kapcsolók az OAuth-bridge, az onboarding/history polling és a push-ingress profilokat választják ki, az alkalmazásbejelentkezéstől függetlenül.

Személyes Gmail-postafiók összekapcsolása

Használj bejelentkezett MailGen-munkamenetet, amelynek szereplője rendelkezik accounts.manage jogosultsággal. A Google-postafiók OAuth-bridge-nek engedélyezettnek és működőképesnek kell lennie.

Nyisd meg a /onboarding oldalt a BFF HTTPS-címén.
A Kapcsold össze a mailboxod részben válaszd a Folytatás Google-lel gombot.
Hagyd jóvá a dedikált postafiók-hozzájárulást a Gmailhez, a névjegyekhez és a naptár elérhetőségéhez. A Google-alkalmazásbejelentkezés külön identitási jogosultság.
A callbackig ugyanabban a MailGen-munkamenetben maradj. A /api/google-mailbox/complete visszatér a /onboarding oldalra, és kiválasztja a csatlakoztatott Google-fiókot.
Várj a Postafiók előkészítése lépésnél, amíg meg nem jelenik a „A munkaterület megnyitása…” felirat, és a munkaterület meg nem nyílik.

A Google kezdeti szinkronizálása automatikusan indul. Az oldal ezt írja ki: A mailbox sync folyamatban van. A MailGen akkor nyílik meg, amikor a levelek és a search készen állnak. Ez a folyamat a Google-haladást és -helyreállítást használja, függetlenül a Microsoft kezdeti import dispatchertől.

Ha kéri, válaszd az Email-key setup megnyitása lehetőséget, és kövesd a személyes kulcs mentését és feloldását. Új tulajdonos létrehozza és letölti a kulcsmentést. Meglévő titkosított tartalomhoz importáld az eredeti tulajdonos mentését.

Ha a setup megáll, csak akkor válaszd a Kezdeti beállítás újrapróbálása lehetőséget, ha az felajánlja. Megtagadott hozzáférésnél ellenőrizd a connector jogosultságait az administratorral. Titkosítási zárnál az újrapróbálás előtt állítsd vissza a helyes eredeti kulcsot. Munkamenet-eltérés vagy lejárt callback esetén indítsd újra a Google-kapcsolatot a /onboarding oldalon az aktuális munkamenetben. Ne játszd le újra a mentett callback URL-t.

Küldj egy jóváhagyott teszt-üzenetet a csatlakoztatott postafiókba. Ellenőrizd az érkezését, a törzsét és a szinkronizációs állapotot. Ha a watch engedélyezve van, nézd meg a Pub/Sub kézbesítési metrikáit is. Az erőforrás-létrehozás vagy egy OAuth-visszatérés önmagában nem igazolja a befejezett szinkronizációt. Lásd az első bejelentkezést.

A MailGen az előkészített topicra hoz létre és újít meg Gmail-postafiók-watcheket. A Cloud-subscription külön routing-erőforrás.

A Workspace által kezelt hozzáféréshez emellett domain-wide delegation, jóváhagyott scope-ok és explicit postafiók-regisztráció kell. Az Admin SDK önmagában való engedélyezése nem elegendő. Használd a Workspace-konfigurációt.

Hivatalos szerződések: OAuth consent, Web OAuth credentials, Gmail push, hitelesített Pub/Sub push, és subscription create.

1. Projekt létrehozása és címek kiválasztása​

2. API-k bekapcsolása​

3. OAuth-hozzájárulás beállítása​

4. Két külön Web OAuth-kliens létrehozása​

5. Hitelesített Gmail push-útvonal létrehozása​

Console-útvonal​

Cloud Shell-útvonal​

Routing JSON előállítása​

6. Routing ellenőrzése és indítás​

Személyes Gmail-postafiók összekapcsolása​