saas-security

SaaS Integration Security

Rules (for AI agents)

ALWAYS

• Verify an inbound webhook against that vendor's documented scheme, and do not generalize from another one. Vendors differ in the header, in the secret, and — the part that breaks a generalized implementation — in the canonical string that gets signed. Some sign the raw body, some sign a version prefix plus a timestamp plus the body, some sign the HTTP method and path as well. Read the vendor's page for the vendor you are integrating; a signature routine copied from a different vendor produces a receiver that rejects every legitimate event, and the fix someone reaches for is to turn verification off.
• Verify against the raw request body, exactly as received, before any parsing or re-serialization. A framework that decodes JSON and re-encodes it changes whitespace and key order, and the HMAC no longer matches — which again ends with verification being disabled rather than fixed.
• Check the timestamp the vendor sends and reject requests outside a short window, then reject replays inside it by recording delivery or event ids. A signature is valid forever; the window narrows the replay opportunity and the id store closes it.
• Compare signatures in constant time. crypto-misuse owns the comparison API for each language.
• Treat the signature as proof of who sent the payload, not who the payload is about. This is the distinction that matters most in this domain: a verified Zoom or Calendly or HubSpot event genuinely came from that vendor, and the email, from, or custom fields inside it may still be attacker-chosen — anyone who can book a meeting or submit a form controls them. Resolve the subject to a canonical id server-side. auth-security owns the general rule for producer-asserted identity.
• Give each integration its own credential, and each environment its own. A refresh token, connected app, or service account shared between dev and prod puts production credentials inside dev's blast radius, and a credential shared between integrations gives each the union of what any of them needs. Name service accounts for their purpose so a later reviewer can tell what revoking one would break.
• Request the narrowest scope you actually call, and prefer a read-only variant where the platform offers one. Scopes are granted once, at consent, and nobody revisits them; a scope requested speculatively is a permanent grant.
• Treat a bulk export of employee, customer or billing records as a data boundary: log the authenticated principal, the query, the row count and the destination, and alert on volume that departs from that integration's own baseline. For HRIS and ERP systems this is the primary control — the integration is authorized, and the question is how much it took.
• Authenticate a SCIM or directory-sync endpoint you expose, rate-limit it, and audit every user and group write. Note what the major identity providers actually send: a static OAuth bearer token, configured once in their admin console. Client certificates are generally not on offer, so the practical controls are a high-entropy token you can rotate, a source-address restriction where the IdP publishes ranges, and treating every write as an audit event.