DEV Community: Jack Jiang

Wiring Up SMART on FHIR OAuth2 Between OpenEMR and a Python Microservice Locally

Jack Jiang — Sat, 28 Feb 2026 15:46:03 +0000

I was building an AI agent on top of OpenEMR and hit a wall I didn't expect.

Not a hard engineering problem — just documentation. Or the lack of it. OpenEMR ships with a full SMART on FHIR OAuth2 server, and the official authentication docs are a decent starting point. But connecting a custom Python microservice to it? You're mostly on your own.

I spent way more time than I'd like to admit staring at active: false responses, getting HTML back from endpoints that should return JSON, and debugging DNS failures that turned out to be a two-word fix. So I'm writing down everything I wish I'd known — the steps and the gotchas.

The Setup

Here's what we're working with:

Service	Tech	Port
`openemr`	OpenEMR 7.0.4 (PHP + Docker)	8300 (HTTP), 9300 (HTTPS)
`ai-agent`	Python FastAPI + LangGraph	8000

Both run in Docker Compose. That detail matters more than it sounds — the OpenEMR container is reachable internally at http://openemr, but the browser needs http://localhost:8300. Mixing these up is the single most common source of errors in this whole setup. Keep that distinction in your head throughout.

How OpenEMR's OAuth2 Actually Works

OpenEMR implements SMART on FHIR on top of a standard OAuth2 Authorization Code flow, using the league/oauth2-server library under the hood.

The endpoints you'll actually use (all under /oauth2/default/):

Endpoint	Purpose
`GET /authorize`	Redirects the user to OpenEMR login
`POST /token`	Exchanges an authorization code for tokens
`POST /introspect`	Validates a token and returns its claims (RFC 7662)
`POST /registration`	Registers an OAuth client dynamically

There are also two distinct scope families, and this distinction really matters:

Patient scopes — patient/Patient.read, patient/Appointment.read, etc. These are tied to a specific authenticated patient.
Staff scopes — system/Patient.read, system/Appointment.read, etc. For provider and admin access.

Your microservice sits at the end of this flow. It receives a Bearer token from whatever client is calling it, and it needs to validate that token against OpenEMR before trusting anything about the request.

Step 1: Register an OAuth Client

Before your service can introspect tokens, it has to be a registered client in OpenEMR itself. You have two options.

Option A: The Admin UI

Easiest for a one-time local setup.

Log into OpenEMR at http://localhost:8300 — use HTTP here, not HTTPS on 9300, to avoid a CORS headache
Go to Admin → System → OAuth2 Client Registration
Create a confidential client:
- Application Type: confidential
- Redirect URI: your service's callback (e.g. http://localhost:8000/auth/callback)
- Scopes: include all the patient and system scopes your service needs
- Grant Types: authorization_code, refresh_token

Save the client_id and client_secret. You'll need both for introspection.

Option B: Dynamic Client Registration

OpenEMR supports RFC 7591, which means you can register clients programmatically. Here's a script that does exactly that and prints the credentials you need:

# scripts/register_oauth_client.py
import sys
import time
import httpx

OPENEMR_BASE = "http://localhost:8300"
REGISTRATION_URL = f"{OPENEMR_BASE}/oauth2/default/registration"

CLIENT_PAYLOAD = {
    "application_type": "confidential",
    "client_name": "My AI Agent",
    "redirect_uris": ["http://localhost:8000/auth/callback"],
    "scope": (
        "openid fhirUser "
        "patient/Patient.read patient/Appointment.read patient/Appointment.write "
        "system/Patient.read system/Appointment.read system/Appointment.write "
        "system/Practitioner.read system/Coverage.read"
    ),
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
}


def register(payload: dict) -> dict:
    for attempt in range(5):
        try:
            resp = httpx.post(REGISTRATION_URL, json=payload, timeout=15)
            if resp.status_code in (200, 201):
                return resp.json()
            print(f"HTTP {resp.status_code}: {resp.text[:200]}")
        except httpx.ConnectError:
            print(f"OpenEMR not ready, retrying in 5s... (attempt {attempt + 1})")
            time.sleep(5)
    sys.exit(1)


if __name__ == "__main__":
    result = register(CLIENT_PAYLOAD)
    print(f"OPENEMR_CLIENT_ID={result['client_id']}")
    print(f"OPENEMR_CLIENT_SECRET={result['client_secret']}")

Run this once after OpenEMR starts. Copy the output into your .env. Done.

Gotcha: If the dynamic registration endpoint rejects your request, check Admin → Globals → Site → Site Address. The site_addr_oauth value must match the URL you're calling from. When there's a mismatch, OpenEMR quietly rejects registration requests — no helpful error message, just a failure.

Step 2: Environment Variables

# .env

# Set after running scripts/register_oauth_client.py
OPENEMR_CLIENT_ID=
OPENEMR_CLIENT_SECRET=

# Internal Docker URL for server-to-server calls
OPENEMR_TOKEN_URL=http://openemr/oauth2/default/token

That OPENEMR_TOKEN_URL value — http://openemr — is the internal Docker hostname. It only resolves from inside the Docker network. If you're running your agent locally with uvicorn outside of Docker, change it to http://localhost:8300. I cannot stress enough how many confusing errors trace back to this one hostname distinction.

Step 3: The Token Introspection Service

Here's the core of the whole thing. On every incoming request, your service needs to call OpenEMR's /introspect endpoint with the Bearer token, and OpenEMR will tell you whether it's valid and what it's allowed to do.

The response looks like this:

{ "active": true, "sub": "some-user-uuid", "scope": "patient/Patient.read patient/Appointment.read" }

You take that, check the scopes, and either proceed or reject the request. Simple in theory — but there are details worth getting right:

# app/services/auth_service.py
"""
Token validation via OpenEMR OAuth2 introspection (RFC 7662).
Caches results briefly to avoid hammering OpenEMR on every request.
"""

import hashlib
import logging
import os
import time

import httpx

logger = logging.getLogger(__name__)

_INTROSPECT_CACHE_TTL = 45  # seconds — shorter than token lifetime
_cache: dict[str, tuple[dict, float]] = {}


def _introspect_url() -> str:
    token_url = os.getenv("OPENEMR_TOKEN_URL", "http://openemr/oauth2/default/token")
    return token_url.rstrip("/").replace("/token", "") + "/introspect"


def _cache_key(token: str) -> str:
    # Hash the token so raw credentials never appear in memory keys
    return hashlib.sha256(token.encode()).hexdigest()[:32]


def _get_cached(token: str) -> dict | None:
    key = _cache_key(token)
    entry = _cache.get(key)
    if not entry:
        return None
    claims, expires_at = entry
    if time.time() >= expires_at:
        del _cache[key]
        return None
    return claims


def _set_cached(token: str, claims: dict) -> None:
    key = _cache_key(token)
    _cache[key] = (claims, time.time() + _INTROSPECT_CACHE_TTL)


async def _introspect(token: str) -> dict:
    """Call OpenEMR introspection endpoint."""
    url = _introspect_url()
    client_id = os.getenv("OPENEMR_CLIENT_ID", "")
    client_secret = os.getenv("OPENEMR_CLIENT_SECRET", "")

    if not client_id or not client_secret:
        logger.warning("Introspection skipped: OPENEMR_CLIENT_ID/SECRET not configured")
        return {"active": False}

    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.post(
            url,
            data={
                "token": token,
                "token_type_hint": "access_token",
                "client_id": client_id,
                "client_secret": client_secret,
            },
            headers={"Content-Type": "application/x-www-form-urlencoded"},
        )

    if resp.status_code != 200:
        logger.warning("Introspection HTTP %s", resp.status_code)
        return {"active": False}

    try:
        return resp.json()
    except Exception as exc:
        logger.warning("Introspection parse error: %s", exc)
        return {"active": False}


async def validate_patient_token(token: str) -> dict:
    """
    Validate a patient token. Raises HTTPException if invalid.
    Returns introspection claims on success (includes 'sub' = patient FHIR ID).
    """
    from fastapi import HTTPException

    cached = _get_cached(token)
    claims = cached if cached is not None else await _introspect(token)

    if cached is None:
        _set_cached(token, claims)

    if not claims.get("active"):
        logger.warning("Patient token invalid: prefix=%s", token[:8])
        raise HTTPException(status_code=401, detail="Token is invalid or expired")

    scopes = (claims.get("scope") or "").split()
    if not any(s.startswith("patient/") for s in scopes):
        logger.warning("Patient token lacks patient scope: prefix=%s", token[:8])
        raise HTTPException(status_code=403, detail="Token lacks patient scope")

    if not claims.get("sub"):
        logger.warning("Patient token missing sub claim: prefix=%s", token[:8])
        raise HTTPException(status_code=401, detail="Token missing subject claim")

    return claims


async def validate_staff_token(token: str) -> dict:
    """
    Validate a staff token. Raises HTTPException if invalid.
    Returns introspection claims on success.
    """
    from fastapi import HTTPException

    cached = _get_cached(token)
    claims = cached if cached is not None else await _introspect(token)

    if cached is None:
        _set_cached(token, claims)

    if not claims.get("active"):
        logger.warning("Staff token invalid: prefix=%s", token[:8])
        raise HTTPException(status_code=401, detail="Token is invalid or expired")

    scopes = (claims.get("scope") or "").split()
    if not any(s.startswith("system/") for s in scopes):
        logger.warning("Staff token lacks system scope: prefix=%s", token[:8])
        raise HTTPException(status_code=403, detail="Token lacks staff/system scope")

    return claims

A few decisions in here that are worth calling out:

The TTL cache. Calling introspect on every single request would hammer OpenEMR. A 45-second in-memory cache keeps things fast without risking stale results — access tokens typically live for an hour. Tokens are hashed before use as cache keys so the raw strings never end up sitting in memory.
403 vs 401. This distinction matters. A missing or expired token is a 401 — unauthenticated. A valid staff token presented to a patient endpoint is a 403 — authenticated but wrong scope. Conflating these makes debugging a nightmare.
Log the prefix, not the token. First 8 characters is enough to correlate a failure to a specific token in your logs without actually leaking credentials.

Step 4: Wiring It Into FastAPI

With the validation service built, the endpoint itself stays clean. FastAPI's HTTPBearer dependency pulls the token from the Authorization header, and validate_patient_token handles everything else:

# app/api/patient.py
from fastapi import APIRouter, Depends
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

from app.services.auth_service import validate_patient_token

router = APIRouter(prefix="/api/chat", tags=["patient"])
security = HTTPBearer()


def _get_patient_token(
    credentials: HTTPAuthorizationCredentials = Depends(security),
) -> str:
    return credentials.credentials


@router.post("/patient", response_model=ChatResponse)
async def patient_chat(
    body: ChatRequest,
    token: str = Depends(_get_patient_token),
) -> ChatResponse:
    token_claims = await validate_patient_token(token)  # raises 401/403 if bad

    # Use the verified patient ID from the token for FHIR data scoping
    patient_id = str(token_claims["sub"])

    # Pass the validated token downstream so FHIR calls are made on behalf of this patient
    message, tool_calls, usage, metadata = await asyncio.to_thread(
        invoke_patient_agent,
        user_input,
        patient_id=patient_id,
        fhir_token=token,
    )
    ...

token_claims["sub"] is the patient's identity. Passing fhir_token to the agent means every downstream FHIR call is made on behalf of that specific patient — which is the whole point of SMART on FHIR's data isolation model.

The Pitfalls I Hit (So You Don't Have To)

Introspection returns active: false on a perfectly fresh token.
Nine times out of ten this means your OPENEMR_CLIENT_ID and OPENEMR_CLIENT_SECRET don't match a registered confidential client. The introspecting client must itself be registered in OpenEMR — you can't just use arbitrary credentials.

Getting HTML back instead of JSON from the introspect endpoint.
This one is deeply confusing the first time. It means the site address (site_addr_oauth) in OpenEMR's globals doesn't match the issuer URL. OpenEMR redirects to an error page instead of returning JSON, and if you're not printing the raw response, all you see is a parse error. Fix it at Admin → Config → Connectors → Site Address Override.

DNS failure when calling http://openemr/....
You're running the agent outside Docker. The openemr hostname only resolves inside the Docker network. Switch to http://localhost:8300 for local development.

Token validates but the patient ID looks wrong.
The sub claim from introspection is the internal OpenEMR user UUID — not the FHIR patient resource ID. If you need the FHIR patient ID directly, cross-reference it via the FHIR API, or grab the patient claim from the original token response (only present for patient-context EHR launches).

Introspection passes but the FHIR API still returns 401.
The FHIR API and the introspection endpoint are independently authorized. A token can be active: true but still get rejected by a specific FHIR endpoint if the token's scopes don't cover that resource type. Make sure the scopes registered on your client actually match what your queries need.

Takeaways

OpenEMR's OAuth2 is real OAuth2 — once you know where the gotchas are, it behaves like a standard SMART on FHIR server. The pain is mostly in the setup, not the protocol.
The internal vs. external hostname split will bite you. Keep http://openemr for server-to-server calls inside Docker, http://localhost:8300 for everything else. Tattoo it on your brain.
Introspection is the right tool. Your service shouldn't be verifying JWT signatures against OpenEMR's keys — use /introspect and let OpenEMR do that work. Cache the results and you won't pay a meaningful performance cost.
Scope-based separation makes roles explicit. Patient endpoints enforce patient/* scopes, staff endpoints enforce system/* scopes. A 403 tells you who the person is but why they can't access this — that's a much more useful error than a generic 401.

If you're building anything on OpenEMR and run into a different gotcha, drop it in the comments. This stuff is genuinely undertested territory and the more people document it, the better.

From Impostor Syndrome to Mentorship: How “WHAT” Shaped My Growth as an Engineer

Jack Jiang — Tue, 21 Oct 2025 21:42:44 +0000

Starting Out — and Feeling Lost

I started my full stack software engineering career right out of college as a bright-eyed, bushy-tailed computer science graduate with terrible impostor syndrome.

Who can relate?

Between the firehose of onboarding information, a brand-new work environment, and an unfamiliar schedule, I felt completely overwhelmed. IBM ran large cohort-based onboarding workshops, and on top of that, I was meeting with different members of the team to learn as much as possible before jumping into real work.

When the time came to tackle my first ticket, I was clueless. I needed to implement a privacy auditing feature across the stack — which, at the time, used vanilla JavaScript on the front end, Node.js on the back end, and IBM DB2 for the database.

The codebase was relatively straightforward in structure, but it was massive, and I didn’t even know where to begin.

Pair Programming: A Turning Point

When I brought this up during our team standup, the lead engineer on the project, Devaraj, offered to pair-program with me.

I was nervous. Would I just stare blankly at a wall of code? Would he explain everything so fast that I wouldn’t retain a thing?

Instead, I was pleasantly surprised. Devaraj built the feature in front of me — explaining what he was doing, why he was doing it, and how the data flowed from front to back at every step. It was like watching a live masterclass in our codebase.

He could have completed the task ten times faster on his own. But by slowing down, explaining his reasoning, and letting me ask endless questions, he helped me gain both a deep understanding of the system and the confidence to contribute independently.

Within weeks, I was building features with some guidance. Within months, I was implementing them entirely on my own.

Exceeding Expectations

Six months later, my manager called me in to talk about my performance. Even with my progress, I still felt “green” and worried that I’d fallen short.

To my surprise, she told me I was exceeding expectations and should expect a bonus.

Excitement hit — and then gratitude. I couldn’t have achieved that growth without the people, like Devaraj, who took the time to invest in me.

And years later, I found myself in his position — mentoring new engineers using the same patient, hands-on approach he had modeled for me.

Introducing “WHAT”: A Framework for Mentorship

So what happened here?

WHAT happened here.

WHAT is an acronym I picked up while volunteering on the A/V team at my church — and it stuck with me ever since. It outlines a simple but powerful model for progressive mentorship:

W – Watch: You (the mentee) watch while I (the mentor) do.

H – Help: I do, and you help.

A – Assist: You do, and I assist.

T – Teach: You teach someone else.

At first, I simply watched Devaraj build the feature and asked questions along the way. As I gained confidence, I started to help, taking small pieces of the task myself. Eventually, I moved to assist, completing most of the work while checking in for feedback.

And finally, I reached the teach stage — mentoring others and passing along what I’d learned.

Applying WHAT in Real Life

The WHAT model is helpful because it brings structure and clarity to mentorship. It creates a shared understanding between mentor and mentee about where they are in the learning journey and what’s next.

Of course, the stages aren’t always linear or clear-cut. Even in the “Help” stage, someone might already have expertise in certain areas and be ready to “Teach” others. The goal isn’t to follow the model rigidly — it’s to use it as a framework for understanding and communication.

When applied intentionally, WHAT helps both sides see progress, build confidence, and ultimately create a culture of continuous learning.

Takeaways

Effective mentorship compounds growth. By slowing down to teach, mentors create ripple effects that elevate entire teams.
Structured learning builds confidence. The WHAT framework gives mentees a roadmap for their development.
Teaching reinforces mastery. When you teach others, you deepen your own understanding — completing the cycle.

Whether you’re a new engineer or a seasoned leader, adopting a “WHAT” mindset can help you turn knowledge into shared success — and transform impostor syndrome into empowerment.

Cross-domain Cookies: Building Less Annoying Consent Solutions

Jack Jiang — Thu, 16 Oct 2025 21:29:42 +0000

When I worked at IBM, we had a cookie preferences pop-up — as every company should:

At first glance, it looked fine. But there was one big problem: whenever a user clicked a link that opened another IBM-owned domain, that new domain had its own cookies and promptly “forgot” the user’s preferences.

It seemed like a minor annoyance — until we noticed it was quietly affecting bounce rates. Even small distractions can discourage potential clients from researching products or completing actions.

What didn't work

My initial solution used a third-party cookie to track the user’s privacy preference across domains. It worked well for months — until it didn’t.

Bounce rates started rising again. Another engineer on my team dug into the analytics and noticed an interesting trend: more of our visitors were using privacy-first browsers like Firefox, Brave, and Chrome extensions that blocked third-party cookies entirely.

For those users, every new domain triggered the pop-up again. Frustrating, and not exactly the “seamless experience” we were aiming for.

The new solution: Redis to the Rescue

I needed an external service that could share cookie preference levels across domains — without relying on third-party cookies.

Enter Redis.

With Redis, I created a fast, in-memory mapping between each user’s IP address and their cookie preference level. It wasn’t perfect — preferences would reset if a user changed networks — but this happened rarely within a single browsing session.

To safeguard against that, I also stored the preference level as a first-party cookie, so users wouldn’t lose their settings if their IP changed.

Here’s what the backend setup looked like in Node.js:

import express from "express";
import { createClient } from "redis";

const app = express();
app.use(express.json());

// Initialize Redis client
const redis = createClient({ url: "redis://localhost:6379" });

redis.on("error", (err) => console.error("Redis Client Error", err));
await redis.connect();

// TTL = 30 days (in seconds)
const TTL_SECONDS = 30 * 24 * 60 * 60;

/**
 * GET /cache
 * Retrieves cached notice_preferences for the client's IP
 */
app.get("/cache", async (req, res) => {
  const ip = req.ip;

  try {
    const value = await redis.get(ip);
    if (value === null) {
      return res.status(404).json({ message: "No value found for this IP" });
    }
    res.json({ ip, notice_preferences: value });
  } catch (err) {
    console.error("Error getting Redis value:", err);
    res.status(500).json({ error: "Failed to get value from Redis" });
  }
});

/**
 * POST /cache
 * Sets notice_preferences for the client's IP
 * Body: { data: { notice_preferences: "0" } }
 */
app.post("/cache", async (req, res) => {
  const ip = req.ip;
  const notice_preferences = req.body?.data?.notice_preferences;

  if (typeof notice_preferences === "undefined") {
    return res.status(400).json({
      error: "Missing 'data.notice_preferences' in request body",
    });
  }

  try {
    await redis.set(ip, notice_preferences, { EX: TTL_SECONDS });
    res.json({
      message: "Value set successfully",
      ip,
      notice_preferences,
      expires_in_days: 30,
    });
  } catch (err) {
    console.error("Error setting Redis value:", err);
    res.status(500).json({ error: "Failed to set value in Redis" });
  }
});

app.listen(3000, () => console.log("Server running on http://localhost:3000"));

In order to test this, I wanted to simulate a live environment. So I tested it in production.

Now, before you tear your hair out, I want to be clear. I tested in production, but I did not integrate it into production code. I kept the existing third-party cookie implementation live and used the QA instance of my Redis backend in parallel to observe behavior.

This allowed me to see how real user traffic interacted with the system without affecting user experience.

I observed the key value stores in Redis and noticed something incredibly odd. I expected only public IP addresses in Redis, but found many private IPs, and their preference levels were constantly changing.

That's when I realized people at various companies used their own VPN, and they were sending over the proxy's IP address and not the client's. Had I integrated it into the core logic, many people would accidentally be setting each other's cookie preferences. Oops!

I corrected it by checking the X-Forwarded-For header instead of the provided IP. Express.js makes this easy.

// Trust proxy headers for accurate client IP detection
app.set("trust proxy", true);

In the end, caching IP addresses to cookie preference settings wasn't a perfect solution. But for our purposes, it got the job of smoothing out the user's journey across domains.

Takeaways

Use data to understand your users. Introducing the cookie banner correlated with higher bounce rates. Minimizing the need to interact with it lowered it.
Continuously verify your results. We saw initial success with third-party cookies, but as the browser landscape shifted, the problem demanded a new solution.
Testing in prod is okay... Sometimes. Ideally, simulate without user engagement, but the most important thing is to not break your user experience.

Final Thoughts

This project reminded me that even small UX details can have a measurable business impact — and that the best engineering often lives at the intersection of technical creativity and user empathy.

Sometimes the fix isn’t about elegant architecture — it’s about understanding how people actually experience the product and optimizing for them.

Why You're Spending Too Much Money on Datadog Metrics

Jack Jiang — Thu, 02 Oct 2025 21:12:00 +0000

As a kid, I had the annoying habit of turning lights on in the house and forgetting to turn them off. My dad had to lecture me a few times about how electricity costs money and how I was wasting it.

Today, I don't leave the lights on anymore. However, I found myself involved in a different kind of waste.

As an SRE at Indeed, the first project I tackled was to reduce our Datadog spend. I found myself looking at a multi-million dollar budget on various Datadog expenses - metrics, logging, tracing - the whole shebang. The task was overwhelming, but my manager did point me to a quick win - reducing our metrics spend.

How Metrics Billing Works

Datadog bills metrics on two factors - the ingestion volume of each metric, and the number of unique combinations of tags each metric has, known as cardinality.

Depending on the number of different tag values a metric had, the cardinality blew up exponentially. We were spending hundreds of thousands of dollars per year tagging these metrics.

How I saved $100k+ per year

I catalogued the progress of cost savings per metric via a spreadsheet, tracking metric names, tags, cardinality, and potential cost savings, starting with the biggest offenders. I calculated potential savings with a tool to identify which tags were being queried within our Datadog namespace (which is now located under the Manage Tags menu in the metric view) and which ones were not. The view also calculates the hypothetical cardinality if you change the tags on a metric without saving the changes. By removing the unqueried tags, I calculated the theoretical cost savings and started reaching out to metric owners who had the highest theoretical savings.

Many of these folks added extra tags for debugging purposes and didn't realize how much it would cost. The most expensive metrics had cardinalities upwards of 200,000! Most were willing to part ways with tags they didn't use for dashboards, but some held on for debugging purposes. Even so, after a month of chasing down metric owners, I managed to trim down about $100k in annual metric costs.

Takeaways

Having many tag keys wasn't as big a problem as having many tag values. More tag values = exponential cardinality growth.
Look before you leap. Make sure metric users are on board before cutting down tags.
Doing this once wasn't enough. Metric bloat inevitably happened, so regular check-ins helped.

Happy savings!