Day 169 · Plumbing into an old building

Enterprise Integration

You will be able to

Explain the SAML and OIDC SSO flows well enough to whiteboard either for a customer IT team
Describe what SCIM provisioning adds on top of SSO and when a customer will demand it
Map the enterprise systems an AI product actually meets — SharePoint, warehouses, ERPs, ticketing — and the integration pattern for each
Name three integration anti-patterns and the pattern that replaces each
Draft the security-review and change-management answers a customer will ask for before go-live

Today's ~120 minutes

Spaced-rep warm-up: due cards from Week 24	10 min
ELI5 + tech read; sketch the enterprise map	20 min
Guided: OIDC walk + enterprise recon sheet	40 min
Practice: permission-aware retrieval design	20 min
Project: enterprise readiness addendum	20 min
Quiz + flashcards	10 min

Builds on: Day 44 — Security, AuthN & AuthZ · Day 45 — Web service architecture · Day 162 — The FDE role

The analogy

🧸 ELI5⚙ Tech

You built a beautiful modern kitchen appliance. Now you have to install it in a 1920s office building. The wiring is aluminum, the pipes are lead, three different superintendents each control one floor, and nothing gets connected without a permit signed by the building committee. You don't get to rewire the building — you adapt YOUR plug to THEIR sockets, and you learn who signs the permits.

That is enterprise integration. The "old building" is the customer's existing stack: their identity system decides who can log in (you plug into it, you never build your own login), their document stores and databases hold the knowledge your AI needs (you connect to them on their terms), and their change-management process decides when anything ships. The engineers who thrive here aren't the ones with the shiniest appliance — they're the ones who can walk the building, find every pipe, and produce a wiring diagram the superintendents will actually sign.

Why this matters on the job

Deals die at integration, not at the demo. A docs-QA assistant that wowed the exec sponsor goes nowhere if it can't authenticate against the customer's Entra ID tenant, read their SharePoint, and pass their security review. FDE job postings almost universally list "experience integrating with enterprise systems (SSO, data warehouses, ticketing)" — because the last mile between a working product and a deployed product is exactly this plumbing, and it is where forward-deployed engineers earn their keep.

Watch it happen

Plumbing into an old building — your service meets the enterprise

step 1 / 5

Employee→SSOSAML/OIDC→API Gatewaytheir perimeter→Your service→SharePoint + Warehousetheir data

✉ nothing connects until security review signs off — plan weeks, not days

Your shiny docs-QA service is ready. Between it and its first enterprise user stands the building's existing plumbing — and every pipe has a gatekeeper.

🎯 Predict modespeed1×

Guided practice

guided 1

Walk the OIDC flow with your own hands

20 min

Create oidc_walk.py and paste the starter code. It simulates the relying-party side of an OIDC login: an ID token arrives, you must validate it before trusting it.
Run it. The first sample token passes; note which checks it passed (issuer, audience, expiry, signature-present flag).
Three bad tokens follow: one expired, one issued for a different app (wrong aud), one from an unknown issuer. Confirm your validator rejects each and prints WHY.
On paper, draw the full auth-code flow as a 6-step sequence (browser → your app → IdP → browser → your app → IdP token endpoint). Label where this validation step lives.
Write one sentence: why does your backend, not the browser, exchange the code for tokens?

🐍 python — editable, runs in your browser

import base64, json, time

# Toy ID-token validator. Real code uses a JWT library and verifies the
# signature against the IdP's published JWKS keys - here we simulate that
# with a 'sig_ok' flag so the CLAIM checks are what you practice.

MY_CLIENT_ID = "docsqa-prod"
TRUSTED_ISSUER = "https://login.customer-idp.example/tenant-42"

def b64url(obj):
    raw = json.dumps(obj).encode()
    return base64.urlsafe_b64encode(raw).decode().rstrip("=")

def make_token(claims, sig_ok=True):
    return {"payload": b64url(claims), "sig_ok": sig_ok}

def validate(token):
    if not token["sig_ok"]:
        return False, "signature invalid - not signed by the IdP's key"
    pad = "=" * (-len(token["payload"]) % 4)
    claims = json.loads(base64.urlsafe_b64decode(token["payload"] + pad))
    if claims.get("iss") != TRUSTED_ISSUER:
        return False, "unknown issuer: " + str(claims.get("iss"))
    if claims.get("aud") != MY_CLIENT_ID:
        return False, "audience mismatch: token minted for " + str(claims.get("aud"))
    if claims.get("exp", 0) < time.time():
        return False, "token expired"
    return True, "ok - user " + claims["sub"] + " groups " + str(claims.get("groups"))

now = time.time()
good = make_token({"iss": TRUSTED_ISSUER, "aud": MY_CLIENT_ID,
                   "sub": "u_1042", "exp": now + 3600, "groups": ["docsqa-users"]})
expired = make_token({"iss": TRUSTED_ISSUER, "aud": MY_CLIENT_ID,
                      "sub": "u_1042", "exp": now - 60})
wrong_aud = make_token({"iss": TRUSTED_ISSUER, "aud": "other-app",
                        "sub": "u_1042", "exp": now + 3600})
bad_iss = make_token({"iss": "https://evil.example", "aud": MY_CLIENT_ID,
                      "sub": "u_1042", "exp": now + 3600})

for name, tok in [("good", good), ("expired", expired),
                  ("wrong_aud", wrong_aud), ("bad_iss", bad_iss)]:
    ok, why = validate(tok)
    print(f"{name:10s} -> {'ACCEPT' if ok else 'REJECT':6s} | {why}")

Ctrl/⌘+Enter runs · Tab indents · numpy/pandas/sklearn auto-load on import (torch and network calls need a local run)

guided 2

Enterprise recon sheet for the capstone

20 min

Your capstone docs-QA assistant is being sold into "Meridian Insurance" (4,000 employees, Microsoft shop). Build an integration matrix — this becomes part of tomorrow's and Day 174's deliverables.

Create docs/integration-matrix.md in the capstone repo with columns: System · What we need from it · Auth method · API/sync pattern · Rate/cost constraints · Permission model · Open questions for their IT.
Fill a row each for: SharePoint Online (policy docs), a Snowflake warehouse (claims data for future phases), ServiceNow (where employees currently ask these questions), and Entra ID (SSO + groups).
For SharePoint, decide: nightly full crawl or incremental delta sync with change tokens? Write two sentences defending your choice using the anti-patterns list.
For each row, write at least one question you literally cannot answer without the customer (e.g. "which SharePoint sites are in scope, and who owns app-registration approval?"). Vague rows are the ones that blow up timelines.

On your own

Permission-aware retrieval design

20 min

Meridian's CISO asks: "If an intern queries your assistant, can it quote from the executive-compensation policy that only HR can open?"

Design the mechanism that makes the honest answer "no." Deliverable: half a page in docs/integration-matrix.md covering (1) where document ACLs are captured at ingest time, (2) how a query gets filtered — pre-filter on metadata at retrieval vs post-filter after retrieval — and which you choose and why, (3) what happens when a document's permissions CHANGE after it was indexed, (4) how you would prove it works (an eval case, not a promise).

Hints (only if stuck): your vector DB (Day 115) supports metadata filters; post-filtering leaks information through "I found something but can't show you"; permission sync is just another incremental-sync problem.

Ship before you stop

Enterprise readiness addendum

Write docs/enterprise-readiness.md for the capstone as if Meridian's security and IT teams will read it Monday. Sections: (1) Authentication — OIDC via customer IdP, token validation, group-to-role mapping, SCIM position (supported / roadmap, be honest); (2) Data flows — a text diagram of every place customer data moves or rests, with encryption noted; (3) Integration plan — the matrix from guided work plus the permission-aware retrieval design; (4) Change management — what you need from their CAB and realistic calendar estimates; (5) Security questionnaire pre-answers — retention, deletion, subprocessors (your LLM provider IS one — name it), audit logging. Commit it; Day 174's simulation and Day 178's ship docs both reuse it.

Rubric — check what you completed (0/6)

OIDC section names the flow, the three token checks, and where group→role mapping happensData-flow section accounts for the LLM provider as a subprocessor with data sent/retained notedIntegration matrix has all four systems with at least one real open question eachPermission-aware retrieval design chooses pre- vs post-filtering with a stated reasonChange-management section estimates calendar time separately from engineering timeCommitted to the capstone repo and linked from the README

Common mistakes & misconceptions

Building your own username/password login "for now." Enterprises will not create accounts in your system; SSO is table stakes, and retrofitting it later touches every session and permission path.
Treating SSO as done when login works. Without SCIM (or at least group-sync on login), departed employees keep access — the exact finding that fails a security review.
Indexing everything the service account can see. Your retrieval layer must honor per-document ACLs, or the intern really can read the exec-comp policy. Sync permissions, not just content.
Full re-crawls every night because they are easy. They hammer the customer's API limits, cost real money on warehouses, and still leave you stale during the day — use change tokens/delta APIs.
Quoting engineering time when the customer hears calendar time. The connector takes 2 weeks; the app registration, firewall change, and CAB approval take 6. Say both numbers out loud.
Bypassing the customer's API gateway to hit an internal service directly "because it is faster." You just opted out of their auth, rate limiting, and audit trail — the first thing an integration review flags.

Knowledge check

Q1. In the OIDC authorization-code flow, why does your BACKEND exchange the code for tokens instead of the browser doing it?

Q2. A customer asks "do you support SCIM?" What are they actually asking for?

Q3. Your docs-QA service account can read all of SharePoint. The safest retrieval design is…

Go deeper — curated resources

docsOpenID Foundation — How OpenID Connect works ↗15 min docsC4 Model — diagrams for the integration map ↗15 min articleFDE Interview Guide (Exponent) — enterprise delivery expectations ↗20 min docsMDN: HTTP — refresher for gateway/auth headers ↗10 min

If you have a third hour

SCIM 2.0 protocol (RFC 7644) ↗ — Skim the endpoint list and the deactivation semantics — enough to answer "what would supporting SCIM take?"

Done means

OIDC validator run; all three bad tokens rejected with correct reasons stated
Integration matrix committed with four systems and open questions per row
Enterprise readiness addendum committed, rubric ≥ 5/6
Quiz ≥ 2/3

How this connects

← Back: Day 44 gave you JWTs, OAuth and RBAC as concepts — today they became the customer's Entra ID tenant and a group-mapped role table. Day 45's layered architecture is where the auth middleware and integration service slot in.

Forward →: Tomorrow (Day 170) the plumbing question becomes WHERE your product runs — the customer's VPC and worse. Day 174's simulation throws a security-review objection at you that this addendum answers, and Day 178 ships these docs in the final repo.

Unlocks: D170 Customer Environments