Microsoft Azure app registration

Part A — Register the application

1. 1Open entra.microsoft.com → sign in → Identity → Applications → App registrations.
2. 2Click New registration.
   • Name: Fiko Email Integration
   • Supported account types: Accounts in any organizational directory and personal Microsoft accounts (multitenant + personal)
   • Redirect URI: Platform = Web
3. 3Paste redirect URI exactly:

   https://msg.fikosrv.com/v2/email/oauth/microsoft/callback

4. 4Click Register.

   Expected result

   Overview page shows Application (client) ID — copy it for env vars.

Part B — Authentication settings

5. 5Left menu → Authentication → verify redirect URI is listed under Web platform:

   https://msg.fikosrv.com/v2/email/oauth/microsoft/callback

6. 6Under Implicit grant and hybrid flows — leave both unchecked:
   • Access tokens: OFF
   • ID tokens: OFF
   Fiko uses authorization code flow only.
7. 7Under Supported account types — confirm: Accounts in any organizational directory and personal Microsoft accounts (multitenant + personal).

Part C — Create client secret

8. 8Left menu → Certificates & secrets → Client secrets → New client secret.
9. 9Description: Fiko messaging → choose expiry (24 months recommended) → Add.
10. 10Copy the Value column immediately (not the Secret ID).

    Expected result

    You cannot view the secret again after leaving this page. Store it in your secrets manager.

Part D — API permissions

11. 11Left menu → API permissions → Add a permission.
12. 12Choose Microsoft Graph → Delegated permissions.
13. 13Search and add each permission:

    Delegated permissions Fiko requires

    Permission	Why Fiko needs it
    Mail.ReadWrite	Read inbox + junk/spam, update read state, ingest messages
    Mail.Send	Send agent replies from the connected mailbox
    offline_access	Issue refresh token for background sync without re-login
    User.Read	Read signed-in user profile (mailbox address) during OAuth

14. 14Click Add permissions.
15. 15Click Grant admin consent for [your tenant] (requires admin role).

    Expected result

    Status column shows green checkmarks for all four permissions. Customer tenants may still need their own admin consent on first connect.

Part E — Generate encryption key and set env vars

16. 16Generate EMAIL_ENCRYPTION_KEY (same command as Google setup — reuse one key across both Google and Microsoft if both are enabled):

    node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

17. 17On fiko-messaging-service, set:

    MICROSOFT_OAUTH_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    MICROSOFT_OAUTH_CLIENT_SECRET=your-secret-value
    MICROSOFT_OAUTH_CALLBACK_URL=https://msg.fikosrv.com/v2/email/oauth/microsoft/callback
    EMAIL_GRAPH_WEBHOOK_BASE_URL=https://msg.fikosrv.com
    EMAIL_ENCRYPTION_KEY=your-base64-32-byte-key

18. 18On fiko-core-service, copy client ID, secret, and encryption key:

    MICROSOFT_OAUTH_CLIENT_ID=...
    MICROSOFT_OAUTH_CLIENT_SECRET=...
    EMAIL_ENCRYPTION_KEY=...

19. 19Redeploy / restart both services after updating env.

Part F — Graph webhook and subscriptions

After OAuth connect, Fiko automatically creates two Graph change notification subscriptions per channel. Without a public HTTPS webhook, Fiko falls back to polling (~1 minute).

20. 20Set EMAIL_GRAPH_WEBHOOK_BASE_URL to messaging-service public origin only:
    • Correct: https://msg.fikosrv.com
    • Wrong: https://msg.fikosrv.com/v2/email (no path suffix)
21. 21Fiko builds notification URL per channel:

    {EMAIL_GRAPH_WEBHOOK_BASE_URL}/v2/email/graph/notify/{channelId}
    
    # Example:
    https://msg.fikosrv.com/v2/email/graph/notify/abc123-channel-uuid

22. 22Validation handshake — when Fiko creates a subscription, Microsoft sends a validation request with ?validationToken=.... Fiko responds with the token as plain text. No manual action needed if messaging-service is running and reachable on port 443.

    Expected result

    Log: Graph subscription validation for channel ...
23. 23Ensure TLS certificate is valid and https://msg.fikosrv.com is reachable from the public internet (Microsoft Graph servers).

Part G — Verify end-to-end

24. 24In Fiko dashboard → Apps → Email → Add new.
25. 25Choose Connect mailbox → Next → click Connect Microsoft.
26. 26Sign in with a test mailbox → accept permissions → finish channel setup.

    Expected result

    Connected mailbox shown with "Mailbox verified during OAuth sign-in." messaging-service log: Graph subscriptions created for channel ...
27. 27Send test email to the mailbox → confirm chat appears in Fiko (seconds with webhook, ~1 minute with polling fallback).
28. 28(Optional) Send test to junk/spam folder rules — Fiko also watches junkemail folder.