Operating connectors

2. Nine routes exist, but nobody owns the map

Nine connectors are installed across your team. One reads shared files, one opens tickets, and another can update inventory. Two were installed by people who have left. The client shows friendly connector names, but nobody can say which publisher supplied each executable, whose identity reaches the source, whether updates arrive automatically, or which tool calls are retained.

Then a connector changes overnight. A tool gains an extra parameter and begins returning more fields. In the Lab, an unpublished manuscript could become visible outside its project group. In the Company, a stock update could be attributed only to a shared service account. Disabling one user's assistant access would not answer what happened or stop the connector for everyone.

This is a Level 5 Operator problem: work can stop across the lab or company when a shared route fails, and the controls must survive the person who installed it. You need a living inventory, per-user authorization, an event for every call, an evidence-based third-party review, and a removal procedure that proves a retired connector is no longer discoverable or callable.

3. After this you can

• Run connectors for a whole team with per-user permissions and prove two users receive different effective access.
• Log every tool call and audit it without turning the log into an unrestricted copy of source data or credentials.
• Judge a third-party connector before you install it from its publisher, provenance, requested permissions, update path, and removal evidence.
• Maintain a connector inventory with owners, revisions, users, source reach, write authority, retention, review dates, and stop controls.
• Deprecate one connector and prove discovery, invocation, credentials, processes, and dependent workflows are cleanly handled.

4. Prerequisites

• T14-L04 | Build your own connector, including its narrow Northstar Inventory contract and negative write test.
• T12-L05 | Operate governance, including control ownership, review evidence, exceptions, and incident routines.
• An approved non-production connector client or gateway, identity provider, log destination, and synthetic source system.
• Two synthetic human identities with different group memberships, plus permission to revoke their test grants.
• Access to connector manifests, exact package or image identifiers, deployment configuration, source-system grant metadata, and update settings without exposing secret values.
• A second operator who can perform the removal verification from the inventory and runbook.

Use only public, synthetic, or explicitly approved data. The examples use reserved .invalid identities and fictional inventory, literature, sample, ticket, supplier, and customer records. Do not copy tokens, authorization headers, cookies, participant records, customer messages, unpublished findings, contracts, source responses, or production endpoints into the exercise artifact. Run removal and permission tests in non-production. If a test could interrupt real work, stop and use a fixture environment.

5. The idea in one page

A connector is not merely an installed integration. It is a changing route from a person or workload, through executable code and a tool contract, to another system. Operate the complete route:

principal -> client -> connector revision -> named tool -> source authorization
         -> bounded result -> audit event -> owner, alert, review, and stop control

The client authenticates the user, but every connector request must carry or resolve a stable principal. The connector then authorizes that principal for the exact operation and resource. Prefer delegated, audience-restricted, short-lived user access where the source supports it. If an approved connector must use a workload identity, do not pretend that the workload credential is the user: preserve the initiating principal, enforce a server-side per-user policy before source access, restrict the workload grant to the connector's narrow job, and log both identities. A shared credential with no reliable initiator makes revocation and attribution fail together.

Inventory what can change behaviour or authority: publisher, acquisition source, exact revision or digest, transport and endpoint, tools, operations, resources, identity path, source grant, users and groups, owner, update channel, approval, tests, logs, retention, dependencies, stop control, and review date. Unknown is a state: mark it BLOCKED, not probably safe.

Create one audit event for every attempted tool call, including denied and failed calls. The minimum useful event identifies time, event and trace IDs, environment, stable initiating principal or approved pseudonymous identifier, connector and revision, tool, normalized argument names or safe categories, authorization result, result category, latency, and policy revision. For write tools, record the target class, action, approval or confirmation reference, and source transaction ID. Exclude tokens and secrets. Do not retain raw arguments or returned content by default; use approved field allowlists, references, hashes, counts, and classifications. Retention is a documented decision with purpose, readers, duration, deletion mechanism, and verification.

Judge third-party code before installation, not after the first incident. Verify the publisher through an official source, record the exact artifact and integrity evidence, inspect the complete startup command, manifest and tool list, compare requested filesystem, network and source permissions with the task, review disclosed dependencies and security support, choose a controlled update channel, test in isolation, and prepare removal and rollback. A signature or checksum proves identity or integrity only to the extent of its trust chain; it does not prove that the code is safe or appropriately scoped.

Deprecation is a service change. Find consumers, announce the replacement or manual fallback, freeze changes, block new assignments, revoke grants and credentials, remove discovery, stop runtime processes, test direct invocation, preserve required audit evidence, monitor for attempts, and assign residual work. Deleting a client entry while a token or server remains active is not removal.

6. The worked example: turn the Level 4 connector into an operated service

Continue the running Level 5 stack with the synthetic Northstar Inventory connector from T14-L04. Do not point that training package at a real source. In this exercise, a centrally managed test gateway exposes the read-only Northstar tool to approved users, produces sanitized JSON Lines events, and contains a separate fictional connector named Legacy Stock Search that will be retired. The exact product is not important; observed behaviour is.

Create one file, connector-inventory.md. It is the single artifact for this book. Put the inventory, third-party review, permission tests, audit sample, removal plan, results, finding, and next review in that file rather than producing separate reports.

Establish the inventory schema

Begin with these fields. Keep stable IDs even when display names change.

Populate nine synthetic rows to match the opening scenario. The compact view below is a starting summary; link each row to its expanded evidence section inside the same file.

CON-008 is not made safer by filling unknown cells from memory. Mark its calls blocked immediately in the test gateway and investigate from manifests, deployment records, the source authorization console, and observed tests. The inventory should make uncertainty operationally visible.

Map identity to effective permission

Use two synthetic identities per framing:

Configure the gateway to pass a stable identity derived from the approved authentication context, not a display name supplied in a prompt or tool argument. The connector's policy maps the identity's current group to its resource prefix. The source credential for this synthetic service is read-only and restricted to the same fixture. In a real connector, document whether the source sees delegated user identity or an application identity and where per-user authorization is enforced.

Run these bounded checks for the selected framing:

Restore only the membership needed for the rest of the non-production exercise. Record actual timestamps, event IDs, elapsed propagation, and connector revision. A configuration screenshot is not proof of per-user permission; different observed outcomes are.

Lab framing: operate the literature and sample routes

The Lab inventory supports the existing literature pipeline and sample tracker. CON-003 may search only the synthetic paper index and return citation metadata. CON-004 may update a synthetic sample location only for lab-sample-coordinators, with a confirmation reference and source transaction ID. It cannot read participant data, instrument credentials, personal drives, unpublished manuscripts, or another group's sample namespace.

Test a literature user who can call CON-003 but not update CON-004. Then test a sample coordinator's approved harmless update against a synthetic sample and verify both the authorization event and source transaction. Removing the coordinator group must deny a new update. If the connector uses an application identity at the sample system, the event must contain both the coordinator's stable principal and the application identity; the source transaction alone is insufficient attribution.

The affected people are group members, collaborators relying on the weekly review, and sample coordinators relying on current locations. A silent connector change can stop review or corrupt shared tracking. The manual fallback is a named read-only export and a human-controlled tracker update, with no attempt to bypass the blocked connector using a personal token.

Company framing: operate the ticket and inventory routes

The Company inventory supports the request tracker and shared inventory. CON-005 may change the queue and status of fictional tickets for co-support; it cannot send customer messages, issue refunds, export customer lists, or administer users. CON-002 remains read-only for CO-ITEM-*.

Test a stock reader who can use CON-002 but cannot update tickets. Test a support user who can perform one approved synthetic queue change and receives a source transaction ID. Then remove the support membership and require a denied new call. Keep customer text out of the retained test artifact; a fictional ticket ID and normalized action are enough.

The affected people are support staff, inventory users, and downstream teams relying on routing. The fallback is manual triage through the approved ticket interface and a read-only stock view. A connector outage must not trigger a broad shared credential or an unrestricted browser automation.

Prove an event exists for every attempted call

Write the event contract before running the checks. This provider-neutral example uses invented values:

{
  "event_id": "evt-syn-0042",
  "trace_id": "trace-syn-0042",
  "occurred_at": "2026-09-04T10:15:00Z",
  "environment": "connector-training",
  "principal_ref": "user:synthetic-alex",
  "workload_ref": "service:northstar-readonly",
  "connector_id": "CON-001",
  "connector_revision": "sha256:[recorded-test-digest]",
  "tool": "read_inventory_item",
  "argument_shape": ["item_id"],
  "resource_class": "LAB-ITEM-*",
  "authorization": "allowed",
  "result_category": "success",
  "returned_field_count": 6,
  "policy_revision": "connector-policy-r7",
  "latency_ms": 18,
  "retention_class": "connector-metadata-30d"
}

Do not invent a digest or latency in the completed artifact; replace placeholders with observed test values. Generate events for allowed, cross-resource, non-member, malformed, unknown-tool, write-shaped, and post-revocation attempts. Reconcile the gateway request IDs with connector events. The attempted-call count and terminal-event count must match, or every missing event needs an incident finding. Logging only successes hides probing and outages.

Add a retention table to the same inventory:

If immediate deletion testing is not supported, record the job, owner, due date, and result as pending. Do not describe scheduled deletion as observed deletion.

Review the third-party connector before installation

Treat CON-006 as a candidate, not as trusted because its catalogue data is public. Complete this gate inside connector-inventory.md:

1. Need: state the exact repeated task and why a static link or existing approved connector is insufficient.
2. Publisher: locate the official publisher page and support/security contact. Record how identity was verified; do not rely on a search-result name.
3. Artifact: record the exact package, container, commit or binary revision, digest or available signature evidence, licence or terms reference, and acquisition route.
4. Execution: inspect the untruncated startup command, install scripts, filesystem access, outbound destinations, runtime user, persistence, and sandbox boundary.
5. Tools and permissions: enumerate discovered tools and compare requested identity, operation, resource, and time scope with the task. Block generic shell, path, URL, SQL, wildcard, admin, and unexplained write access.
6. Data handling: record processors, destinations, retention, telemetry, incident notice, and deletion route. Public source data does not make user identity and call history public.
7. Updates: disable uncontrolled promotion. State how releases are notified, authenticated, staged, scanned, diffed, tested, approved, pinned, rolled back, and monitored.
8. Evidence: run allowed and denied tests in isolation, inspect outbound connections and sanitized events, and record actual results.
9. Removal: prove how to disable assignment, revoke grants, uninstall the artifact, stop processes, remove discovery, deny direct invocation, preserve required logs, and restore the previous approved route.

The decision is approve, approve with a dated exception, or block. Any unknown publisher, mutable unpinned artifact, unexplained privilege, uncontrolled update, absent security contact, or untested removal remains blocked. Procurement approval, malware scanning, source review, and a successful demo answer different questions; record each without allowing one to stand for all.

Remove the legacy connector cleanly

Retire CON-008 in the fixture environment. First identify all consumers from configuration references, assignment groups, recent sanitized call events, scheduled workflows, and owner interviews. Record a last-use window, affected Lab or Company work, replacement or manual fallback, change owner, approval, start time, rollback boundary, and communication route.

Then execute in this order:

1. Set status to deprecated, block new assignments, and freeze its revision.
2. Disable calls at the central gateway so a cached client cannot continue using the route.
3. Move synthetic consumers to the approved read-only Northstar connector or documented manual fallback.
4. Revoke the connector's source grant, OAuth client consent, tokens, and workload credential by identifier. Never paste credential values into the inventory.
5. Remove client discovery and deployment configuration, uninstall the pinned artifact, and stop its process or workload.
6. Call the old route directly using the approved test harness. Require denial or unreachable service, not a friendly client omission.
7. Refresh two synthetic clients and prove the legacy tools are absent from discovery. Call the replacement's allowed and denied cases.
8. Search for new legacy call attempts during the observation window; route any attempts to an owner instead of silently restoring access.
9. Preserve audit records only for their approved retention period, then verify expiry. Mark the inventory retired with date, operator, evidence IDs, and residual actions.

The removal fails if the old tool merely disappears from one screen, its source token remains valid, a scheduled workflow keeps retrying, a process still listens, or the replacement has broader authority. Ask the second operator to repeat discovery and direct-call tests from the written steps. If they need the installer to explain an undocumented command, handover has failed.

Close one finding and schedule the next review

Record at least one observed finding in the inventory. For this worked example:

Finding: CON-008 has no verified per-call event and an unknown update mode.
Risk: Changes and source access cannot be attributed or reconstructed.
Blast radius: Shared Lab or Company route; incorrect or unauthorized calls can
affect every user and downstream workflow assigned to the connector.
Action: Block calls, migrate synthetic consumers, revoke the source grant,
remove discovery and runtime, and preserve approved audit evidence.
Owner: Synthetic Connector Service Owner
Checked: 2026-09-04
Retest: old tool absent from discovery; direct call denied; source grant revoked;
replacement allowed and cross-resource checks pass; no unexplained retries.
Next review: [approved date]

Finally, sort the nine rows by blocked, exception expiry, and next review date. The inventory is alive only if ownership changes, releases, permission changes, incidents, and removals update it through an approved process.

7. What goes wrong

Everyone appears as one service account

Symptom: source and connector logs show only connector-service, so a leaver's call cannot be separated from anyone else's.

Fix: prefer delegated per-user access. Where an application identity is necessary, carry a trusted initiating principal, authorize per user before source access, log user and workload separately, and test one user's revocation without stopping everyone.

Only successful calls are logged

Symptom: the audit looks quiet while denied probes, malformed arguments, timeouts, and missing terminal events are invisible.

Fix: emit a sanitized event for every attempt and terminal outcome. Reconcile request and event counts, alert on missing terminal events, and retain denial categories without raw sensitive payloads.

Audit logging becomes a second data lake

Symptom: tokens, complete arguments, source records, prompts, and responses are searchable long after their operational purpose ends.

Fix: allowlist metadata fields, redact before transport, restrict readers, assign retention by event class, and observe deletion with synthetic canaries.

A familiar publisher name substitutes for provenance

Symptom: the inventory says official connector but has no official source, exact revision, digest, startup command, or review evidence.

Fix: resolve publisher and artifact identity from the official channel, pin what runs, verify available integrity evidence, inspect execution and permissions, and block unknowns.

Auto-update silently changes authority

Symptom: discovery gains a new tool or parameter before the operator has reviewed or tested it.

Fix: separate notification from promotion. Stage the exact candidate, diff manifests and tools, rerun permission and logging tests, approve, pin, monitor, and retain a rollback revision.

Removal happens only in the client

Symptom: the icon is gone, but a cached client, scheduled workflow, token, or server can still call the source.

Fix: block centrally, migrate consumers, revoke source grants and credentials, remove discovery and runtime, then prove direct denial and watch for retries.

The inventory has owners but no review trigger

Symptom: rows remain green after a maintainer leaves, a group changes, a connector releases, or a source permission expands.

Fix: trigger review on ownership, revision, tool-contract, identity, permission, endpoint, processor, incident, and lifecycle changes, plus a scheduled date.

Deprecation breaks work without a fallback

Symptom: the risky connector is correctly blocked, but the literature review, sample tracker, ticket queue, or report stops with no supported path.

Fix: identify consumers before removal, name the manual or replacement route, test it with the same boundary cases, communicate the window, and assign residual failures.

8. Do it yourself: inventory nine routes and retire one in 90 minutes

Use one approved non-production environment and one connector-inventory.md artifact. Choose the Lab or Company framing; use synthetic identities and records throughout.

Minutes 0-15: discover connectors from central configuration, client assignments, deployment records, source authorization metadata, and recent sanitized events. Create nine rows, or every row that actually exists if fewer than nine. Mark every unknown field BLOCKED.

Minutes 15-30: expand the highest-authority rows. Record exact artifacts, publishers, tools, resources, operations, user groups, workload identities, update paths, owners, dependencies, stop controls, and review dates. Do not retrieve secret values.

Minutes 30-43: use two synthetic users to test one allowed call, cross-resource denial, non-member denial, identity spoof rejection, write-shaped denial, and one group revocation. Record actual event and trace IDs.

Minutes 43-55: reconcile every attempted call with one sanitized terminal event. Check required fields and prohibited content. Record readers, retention, deletion control, and either an observed synthetic deletion or a pending evidence date and owner.

Minutes 55-67: review one third-party candidate. Verify publisher and exact artifact, inspect command and permissions, document update control and security support, run isolated allowed and denied checks, and decide approve, exception, or block.

Minutes 67-84: choose one safely removable fixture connector. Identify consumers and fallback, block new calls, revoke synthetic grants, remove discovery and runtime, run direct denial, verify replacement boundaries, and observe retries. Have the second operator repeat the checks.

Minutes 84-90: write one finding with risk, affected people, action, owner, date, observed retest, and next review. Remove temporary memberships and synthetic credentials. Confirm the artifact contains references and sanitized evidence, not secrets or source content.

Do not retire a production connector to finish on time. If no approved fixture is removable, build a synthetic disposable route first; do not claim the exit artifact until the complete removal test has been observed.

9. Exit check

Deliver exactly one artifact: one connector inventory stating what each connector reaches, who may use it, and what is logged.

It passes when the inventory covers every discovered connector and records stable ID, purpose, publisher and official source, exact revision or digest, tools, operations, resources, per-user or explicitly separated user/workload identity path, allowed groups, owner, update channel, approval, audit schema, readers, retention, deletion control, dependencies, fallback, stop control, lifecycle state, and review dates. It must include observed allowed and denied tests for two synthetic users; sanitized events for every attempted test call; one completed third-party decision; one safely retired fixture connector with discovery absence, direct denial, revoked source grant, stopped runtime, consumer handling, and retry observation; and one finding with owner, date, fix, Level 5 blast radius, and observed retest.

It fails if unknown authority is treated as approved, all users share unattributable access, only successful calls are logged, secrets or unapproved source content enter the artifact, an update can promote without review, or removal is evidenced only by a missing icon. An honest blocked row or pending retention check is valid operational evidence; a fabricated pass is not.

10. Rule to remember

Every tool call is an action by somebody. Know who.

11. Further reading & tools

• Taught: T14-L04 | Build your own connector - supplies the narrow Northstar contract, minimal result, server-side authorization, and denied write test operated here.
• Taught: T12-L05 | Operate governance - supplies ownership, exception, evidence, review, and incident routines for the inventory.
• Taught: The AI supply chain - introduces exact component identity, provenance, release gates, and rollback references used in third-party review.
• Taught: MCP security best practices (opens in a new tab) - primary guidance on token passthrough, local server execution, session handling, scope minimization, and related connector risks.
• Catalogued: MCP authorization specification (opens in a new tab) - current protocol requirements for protected HTTP-based MCP servers and audience-bound authorization.
• Catalogued: OAuth 2.0 Security Best Current Practice, RFC 9700 (opens in a new tab) - primary guidance for redirect, token, client, and least-privilege controls.
• Catalogued: NIST SP 800-53 Rev. 5 (opens in a new tab) - primary control catalogue for access enforcement, audit, configuration, incident response, and supply-chain risk management.
• Catalogued: SLSA specification 1.2 (opens in a new tab) - primary supply-chain specification for artifact provenance and verification concepts.
• Catalogued: Tools index - compare approved connector clients, gateways, identity systems, log platforms, and inventory tools after fixing the operating contract.