Enterprise SaaS and Third-Party Integration Playbook

A product team connects its customer-support platform to the application. The connector copies account names, contact details, plan level, and recent order status into support tickets. It can update customer tags through OAuth, and a ticket.closed webhook starts an internal follow-up job. Support managers administer the vendor console.

At renewal, the engineer who installed the connector has left. The OAuth grant says it may read and write all customer objects, not merely the fields used in tickets. Nobody is sure whether the webhook secret was ever rotated, who still has vendor-admin access, or whether canceling the contract would stop the nightly sync.

The integration is not a pipe attached to the system. It is delegated authority: a path by which another system can observe data, hold credentials, send commands, and retain copies. It is under control only when the team can name that authority, restrict it, observe its use, and withdraw it completely.

Inventory the integration, not merely the vendor

A vendor assessment describes an organization. The integration record describes what one installation can do. The same support vendor might host a public knowledge base, store regulated customer conversations, or hold an organization-wide OAuth grant. Those installations do not deserve the same review.

Classify the actual integration by the sensitivity and volume of data it receives; the actions it can perform; whether it is internet-facing; its access to many users or tenants; its operational criticality; the harm of false, delayed, or replayed messages; and the difficulty of leaving. An identity provider or payment processor can stop the business. A chat bot may be less critical but still read private channels and speak as trusted automation. A marketing tag may have little write authority while observing a wide slice of user behavior.

Create the inventory entry before granting access. Name the business purpose, accountable owner, technical operator, vendor, connected systems, environments, data classes, authentication method, permissions, inbound endpoints, administrators, log sources, incident contact, contract owner, renewal date, review trigger, and tested exit path. Link credentials by secret identifier, never by secret value.

Personal accounts, browser-installed apps, marketplace trials, copied tokens, and temporary bots need the same entry. Their ease of installation is precisely why they disappear from ordinary architecture records.

Vendor data-flow template

Draw or record one flow for the support connector from source to final retention. For every crossing, capture:

• Source and destination: the application database, connector worker, vendor region, subprocessor, administrator console, webhook receiver, and any archive or analytics copy.
• Data: exact fields and attachments, their classification, tenant scope, volume, transformation, encryption expectations, and retention or deletion rule.
• Authority: the human or workload identity, credential, grant type, scopes, consent authority, and policy check that permits the crossing.
• Return path: webhooks, API writes, SSO or SCIM changes, embedded content, support access, exports, and scheduled jobs that can affect the local system.
• Operations: owner, logs, alerts, failure behavior, incident contact, and the control that stops the flow.

Include metadata and derived copies. A ticket attachment, transcript, debug payload, search index, and export may carry more sensitive material than the handful of fields named in the original design. Then minimize the flow: send only the required fields, tenants, events, and history. If ticket handling needs plan level and the last four characters of an order reference, a full customer and order sync is not justified by convenience.

Choose authentication by the authority required

Start with the workflow. A human entering a vendor console, a background service reading tickets, and an inbound webhook are different actors and should not share one credential.

Use individual SSO accounts with strong MFA for people. Use a dedicated application identity, managed OAuth installation, or narrowly scoped service account for workloads. Prefer short-lived credentials where the systems support them. Keep client secrets and API keys in the approved secrets system with an owner, access logging, rotation and emergency-revocation procedures; separate production from non-production.

Long-lived API keys are sometimes the only interface a vendor offers. That limitation does not turn a broad key into a safe default. Restrict where it can be read, limit its permissions and network use where possible, monitor it, test rotation, and record a dated decision to keep or replace the integration. Never let a personal access token become production infrastructure simply because it made the first demonstration work.

OAuth app review form

Review an OAuth app from requested behavior outward. Record the installation owner, client or application id, publisher, redirect URIs, grant type, consent authority, user population, token lifetime, refresh or offline access, token storage, and revocation route. For each requested scope, write the exact operation and object that requires it.

For the support connector, read:customer_profile might support ticket context while write:all_customers does not. Ask whether read-only access is enough, whether access can be limited by tenant or project, and whether the action should use an application identity or the signed-in user’s delegated authority. Treat organization-wide admin consent separately from one user’s consent: its blast radius is different even if the consent screen looks the same.

Test the claims. Install the smallest grant in a non-production environment and exercise the required workflow. Attempt an operation outside the proposed scope and require denial. Revoke the grant and confirm that both access and refresh fail. Inspect what the provider’s revocation actually invalidates; deleting a local token is not evidence that the remote grant is gone.

When the vendor exposes only a broad scope, name the excess authority. Record the owner, business necessity, isolation, monitoring, compensating controls, reapproval date, and a condition that would trigger replacement. “Standard integration” is not a risk description.

Treat webhooks as untrusted messages

The ticket.closed webhook arrives from a known vendor, but its body still cannot authorize a sensitive local action. Verify the signature over the raw body according to the provider’s scheme, use the correct secret or public key, enforce a bounded timestamp or replay window, and validate the expected event type and tenant mapping. Parse with size and schema limits. Keep secrets out of URLs, logs, and error responses.

Retries are normal. Store the provider’s event identifier or a stable idempotency key and make the handler safe when an event arrives twice or out of order. Rate-limit and isolate the receiver so a flood cannot starve ordinary application traffic.

For a high-impact transition—payment settled, account disabled, privilege changed—treat the webhook as notice that something may have happened. Reconcile through an authenticated API or authoritative local state before acting. A valid signature establishes message origin and integrity; it does not prove that the claimed transition is current, belongs to the right tenant, or satisfies local policy.

Test a valid delivery, bad signature, stale timestamp, replay, duplicate, wrong tenant, unknown event, oversized body, reordered transition, and provider timeout. Preserve enough evidence to distinguish rejection from handler failure without logging the sensitive payload by default.

Govern administrators and support access

The vendor console may control exports, retention, SSO, OAuth apps, webhook destinations, audit logs, support sessions, and billing. Its administrators hold production authority even when they cannot sign in to the production application.

Use named accounts, strong MFA, least-privilege roles, and periodic review. Separate routine administration from security-sensitive changes where the platform permits it. Shared or break-glass accounts need controlled custody, alerting on use, and rotation after use. Remove the account once an individual or narrower administrative path is available.

Vendor personnel may also obtain support access. Record whether support can view customer content, impersonate users, export data, or change configuration; how access is approved; whether it expires; and where the session is logged. A contract clause about support is not a technical control unless the team can see and govern the resulting access.

Make production use explainable

The logs for the support connector should answer a future responder’s questions: which integration read or changed which object, for which tenant, using which grant, at what time, with what result? Join vendor audit logs, local gateway or worker logs, identity events, secrets access, and configuration changes through stable integration and actor identifiers.

Alert on events that change authority or suggest misuse: a new token, widened scope, new administrator, changed redirect or webhook destination, disabled audit log, SSO bypass, repeated signature failures, replay, unusual export volume, unexpected tenant breadth, or calls continuing after revocation. Route each alert to a named owner and test at least one path end to end. A log retained in a vendor console is not an operating control if nobody can retrieve it during an incident.

Monitor dependency health as well as hostile behavior. Delayed or duplicated webhooks, expired credentials, rate limiting, schema changes, and silent partial syncs can corrupt local decisions. Define whether the integration fails closed, queues work, degrades to manual operation, or becomes unavailable. Critical integrations need a service response that does not depend on the compromised or unavailable vendor console.

Prepare for the vendor’s incident

Before production use, record the vendor’s security and operational incident channels, expected notification route, after-hours path, and the internal owners for engineering, security, procurement, privacy, legal, and customer communication. During an event, engineering should record facts—affected integration, time window, credentials, data, actions, copies, and containment—not improvise legal conclusions.

Contract and security evidence should answer the risks in the integration record. Depending on the class, that may include review results, data-processing and retention terms, subprocessor locations, audit or assessment reports, penetration-test summaries, encryption and key-handling statements, support-access controls, availability commitments, evidence-preservation capability, breach-notification language, and deletion obligations. Store the executed terms and current evidence where responders and owners can find them, not only in a procurement mailbox.

Evidence ages when the integration changes. Reopen the review for a new data class or region, broader permission, automation of a formerly manual action, new subprocessor, acquisition, incident, major control change, increased criticality, or renewal. The question is not whether a report is still within its date window; it is whether the evidence still covers the authority now in use.

Design the exit before approving the entrance

Return to the support connector. Canceling its contract would not necessarily revoke its OAuth grant, stop the worker, delete retained tickets, remove vendor administrators, or make the webhook receiver reject old messages. Those are separate edges, and the offboarding plan must close each one.

Vendor offboarding checklist

Before approval, rehearse the exit in non-production and record who can perform it. At offboarding:

1. Freeze new installations and configuration changes; preserve the inventory record, approvals, relevant logs, and any evidence needed for an active incident.
2. Stop scheduled syncs, workers, marketplace apps, automation rules, and inbound processing. Put critical business work onto the planned manual or replacement path.
3. Revoke remote OAuth grants and refresh tokens, disable service accounts and API keys, remove webhook subscriptions, and rotate any local secret exposed to the vendor.
4. Remove vendor users, internal administrators, support access, SSO and SCIM connections, shared mailboxes, and recovery routes. Transfer ownership of data and automation first.
5. Export only the records the organization must retain, with an owner and access policy. Request deletion of other vendor and subprocessor copies according to the applicable agreement; record any retention that cannot yet end.
6. Watch vendor and local logs for attempted calls, webhook deliveries, sync activity, and use of retired credentials. Investigate activity instead of assuming it is harmless cleanup.
7. Record evidence for every edge: disabled grant, failed refresh, deleted webhook, stopped job, closed account, data disposition, and monitoring confirmation. Keep the integration open in the inventory until the evidence is complete.

An emergency exit may reverse the first two steps: revoke authority before preserving convenience. The inventory should make that decision possible by showing which business process will fail and who owns the fallback.

Third-party integration release checklist

Before enabling or materially changing an integration, walk one ordinary transaction and one denied transaction across the boundary:

• Inventory and class: purpose, owners, systems, criticality, incident impact, review triggers, renewal, and exit are recorded for this installation.
• Data flow: exact fields, tenants, destinations, return paths, subprocessors, retention, and deletion are known and minimized.
• Authentication and authority: each human and workload has a distinct, protected, revocable identity; OAuth scopes and API permissions have been exercised at their minimum and outside-scope actions fail.
• Inbound trust: webhooks are verified, bounded, replay-resistant, idempotent, tenant-safe, and reconciled before high-impact action.
• Administration and evidence: administrators and support access are controlled; current contract and security evidence covers the integration’s real authority.
• Operations: logs reconstruct use, alerts reach an owner, dependency failures degrade deliberately, and incident contacts work.
• Revocation: the team has stopped the integration in a rehearsal and knows how to prove that credentials, jobs, inbound paths, access, and retained data have reached their intended end state.

The renewal problem is now answerable. The team can narrow or explicitly accept the OAuth grant, rotate and test the webhook secret, review administrators, trace the nightly sync, and rehearse revocation before signing again. A vendor relationship may continue for years; its authority should never survive by accident.