Security & OAuth Verification Disclosure

Workspace Security Module Compliance & Scope Minimization Note

This public disclosure documents how MailPosture connects to Microsoft 365 (Microsoft Graph API) and Google Workspace (Admin SDK & Gmail Settings API). Every permission is strictly read-only, all OAuth tokens and finding identifiers are encrypted at rest using AES-256-GCM, and no automated write actions are ever executed on customer tenants.

AES-256-GCM at Rest

All OAuth access tokens, refresh tokens, and tenant finding details (affected UPNs and forwarding targets) are encrypted at the application layer with a 256-bit key (SERVER_ENCRYPTION_KEY), unique 96-bit IVs, and 128-bit authentication tags before database persistence.

Token Vault & Rotation

Refresh tokens live in an isolated workspace_token_vault table. Each refresh increments rotation_version, records a one-way SHA-256 lineage hash of the superseded token, and overwrites the ciphertext.

Step-Up Scope Separation

Initial onboarding requests only core directory, MFA, policy, and sharing read-only scopes. Mailbox forwarding and inbox rule inspection require explicit administrator step-up consent and never read email bodies.

Human Approval Required

AI-generated remediation playbooks provide plain-language explanations and step-by-step portal instructions. MailPosture never modifies tenant settings automatically; every remediation requires explicit human administrator approval.

1. Microsoft 365 (Microsoft Graph API) Permission Matrix

Zero ReadWrite, Mail.Read, or Mail.Send scopes are requested.

Permission / Scope	Consent Tier	Access Mode	Posture Check Powered	Strict Justification
openid	Core Onboarding	Delegated Identity	Tenant Identity & Consent Verification	Authenticates the consenting tenant administrator and validates OIDC claims.
profile	Core Onboarding	Delegated Identity	Tenant Identity & Consent Verification	Reads administrator display name and tenant metadata.
email	Core Onboarding	Delegated Identity	Tenant Identity & Consent Verification	Identifies the consenting administrator email and primary domain.
offline_access	Core Onboarding	Delegated Identity	Encrypted Token Vault Refresh Rotation	Issues a refresh token so posture checks can rotate credentials without re-prompting.
User.Read.All	Core Onboarding	Read-Only	MFA Coverage Denominator & Account Status	Lists active directory users (id, userPrincipalName, accountEnabled) to establish MFA coverage.
UserAuthenticationMethod.Read.All	Core Onboarding	Read-Only	MFA Coverage / Users Without MFA	Reads /reports/authenticationMethods/userRegistrationDetails (admin-consented, paginated up to 10,000 users with 429 graceful degradation) to identify accounts without MFA.
Policy.Read.All	Core Onboarding	Read-Only	Legacy Authentication Enabled Check	Reads Conditional Access policies and security defaults to verify whether IMAP/POP3/SMTP Basic Auth is blocked.
Organization.Read.All	Core Onboarding	Read-Only	External Sharing Settings & Verified Domains	Reads organization guest/external collaboration settings and maps verified domains to monitored MailPosture domains.
MailboxSettings.Read	Optional Step-Up	Read-Only	Mailbox Forwarding Rules & Suspicious Inbox Rules (BEC)	Inspects delegated mailboxSettings (forwardingSmtpAddress) without reading email message bodies.

2. Google Workspace (Admin SDK & Gmail Settings API) Permission Matrix

Compliant with Google API Services User Data Policy (Limited Use Requirements).

OAuth 2.0 Scope	Consent Tier	Access Mode	Posture Check Powered	Strict Justification
openid	Core Onboarding	Delegated Identity	Tenant Identity & Consent Verification	Verifies the consenting Google Workspace administrator session.
email	Core Onboarding	Delegated Identity	Tenant Identity & Consent Verification	Reads the administrator email address and primary Workspace domain.
profile	Core Onboarding	Delegated Identity	Tenant Identity & Consent Verification	Reads administrator profile metadata.
https://www.googleapis.com/auth/admin.directory.user.readonly	Core Onboarding	Read-Only	MFA Coverage / Users Without 2-Step Verification	Lists directory users (customerId, isEnrolledIn2Sv, isEnforcedIn2Sv) to calculate 2SV coverage and flag unprotected accounts.
https://www.googleapis.com/auth/admin.directory.domain.readonly	Core Onboarding	Read-Only	Unified Security Score Domain Mapping	Reads verified Google Workspace domains to pair tenant posture scores with MailPosture SPF/DKIM/DMARC scores.
https://www.googleapis.com/auth/admin.reports.audit.readonly	Core Onboarding	Read-Only	Legacy Authentication & External Sharing Settings	Audits tenant-level POP/IMAP legacy access toggles and external Drive/Calendar link-sharing exposure events.
https://www.googleapis.com/auth/gmail.settings.basic	Optional Step-Up	Read-Only	Mailbox Forwarding Rules & Suspicious Inbox Filters (BEC)	Reads Gmail auto-forwarding (getAutoForwarding) and filter definitions (forward + trash/skipInbox BEC rules) without reading message bodies.

Microsoft Graph Reports API Quota & Large Tenant (>10,000 Users) Behavior

Evaluating tenant MFA registration via UserAuthenticationMethod.Read.All requires tenant-wide Administrator Consent and queries GET /v1.0/reports/authenticationMethods/userRegistrationDetails?$top=999. Because Microsoft Graph enforces strict throttling limits on the Reports API:

· MailPosture paginates up to a deterministic ceiling of 10,000 users (10 pages) per synchronous audit pass.
· If Microsoft Graph returns HTTP 429 Too Many Requests or 503, the evaluator honors Retry-After or degrades gracefully to a partial sample (isSampled: true) rather than failing the tenant check.

AI Remediation Telemetry & Zero-Auto-Action Guarantee

Remediation guidance uses a 3-tier server-side execution chain: gemini:gemini-3.8-flash → openai:gpt-4o-mini → fallback:playbook-v1.

· Every remediation logs and records the serving provider_model for audit traceability.
· Only aggregated finding summaries are passed to generate step-by-step instructions.
· Every generated checklist enters pending_approval and requires explicit administrator sign-off before execution.