DEV Community: Harikrushna V

FHIR DiagnosticReport Resource: A Developer's Guide to Lab Reports and Radiology in an Indian HMIS

Harikrushna V — Sun, 05 Jul 2026 08:57:53 +0000

FHIR DiagnosticReport Resource: A Developer's Guide to Lab Reports and Radiology in an Indian HMIS

If you've ever tried to build a lab module or a radiology viewer inside a Hospital Management Information System, you know the pain. Pathology labs send PDFs. Radiology departments push DICOM. Hospital staff re-types values into Excel. Patients carry printouts between visits, and when they switch hospitals, the new doctor's first question is always the same — "can you bring your old reports?"

The FHIR DiagnosticReport resource is the FHIR answer to that chaos. It is the canonical way to model a lab report, a histopathology report, or a radiology report as a structured, queryable, machine-readable document. When your HMIS stores DiagnosticReports properly, the patient's history follows them across facilities — through ABDM's ABHA-linked records, across the PHR (Personal Health Record) app on their phone, and into the next hospital that sees them.

In this post, we'll walk through every important field of DiagnosticReport, build it with HAPI FHIR in Java + Spring Boot, and tie it together with the Indian healthcare context: NABL-accredited labs, ABDM's diagnostic record sharing, and SNOMED CT coding.

This is the eighth post in our FHIR Resource Deep-Dive series for Indian healthcare IT. The previous posts covered Patient, Practitioner, Organization, Encounter, Condition, Observation, and MedicationRequest. If you're building or scaling an HMIS in India and want the FHIR fundamentals tight, start with Patient and Observation — DiagnosticReport hangs off both.

What Is a FHIR DiagnosticReport?

The official FHIR R4 spec describes DiagnosticReport as: "The findings and interpretation of diagnostic tests performed on patients, groups of patients, devices, and locations, and/or specimens derived from these. The report includes clinical context such as requesting and performing provider information, and some mix of atomic results, images, textual and coded interpretations, and formatted representations of these reports."

In plain English: a DiagnosticReport is the wrapper around a lab or radiology report. It is not the individual test results themselves — those are Observation resources (e.g., a haemoglobin value, a blood glucose reading, a tumour measurement on a CT scan). The DiagnosticReport is the report document that groups all those observations together, attaches them to a patient and an encounter, identifies who performed the test and who interpreted it, and gives the report a status and a coded type.

Think of it like this:

Observation = a single lab value (HbA1c = 7.2%)
DiagnosticReport = the complete "HbA1c report" document containing that value plus the methodology, the reference lab, the interpreting pathologist, and the PDF attachment the lab sends back

In a well-modelled FHIR system, a single DiagnosticReport for a Complete Blood Count (CBC) might reference a dozen Observation resources — RBC count, WBC count, haemoglobin, haematocrit, platelets, MCV, MCH, MCHC, and so on. The report tells you what was ordered, when, by whom, and where to find the underlying numbers.

Why This Matters for an Indian HMIS

Three things make DiagnosticReport especially important if you're building healthcare software for India:

1. NABL accreditation requires structured outputs. The National Accreditation Board for Testing and Calibration Laboratories (NABL) accredits pathology labs in India against ISO 15189. NABL-accredited labs are required to issue reports that identify the test, the methodology, the reference range, and the accreditation number of the lab. A free-text PDF is no longer enough for many empanelled labs. FHIR DiagnosticReport gives you the structured backbone those reports need.

2. ABDM's diagnostic record sharing is built around DiagnosticReport. India's Ayushman Bharat Digital Mission (ABDM) uses FHIR profiles under the hood. When a patient fetches their records through an ABHA-linked PHR app like the ABDM-compliant health locker, lab reports show up as DiagnosticReport resources bundled with their referenced Observations. If your HMIS doesn't produce FHIR-compliant DiagnosticReports, your patients' lab history simply won't show up in their ABDM PHR — which means the patient still has to carry printouts.

3. SNOMED CT is the international coding system that NABL and AIIMS are pushing. India adopted SNOMED CT as a national terminology in 2018 through the National Resource Centre for EHR Standards (NRCeS). For diagnostic reports, the report code and the conclusionCode fields should be SNOMED CT-coded so that reports can be exchanged across hospitals and integrated with international research datasets.

The DiagnosticReport Fields That Actually Matter

Let's go field by field. I'll focus on the ones you'll touch in real Indian HMIS implementations. For the full list, the FHIR R4 DiagnosticReport spec is the reference.

`status` — the lifecycle of the report

The status field is a required code that tells you where the report is in its lifecycle. The allowed values in R4 are:

registered — the report has been ordered but not yet performed
partial — some results are available, but the report is not final
preliminary — the report is available in a draft form, not yet verified by the signing pathologist or radiologist
final — the report is complete and verified
amended — the report was modified after being finalized
corrected — the report was corrected after being finalized (used when a wrong value was issued)
appended — the report was amended by appending additional content
cancelled — the report has been withdrawn
entered-in-error — the report should never have been made (e.g., filed against the wrong patient)

In a real lab workflow in India, you'll most commonly see registered (ordered, sample collected), preliminary (instrument finished, awaiting pathologist sign-off), final (pathologist signed), and corrected (typo in original final report fixed after the fact). The state transitions matter because:

A preliminary report should not trigger downstream billing finalization.
A corrected report should generate an alert on the patient's record.
A cancelled report should be excluded from cumulative summaries.

`category` — what kind of report is this?

The category field uses a CodeableConcept to classify the report. The most common values you'll see:

LAB — laboratory (pathology, biochemistry, microbiology)
RAD — radiology (X-ray, CT, MRI, ultrasound)
PATH — anatomical pathology / histopathology
HISTO — histology specifically
CARD — cardiology (ECG, echo, stress test reports)

NABL accreditation matters most for LAB, PATH, and HISTO. Indian HMISes often show a different colour or icon for each category so the doctor can scan a patient's record quickly.

`code` — what was the report for?

The code field is a CodeableConcept that identifies the type of report. In Indian practice:

For lab reports, the code is typically a LOINC code. For example, the LOINC code for a Complete Blood Count is 58410-2 (Complete blood count (hemogram) panel - Blood).
For radiology reports, you can also use LOINC, but many Indian PACS systems use their own internal codes. Mapping them to LOINC at the HMIS boundary is a worthwhile engineering investment.
For histopathology, LOINC is the standard but the SNOMED CT morphology code may also be useful.

LOINC adoption in India is growing but still patchy. Many Indian labs use locally-defined codes that map to a smaller set of common tests. If you're building an HMIS, decide on a policy: either store both the local code and the LOINC code, or commit to LOINC at the FHIR boundary.

`subject` — which patient

A reference to the Patient resource. In a multi-hospital ABDM setup, this would be the patient's ABHA-linked Patient resource.

`effective[x]` — when was the test performed

This is a choice type. It's either effectiveDateTime (a single timestamp for tests that happen at one moment, like a glucose reading) or effectivePeriod (a range for tests that span time, like a 24-hour urine collection or a Holter monitor). For radiology, effectivePeriod is often the right choice because the scan acquisition takes time.

`issued` — when was the report released

This is when the lab or radiology system released the report to the requesting clinician. In a finalised pathology report, this is the timestamp the pathologist signed off. Different from effective[x] (when the sample was collected or scan done) and different from date (an FHIR metadata timestamp).

`performer` — who performed the test

An array of references to Practitioner and Organization resources. For a lab report, you'd typically reference both the lab organization (e.g., "SRL Diagnostics, Andheri branch") and the performing pathologist. For radiology, the performing radiologist is the key performer.

`results` — the underlying Observations

An array of references to Observation resources. Each Observation referenced here is a single test result (haemoglobin value, blood glucose, lesion measurement on CT, etc.) that belongs to this report. In our ABDM context, the ABDM Health Locker's "Lab Reports" view shows the DiagnosticReport with a button to view all referenced Observations.

`imagingStudy` — for radiology reports

A reference to an ImagingStudy resource. ImagingStudy is the FHIR resource for the actual imaging metadata (DICOM Study UID, number of images, modality). For an X-ray or CT, you'd create both an ImagingStudy and a DiagnosticReport. The DiagnosticReport.presentedForm carries the actual PDF or image.

`conclusion` — the free-text interpretation

The radiologist's or pathologist's narrative interpretation. For example: "Impression: 1.2 x 1.4 cm hypoechoic lesion in the right lobe of the liver, likely simple cyst. Clinical correlation advised."

`conclusionCode` — coded diagnoses from the report

An array of CodeableConcept. For histopathology, you'd put SNOMED CT morphology codes here. For radiology, you might use SNOMED CT clinical findings or ICD-10.

`presentedForm` — attachments

An array of Attachment resources. This is where the actual PDF or image goes. In practice, the FHIR server stores the binary content and presents a URL the client can fetch. For Indian labs, the PDF is typically the signed-and-stamped report the lab sends to the patient.

Building It with HAPI FHIR in Java

Let's see the actual Java code. I'll use HAPI FHIR R4, which is the most widely used FHIR implementation in Java.

Maven dependencies

<dependencies>
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-structures-r4</artifactId>
        <version>6.8.0</version>
    </dependency>
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-client</artifactId>
        <version>6.8.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

Creating a CBC lab report

Here's how to model a Complete Blood Count (CBC) DiagnosticReport with three referenced Observations: haemoglobin, total WBC count, and platelet count.

package com.orglance.hmis.fhir;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.parser.IParser;
import org.hl7.fhir.r4.model.*;
import org.springframework.stereotype.Service;

import java.util.Date;
import java.util.List;

@Service
public class DiagnosticReportBuilder {

    private final FhirContext fhirContext = FhirContext.forR4();

    /**
     * Build a CBC (Complete Blood Count) DiagnosticReport for an Indian patient.
     *
     * @param patientMrn   The patient's hospital MRN (will be the Patient.id)
     * @param patientName  The patient's display name (for the report header)
     * @param encounterId  The encounter this report belongs to
     * @param labOrgId     The NABL-accredited lab's Organization.id
     * @param pathologistId The performing pathologist's Practitioner.id
     * @return A complete DiagnosticReport resource as a JSON string
     */
    public String buildCbcReport(String patientMrn,
                                  String patientName,
                                  String encounterId,
                                  String labOrgId,
                                  String pathologistId) {

        // The DiagnosticReport resource itself
        DiagnosticReport report = new DiagnosticReport();

        // Logical id
        report.setId("cbc-" + patientMrn + "-" + System.currentTimeMillis());

        // status: final (pathologist has signed off)
        report.setStatus(DiagnosticReport.DiagnosticReportStatus.FINAL);

        // category: LAB
        report.addCategory(new CodeableConcept()
                .addCoding(new Coding()
                        .setSystem("http://terminology.hl7.org/CodeSystem/v2-0074")
                        .setCode("LAB")
                        .setDisplay("Laboratory")));

        // code: LOINC 58410-2 - Complete blood count (hemogram) panel
        report.setCode(new CodeableConcept()
                .addCoding(new Coding()
                        .setSystem("http://loinc.org")
                        .setCode("58410-2")
                        .setDisplay("Complete blood count (hemogram) panel - Blood"))
                .setText("Complete Blood Count (CBC)"));

        // subject: reference to the Patient
        report.setSubject(new Reference("Patient/" + patientMrn)
                .setDisplay(patientName));

        // effectiveDateTime: when the sample was collected
        report.setEffective(new DateTimeType("2026-06-25T09:30:00+05:30"));

        // issued: when the report was released
        report.setIssued(new Date());

        // performer: the lab org and the pathologist
        report.addPerformer(new Reference("Organization/" + labOrgId)
                .setDisplay("NABL Accredited Lab"));
        report.addPerformer(new Reference("Practitioner/" + pathologistId)
                .setDisplay("Dr. Priya Sharma, Pathologist"));

        // encounter
        report.setEncounter(new Reference("Encounter/" + encounterId));

        // results: references to the three Observations
        // In a real system, you'd persist these Observations first and use their real IDs.
        // Here we create them inline for clarity.
        Observation hb = buildObservation(patientMrn, encounterId,
                "718-7", "Hemoglobin [Mass/volume] in Blood",
                "g/dL", 14.2, "13.0-17.0");
        Observation wbc = buildObservation(patientMrn, encounterId,
                "6690-2", "Leukocytes [#/volume] in Blood by Automated count",
                "10*3/uL", 7.8, "4.0-11.0");
        Observation plt = buildObservation(patientMrn, encounterId,
                "777-3", "Platelets [#/volume] in Blood by Automated count",
                "10*3/uL", 250.0, "150-400");

        // Note: in a real FHIR server, you'd POST each Observation first,
        // get the assigned IDs back, then reference them here.
        // For demonstration we set logical references.
        report.addResult(new Reference()
                .setReference("Observation/cbc-hb-" + patientMrn)
                .setDisplay("Hemoglobin"));
        report.addResult(new Reference()
                .setReference("Observation/cbc-wbc-" + patientMrn)
                .setDisplay("Total WBC count"));
        report.addResult(new Reference()
                .setReference("Observation/cbc-plt-" + patientMrn)
                .setDisplay("Platelet count"));

        // conclusion: free-text interpretation
        report.setConclusion(
            "All values within reference range. " +
            "No evidence of anemia, leukocytosis, or thrombocytopenia. " +
            "Recommend repeat CBC in 6 months as part of routine health check-up.");

        // conclusionCode: SNOMED CT code for "normal findings"
        report.addConclusionCode(new CodeableConcept()
                .addCoding(new Coding()
                        .setSystem("http://snomed.info/sct")
                        .setCode("17621005")
                        .setDisplay("Normal (qualifier)")));

        // presentedForm: the PDF attachment (in real use, attach the actual binary)
        Attachment pdfAttachment = new Attachment()
                .setContentType("application/pdf")
                .setTitle("CBC Report - " + patientName + " - " + report.getIssued())
                .setCreation(report.getIssued())
                .setHash(org.hl7.fhir.r4.model.Base64BinaryType
                        .fromStringValue("placeholder-base64-pdf-content"));
        report.addPresentedForm(pdfAttachment);

        // Serialize to JSON
        IParser parser = fhirContext.newJsonParser()
                .setPrettyPrint(true);
        return parser.encodeResourceToString(report);
    }

    private Observation buildObservation(String patientMrn, String encounterId,
                                          String loincCode, String loincDisplay,
                                          String unit, double value, String refRange) {
        Observation obs = new Observation();
        obs.setStatus(Observation.ObservationStatus.FINAL);
        obs.setCode(new CodeableConcept()
                .addCoding(new Coding()
                        .setSystem("http://loinc.org")
                        .setCode(loincCode)
                        .setDisplay(loincDisplay)));
        obs.setSubject(new Reference("Patient/" + patientMrn));
        obs.setEncounter(new Reference("Encounter/" + encounterId));
        obs.setValue(new Quantity().setValue(value).setUnit(unit).setSystem("http://unitsofmeasure.org").setCode(unit));
        obs.setReferenceRange(List.of(
                new Observation.ObservationReferenceRangeComponent()
                        .setText(refRange)));
        return obs;
    }
}

Storing and exposing the report

Once you build the DiagnosticReport JSON, you POST it to your FHIR server. With HAPI FHIR's JPA server starter:

@PostMapping("/api/fhir/DiagnosticReport")
public ResponseEntity<String> createReport(@RequestBody DiagnosticReport report) {
    // The DaoConfig and FhirContext are autowired by Spring Boot
    MethodOutcome outcome = myFhirClient.create()
            .resource(report)
            .execute();

    return ResponseEntity
            .status(HttpStatus.CREATED)
            .header("Location", outcome.getId().toUnqualifiedVersionless().getValue())
            .body("Report created: " + outcome.getId().getIdPart());
}

To fetch all CBC reports for a patient:

@GetMapping("/api/patients/{mrn}/lab-reports")
public List<DiagnosticReport> getLabReports(@PathVariable String mrn) {
    Bundle results = myFhirClient.search()
            .forResource(DiagnosticReport.class)
            .where(DiagnosticReport.SUBJECT.hasId("Patient/" + mrn))
            .and(DiagnosticReport.CATEGORY.exactly().code("LAB"))
            .and(DiagnosticReport.STATUS.exactly().code("final"))
            .returnBundle(Bundle.class)
            .execute();

    return results.getEntry().stream()
            .map(entry -> (DiagnosticReport) entry.getResource())
            .toList();
}

This is the query that powers a patient's "My Lab Reports" view in your HMIS UI — and that same query is what ABDM's PHR apps use (with appropriate authorization) when fetching a patient's records through ABHA consent.

An Indian Radiology Workflow, End to End

Let me walk through a realistic scenario for a CT abdomen report at an Indian hospital.

Step 1 — Order placement. The requesting doctor orders a "CT Abdomen with Contrast" using a ServiceRequest resource (LOINC 30619-5 or a local code). This creates a DiagnosticReport with status = registered and a placeholder code. The Order Entry UI shows it as "Ordered, awaiting scheduling."

Step 2 — Sample/Study performed. The patient undergoes the CT scan. The PACS system creates an ImagingStudy resource with the DICOM Study Instance UID. The HMIS updates the DiagnosticReport.effectivePeriod to reflect the scan acquisition window and the imagingStudy field to reference the new ImagingStudy.

Step 3 — Preliminary report. The radiologist opens the study in their reporting workstation and saves a preliminary draft. The HMIS updates status = preliminary and starts populating conclusion. The requesting doctor's UI shows "Preliminary report available" with a yellow indicator.

Step 4 — Final report. After the radiologist signs off, status = final and issued is set to the sign-off timestamp. A conclusionCode of the relevant SNOMED CT clinical finding is added (e.g., 414916001 for "Obstruction"). The signed PDF is attached via presentedForm.

Step 5 — ABDM sharing. If the patient has linked their ABHA, your HMIS's ABDM integration publishes the final DiagnosticReport to the ABDM Health Information Exchange. The patient can now see this CT report in their ABHA app on their phone, and any other ABDM-compliant hospital they visit can fetch it with the patient's consent.

This flow is the difference between a hospital that "has a computer system" and a hospital that participates in India's digital health ecosystem.

Common Pitfalls When Modelling DiagnosticReport

After working with multiple Indian HMIS implementations, here are the mistakes I see most often:

1. Treating DiagnosticReport as a single value, not a wrapper. A DiagnosticReport without referenced Observations is just a labelled PDF. Always model the underlying Observations and reference them. The PDF in presentedForm is for human readability, but the structured Observations are what enable analytics, alerts, and cross-hospital exchange.

2. Using free-text only for code. If you only set code.text = "CBC" without a LOINC or SNOMED CT coding, your reports can't be discovered by code-based search across institutions. Always set a coding entry.

3. Not handling the corrected and amended statuses. Indian labs do issue corrected reports — a wrong patient ID is caught, a typo is fixed. Your HMIS should treat corrected reports as a new revision, not as a duplicate, and surface the correction clearly in the UI.

4. Storing the PDF in the FHIR server instead of a binary store. presentedForm.content can be inline base64, but it's not efficient for large PDFs. The recommended pattern is to POST the binary to a FHIR Binary endpoint, then reference it from presentedForm.url. Most production FHIR servers, including HAPI's JPA server, support this.

5. Ignoring category. Without category, you can't filter "show me only lab reports" or "show me only radiology reports" efficiently at the FHIR layer. Always populate it.

How ArogyaPlus HMIS Handles DiagnosticReport

At ArogyaPlus HMIS, we've built DiagnosticReport support directly into the lab and radiology modules. When a NABL-accredited lab partner pushes results through our API, we automatically:

Create referenced Observation resources for each test value, SNOMED CT-coding where the lab provides the code
Bundle them into a DiagnosticReport with the correct status lifecycle
Attach the signed PDF via presentedForm
Push the bundle to ABDM's HIU if the patient has linked their ABHA

This is the same FHIR R4 pattern you'll find in any ABDM-compliant HMIS, and it's the architectural baseline we'd recommend if you're building or modernizing a hospital system in India.

If you're scaling an HMIS or a digital health platform and want to talk FHIR, ABDM integration, or lab/radiology workflows, reach out — we work with hospital chains, diagnostic lab networks, and health-tech startups across India and South-East Asia. Drop us a line at hello@orglance.com or book a slot on our Calendly.

About the author: Harikrushna V is a software architect with 13 years of experience in Java, Spring Boot, and healthcare IT — ex-PayPal, Salesforce, NCR, and ST Microelectronics. He's the founder of Orglance Technologies and SnowCare Health Tech, building FHIR-native hospital systems and digital health platforms. Connect on LinkedIn.

Tags: fhir, healthcareit, java, india

FHIR MedicationRequest Resource: A Developer's Guide to Modelling Prescriptions in an Indian HMIS

Harikrushna V — Tue, 23 Jun 2026 13:06:17 +0000

FHIR MedicationRequest Resource: A Developer's Guide to Modelling Prescriptions in an Indian HMIS

If you're building a Hospital Management Information System in India, prescriptions are at the heart of your OPD workflow. Every doctor writes dozens of them a day, every pharmacy has to dispense them, and every audit trail needs to capture who prescribed what, when, and to whom. FHIR's MedicationRequest resource is the canonical way to model a prescription order in a modern, interoperable HMIS.

In this post — seventh in our FHIR Resource Deep-Dives series for Indian healthcare IT — we'll walk through MedicationRequest end to end. We'll see how it differs from the closely-related MedicationStatement and MedicationDispense resources, dig into the fields you'll actually use in production, and build a working Spring Boot service that creates and reads prescriptions. Along the way, we'll wire it into the India-specific concerns that come up in real HMIS work: Jan Aushadhi generic substitution, DPCO ceiling price enforcement, NLEM-aligned essential medicines, and ABHA-linked prescription records.

MedicationRequest vs MedicationStatement vs MedicationDispense

FHIR gives you three resources for tracking medications, and they map to three different moments in the medication lifecycle:

MedicationRequest — an order or prescription. A doctor says "give this patient amoxicillin 500mg three times a day for 7 days." The order is created, but the patient may or may not have started taking it.
MedicationStatement — a record of what the patient is actually taking. "Patient reports taking metformin 500mg twice daily for the past 6 months." Useful for medication reconciliation at admission.
MedicationDispense — a record of what the pharmacy actually handed out. The medication may have been dispensed against a MedicationRequest (so MedicationDispense will reference the prescription via authorizingPrescription), or it may have been an OTC sale with no prescription involved.

In your HMIS, the typical OPD-to-pharmacy flow is:

OPD consultation ends → doctor creates a MedicationRequest (the prescription).
Patient walks to pharmacy → pharmacy creates a MedicationDispense referencing the MedicationRequest.
Patient is admitted to IPD next month → on admission, you create a MedicationStatement summarising their home medications for reconciliation.

The three resources are linked by MedicationRequest.basedOn (the plan or order this request is based on), MedicationRequest.replaces (a previous prescription this one supersedes), and MedicationDispense.authorizingPrescription (the MedicationRequest this dispense fulfils). Get the linkage right and the audit trail writes itself; get it wrong and you spend six months untangling dispensations.

Anatomy of a MedicationRequest

The R4 spec defines MedicationRequest with these key fields you'll use in production:

Field	Cardinality	Purpose
`status`	1..1	`active` / `completed` / `stopped` / `draft` / `unknown` / `cancelled` / `entered-in-error`
`intent`	1..1	`proposal` / `plan` / `order` / `original-order` / `reflex-order` / `filler-order`
`medicationCodeableConcept`	1..1	The drug prescribed (RxNorm, SNOMED CT, ATC, or local coding system)
`subject`	1..1	Reference to the `Patient` (ABHA-linked in India)
`encounter`	0..1	Reference to the `Encounter` (the OPD visit)
`authoredOn`	0..1	When the prescription was written
`requester`	0..1	Reference to the `Practitioner` who wrote it (HPR ID in India)
`dosageInstruction`	0..*	How the patient should take it (dose, route, frequency, duration)
`dispenseRequest`	0..1	Pharmacy-side info: quantity, refills, validity period, expected supply duration
`substitution`	0..1	Whether generic substitution is allowed at the pharmacy
`note`	0..*	Free-text notes ("take after meals", "avoid driving")
`priorPrescription`	0..1	Reference to a previous `MedicationRequest` this one replaces
`detectedIssue`	0..*	Links to allergy / interaction warnings raised at prescribing time

A minimal but realistic MedicationRequest for an Indian OPD looks like this:

{
  "resourceType": "MedicationRequest",
  "id": "prescription-2026-06-23-001",
  "status": "active",
  "intent": "order",
  "medicationCodeableConcept": {
    "coding": [
      {
        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
        "code": "197361",
        "display": "Amoxicillin 500mg"
      },
      {
        "system": "https://janaushadhi.gov.in/product-codes",
        "code": "JAP-AMX-500",
        "display": "Jan Aushadhi Amoxicillin 500mg (generic)"
      }
    ],
    "text": "Amoxicillin 500mg (generic substitution allowed)"
  },
  "subject": {
    "reference": "Patient/abha-14-1234-5678-9012",
    "display": "Ravi Kumar"
  },
  "encounter": {
    "reference": "Encounter/opd-2026-06-23-1045"
  },
  "authoredOn": "2026-06-23T10:45:00+05:30",
  "requester": {
    "reference": "Practitioner/hpr-MCI-12345",
    "display": "Dr. Priya Shah"
  },
  "dosageInstruction": [
    {
      "text": "One tablet three times a day for 7 days, after meals",
      "timing": {
        "repeat": {
          "frequency": 3,
          "period": 1,
          "periodUnit": "d"
        }
      },
      "doseAndRate": [
        {
          "doseQuantity": {
            "value": 500,
            "unit": "mg",
            "system": "http://unitsofmeasure.org",
            "code": "mg"
          }
        }
      ],
      "route": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "26643006",
            "display": "Oral route"
          }
        ]
      }
    }
  ],
  "dispenseRequest": {
    "quantity": {
      "value": 21,
      "unit": "tablets"
    },
    "numberOfRepeatsAllowed": 0,
    "validityPeriod": {
      "start": "2026-06-23",
      "end": "2026-07-23"
    },
    "expectedSupplyDuration": {
      "value": 7,
      "unit": "days",
      "system": "http://unitsofmeasure.org",
      "code": "d"
    }
  },
  "substitution": {
    "allowedBoolean": true,
    "reason": {
      "text": "Generic substitution permitted per Jan Aushadhi scheme guidelines"
    }
  }
}

Drug coding in the Indian context

Drug coding is where most Indian HMIS implementations fall down. The international standards — RxNorm (US-centric), SNOMED CT (clinical, not drug-focused), ATC (WHO classification) — all work, but they don't capture the specific regulatory context that matters in India:

Jan Aushadhi (janaushadhi.gov.in): The government's affordable generic-medicine scheme run under the Pharmaceuticals & Medical Devices Bureau of India (PMBI). Every Jan Aushadhi product has a unique product code, and the prescription should allow the pharmacist to substitute a Jan Aushadhi generic for a branded equivalent. The substitution.allowedBoolean field is critical here — set it to true and the pharmacy can offer the patient a Jan Aushadhi alternative, typically at 50–90% lower cost. The Indian government has been pushing for broader Jan Aushadhi adoption under the Jan Aushadhi Suvidha and Jan Samarthan campaigns, so any new HMIS should support it out of the box.
DPCO (Drug Prices Control Order): NPPA (National Pharmaceutical Pricing Authority) sets ceiling prices for scheduled drugs under the DPCO, 2013. Your HMIS should validate that the dispensed price doesn't exceed the DPCO ceiling. You can extend MedicationRequest with a custom extension like dispenseRequest.extension.dpco-ceiling-price to record the regulatory cap, and your pharmacy module can hard-stop a dispense that exceeds it.
NLEM (National List of Essential Medicines): A subset of drugs that are considered essential for India's healthcare needs, published by the Ministry of Health. Useful for public-hospital implementations where the formulary is restricted to NLEM drugs. Most government schemes (CGHS, ESIC, Ayushman Bharat) reimburse only NLEM drugs.
Brand vs generic: Indian prescriptions often specify a brand name (e.g. "Mox 500" for a branded amoxicillin by Ranbaxy). Your mapping layer should resolve brand → generic → RxNorm/SNOMED → Jan Aushadhi code, so the prescription is both human-readable and machine-interoperable. The doctor types the brand, the patient sees a friendly label, but the MedicationRequest carries the full set of codings.

A common pattern in ArogyaPlus is to keep an internal drug master table (with columns for brand name, generic name, strength, manufacturer, RxNorm code, SNOMED code, Jan Aushadhi code, DPCO ceiling price, NLEM flag, schedule H/H1/X classification), and resolve all of these at the point of prescription creation.

Spring Boot + HAPI FHIR code

Here's a working Spring Boot service that creates a MedicationRequest from an OPD prescription form, persists it, and exposes it via REST:

@Service
public class PrescriptionService {

    private final FhirContext fhirContext = FhirContext.forR4();
    private final IParser parser = fhirContext.newJsonParser();

    @Autowired
    private MedicationRequestDao medicationRequestDao;

    @Autowired
    private DrugMasterRepository drugMasterRepository;

    public MedicationRequest createPrescription(PrescriptionRequest request) {
        // Look up the drug in our internal drug master
        DrugMaster drug = drugMasterRepository.findById(request.getDrugId())
            .orElseThrow(() -> new DrugNotFoundException(request.getDrugId()));

        // Build the MedicationRequest
        MedicationRequest medReq = new MedicationRequest();
        medReq.setId("prescription-" + UUID.randomUUID());
        medReq.setStatus(MedicationRequest.MedicationRequestStatus.ACTIVE);
        medReq.setIntent(MedicationRequest.MedicationRequestIntent.ORDER);

        // Drug coding — RxNorm + Jan Aushadhi + brand
        CodeableConcept medication = new CodeableConcept();
        medication.addCoding()
            .setSystem("http://www.nlm.nih.gov/research/umls/rxnorm")
            .setCode(drug.getRxnormCode())
            .setDisplay(drug.getGenericName() + " " + drug.getStrength());
        if (drug.getJanAushadhiCode() != null) {
            medication.addCoding()
                .setSystem("https://janaushadhi.gov.in/product-codes")
                .setCode(drug.getJanAushadhiCode())
                .setDisplay("Jan Aushadhi " + drug.getGenericName());
        }
        medication.setText(drug.getBrandName() + " (" + drug.getGenericName() + " " + drug.getStrength() + ")");
        medReq.setMedication(medication);

        // Patient reference (ABHA)
        medReq.setSubject(new Reference("Patient/" + request.getPatientAbhaId()));

        // Encounter reference
        medReq.setEncounter(new Reference("Encounter/" + request.getEncounterId()));

        // Authored timestamp
        medReq.setAuthoredOn(new Date());

        // Prescribing doctor
        medReq.setRequester(new Reference("Practitioner/" + request.getPractitionerHprId())
            .setDisplay(request.getDoctorName()));

        // Dosage instructions
        Dosage dosage = new Dosage();
        dosage.setText(request.getDosageText());
        Timing timing = new Timing();
        timing.getRepeat()
            .setFrequency(request.getFrequencyPerDay())
            .setPeriod(1)
            .setPeriodUnit(Timing.UnitsOfTime.D);
        dosage.setTiming(timing);
        Dosage.DosageDoseAndRateComponent doseAndRate = new Dosage.DosageDoseAndRateComponent();
        doseAndRate.getDoseQuantity()
            .setValue(drug.getStrengthValue())
            .setUnit(drug.getStrengthUnit());
        dosage.addDoseAndRate(doseAndRate);
        medReq.addDosageInstruction(dosage);

        // Dispense request — quantity, refills, DPCO validation
        MedicationRequest.MedicationRequestDispenseRequestComponent dispense =
            new MedicationRequest.MedicationRequestDispenseRequestComponent();
        dispense.setQuantity(new Quantity()
            .setValue(request.getTotalQuantity())
            .setUnit("tablets"));
        dispense.setNumberOfRepeatsAllowed(request.getRefills());
        if (request.getRefills() > 0) {
            dispense.setValidityPeriod(new Period()
                .setStart(new Date())
                .setEnd(DateUtils.addMonths(new Date(), 6)));
        }

        // DPCO ceiling price extension
        if (drug.getDpcoCeilingPrice() != null) {
            dispense.addExtension()
                .setUrl("https://nppa.gov.in/fhir/StructureDefinition/dpco-ceiling-price")
                .setValue(new Money()
                    .setValue(drug.getDpcoCeilingPrice())
                    .setCurrency("INR"));
        }
        medReq.setDispenseRequest(dispense);

        // Substitution policy
        MedicationRequest.MedicationRequestSubstitutionComponent substitution =
            new MedicationRequest.MedicationRequestSubstitutionComponent();
        substitution.setAllowedBoolean(Boolean.TRUE);
        substitution.setReason(new CodeableConcept().setText(
            "Generic substitution permitted per Jan Aushadhi scheme guidelines"));
        medReq.setSubstitution(substitution);

        // Persist
        return medicationRequestDao.save(medReq);
    }

    public String toJson(MedicationRequest medReq) {
        return parser.encodeResourceToString(medReq);
    }
}

And the REST controller:

@RestController
@RequestMapping("/api/fhir/MedicationRequest")
public class MedicationRequestController {

    @Autowired
    private PrescriptionService prescriptionService;

    @Autowired
    private MedicationRequestDao medicationRequestDao;

    @PostMapping
    public ResponseEntity<String> create(@RequestBody PrescriptionRequest request) {
        MedicationRequest created = prescriptionService.createPrescription(request);
        return ResponseEntity
            .status(HttpStatus.CREATED)
            .header("Content-Location", "/api/fhir/MedicationRequest/" + created.getId())
            .body(prescriptionService.toJson(created));
    }

    @GetMapping("/{id}")
    public ResponseEntity<String> get(@PathVariable String id) {
        return medicationRequestDao.findById(id)
            .map(prescriptionService::toJson)
            .map(json -> ResponseEntity.ok()
                .contentType(MediaType.APPLICATION_JSON)
                .body(json))
            .orElse(ResponseEntity.notFound().build());
    }
}

The MedicationRequestDao is your standard JPA / Mongo / HAPI FHIR JPA repository — pick whatever persistence layer matches the rest of your HMIS. The HAPI FHIR structure handles all of the FHIR-specific validation, codings, and extensions for you.

ABDM integration: prescriptions as part of a Bundle

In the ABDM (Ayushman Bharat Digital Mission) ecosystem, a prescription is rarely a standalone resource. It's part of a Bundle — typically a document or transaction bundle — that ties the prescription to the patient, the encounter, the prescribing doctor, and any observations (vitals, lab results) that informed the prescription.

A common pattern is to build the prescription bundle at the end of the OPD visit, sign it digitally (using ABDM's digital signature specifications), and push it to the patient's PHR (Personal Health Record) address via the /v0.5/health-information/transfer flow. The bundle typically contains:

Patient (with ABHA ID)
Encounter (the OPD visit)
Practitioner (the doctor, with HPR ID)
Organization (the hospital, with HFR ID)
One or more MedicationRequest resources
Related Observation resources (vitals taken during the visit)
A Composition resource as the bundle's first entry (the document manifest, pointing at all the above)

This is how ABDM achieves longitudinal health records — every prescription you've ever written is linked to the patient's ABHA and can be pulled up by any other hospital in the network (with the patient's consent, of course). And because everything is a MedicationRequest with proper RxNorm / SNOMED / Jan Aushadhi codings, the receiving hospital can immediately understand, verify, and continue the prescription course.

Common pitfalls

A few things to watch out for in production:

Drug master consistency: If your drug master is out of sync with the latest Jan Aushadhi or DPCO lists, your prescription will have stale codings. Automate the sync — Jan Aushadhi publishes its product list as a downloadable CSV, and NPPA publishes DPCO ceiling prices quarterly. Schedule a nightly job to pull and reconcile.
Substitution consent: Don't enable generic substitution by default for every drug. Some drugs (e.g. narrow-therapeutic-index drugs like warfarin, levothyroxine, theophylline) should not be substituted without explicit doctor approval. The substitution.allowedBoolean field is per-prescription, not per-patient — use it carefully. Better yet, drive it from the drug master: NLEM drugs and Jan Aushadhi equivalents default to allowed; narrow-therapeutic-index drugs default to disallowed.
Refill vs renewal: numberOfRepeatsAllowed means "the pharmacy can dispense this prescription N more times without a new doctor visit." A "renewal" (a new prescription for the same drug after the original course ends) is a new MedicationRequest that replaces the old one via priorPrescription. Don't conflate the two in your pharmacy UI.
Status transitions: A prescription can go from active → completed (course finished) or active → stopped (doctor cancelled it). If you set status = stopped, also record statusReason — this is critical for clinical audit and for explaining to the patient why their medication was stopped.
Time zone: India is a single time zone (IST, UTC+5:30) now, but your FHIR resources should still carry explicit +05:30 offsets in all timestamps. Don't strip the offset; you will regret it the first time you integrate with a system in another country.
Don't store drug name in medicationCodeableConcept.text only: The text field is for human display. The codings in the coding array are for machine interoperability. If you only fill text and leave coding empty, you've built a fax machine, not an HMIS.

Closing thought

MedicationRequest is the resource that ties together the clinical (what was prescribed), regulatory (DPCO, Jan Aushadhi), and interoperability (ABDM) sides of Indian healthcare IT. Get the model right and the rest of your prescription workflow — pharmacy dispensing, drug interaction checks, formulary enforcement, ABHA-linked longitudinal records — becomes a matter of building the next resource on top.

If you're building an HMIS, start with Patient, Practitioner, Encounter, and MedicationRequest. That's the core outpatient loop. Everything else — Observation, Condition, Procedure, Immunization, AllergyIntolerance — extends from it. In the next post, we'll look at DiagnosticReport — the FHIR resource for NABL-accredited lab reports and radiology results — and how to tie it back into the same OPD visit.

Harikrushna V is the founder of Orglance Technologies — an India-based software services company specialising in Java/Spring Boot, healthcare IT, and fintech systems — and SnowCare Health Tech (ArogyaPlus HMIS). 13 years building enterprise systems across PayPal, Salesforce, and NCR. Building dedicated India engineering teams for US/UK/EU/Japan clients. Reach out: hello@orglancetechnologies.com

OAuth2 + OpenID Connect in Spring Boot: A Practical Guide for Java Backend Engineers

Harikrushna V — Fri, 05 Jun 2026 12:39:12 +0000

OAuth2 + OpenID Connect in Spring Boot: A Practical Guide for Java Backend Engineers

Most "JWT" tutorials in 2026 conflate two different things: OAuth2 (an authorization framework) and OpenID Connect (an identity layer built on top). In production, you rarely use JWTs without OAuth2 — and you almost never use OAuth2 without OIDC if you need to know who the user is. This post walks through the practical patterns: when to use which flow, how to wire Spring Security as both client and resource server, and the gotchas that trip up teams shipping federated identity for the first time.

OAuth2 vs OpenID Connect: The Distinction That Matters

OAuth2 is for authorization — "can this app access this resource on the user's behalf?" It issues access tokens. It does not, by itself, tell you who the user is.

OpenID Connect (OIDC) is for authentication — "who is this user?" It issues ID tokens (always JWTs) alongside the access token, in a standardized format with claims like sub, email, name, iss, aud.

If your service needs to know the user's identity, you need OIDC. If your service just needs to verify a token from a trusted issuer (e.g., to call a downstream API), OAuth2 alone is fine. Most production systems use both.

The Four Flows and When to Use Each

Flow	Use Case	Token Type
Authorization Code + PKCE	SPAs, mobile apps, native apps	Access + ID token via redirect
Authorization Code (with client secret)	Server-side web apps	Access + ID token via backend
Client Credentials	Service-to-service, no user	Access token only
Refresh Token	Long-lived sessions	New access token

For modern browser-based apps, Authorization Code with PKCE is the recommended flow — it eliminates the client secret requirement, works on public clients, and is the standard for SPAs. Service-to-service calls use Client Credentials.

Spring Security OAuth2 Resource Server

The most common pattern: your Spring Boot API is a resource server that validates access tokens issued by an external authorization server (Keycloak, Auth0, Okta, Azure AD, AWS Cognito). You don't issue tokens — you just verify them.

Maven Setup

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

That's it for dependencies. Spring Boot auto-configures most of what you need.

application.yml

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com/realms/myapp
          # OR use jwk-set-uri directly if discovery is unavailable:
          # jwk-set-uri: https://auth.example.com/realms/myapp/protocol/openid-connect/certs

When you specify issuer-uri, Spring Security fetches the OIDC discovery document from ${issuer-uri}/.well-known/openid-configuration, then loads the JWK Set, then validates tokens against the issuer. This is the production-ready approach — the alternative (hardcoded JWK Set) leaves you with no way to handle key rotation.

Security Configuration

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class ResourceServerConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt.jwtAuthenticationConverter(new JwtAuthenticationConverter()))
            )
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )
            .csrf(AbstractHttpConfigurer::disable);

        return http.build();
    }
}

SCOPE_admin is the default authority prefix that Spring applies to each scope claim in the JWT. To use a custom prefix (e.g., ROLE_), configure a JwtAuthenticationConverter with a JwtGrantedAuthoritiesConverter.

Extracting Custom Claims

The default behavior gives you scopes as authorities. To extract custom claims like tenant_id or user_role:

@Component
public class TenantContextFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {

        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth instanceof JwtAuthenticationToken jwtAuth) {
            String tenantId = jwtAuth.getToken().getClaimAsString("tenant_id");
            if (tenantId != null) {
                TenantContext.set(tenantId);
            }
        }

        try {
            filterChain.doFilter(request, response);
        } finally {
            TenantContext.clear();
        }
    }
}

This pattern — pulling tenant context out of the JWT into a ThreadLocal for downstream services — is something we use across all multi-tenant SaaS deployments at Orglance Technologies.

Spring Security OAuth2 Client

If your app issues tokens (e.g., you are a gateway or BFF), you're an OAuth2 client. The setup is more involved:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

spring:
  security:
    oauth2:
      client:
        registration:
          myapp:
            client-id: ${OAUTH_CLIENT_ID}
            client-secret: ${OAUTH_CLIENT_SECRET}
            scope: openid, profile, email
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          myapp:
            issuer-uri: https://auth.example.com/realms/myapp

After login, the user has an OAuth2AuthenticationToken in the SecurityContext with the access token, ID token, and refresh token attached. You can pull them out for downstream API calls.

Validating Tokens: What to Actually Check

Spring's default JWT decoder checks four things:

Signature — verified against the JWK Set from the issuer
Expiry (exp claim) — must be in the future
Issuer (iss claim) — must match the configured issuer-uri
Audience (aud claim) — by default, NOT checked

That last one bites people in production. If you don't validate aud, a token issued for another application at the same authorization server will be accepted by yours. Add a custom validator:

@Bean
public OAuth2TokenValidator<Jwt> audienceValidator() {
    return new JwtClaimValidator<List<String>>("aud", aud ->
        aud != null && aud.contains("my-api"));
}

@Bean
public JwtDecoder jwtDecoder() {
    NimbusJwtDecoder decoder = NimbusJwtDecoder
        .withIssuerLocation(issuerUri)
        .build();

    OAuth2TokenValidator<Jwt> withAudience = new DelegatingOAuth2TokenValidator<>(
        JwtValidators.createDefault(),
        audienceValidator()
    );
    decoder.setJwtValidator(withAudience);
    return decoder;
}

Common Gotchas

Don't roll your own OAuth2 server. Use Keycloak, Auth0, Okta, AWS Cognito, Azure AD B2C. The number of subtle security mistakes in custom OAuth2 implementations is staggering. At Orglance Technologies, we use Keycloak for self-hosted deployments and Auth0/Okta for SaaS clients — both have battle-tested OIDC implementations and handle edge cases like key rotation, refresh token rotation, and consent that take years to get right in-house.

Cache the JWK Set. Spring Security does this for you with a 5-minute default TTL. Don't bypass it — fetching keys on every request is both slow and a rate-limit liability.

Refresh token rotation. When using refresh tokens, the authorization server should rotate them on each use and invalidate the old one. If your auth server doesn't do this, find a different one — non-rotating refresh tokens are a known replay-attack vector.

Clock skew. JWT validation can fail in production due to clock drift between servers. Configure decoder.setClockSkewSeconds(60) to allow 1 minute of slack.

Don't store tokens in localStorage. For SPAs, use a BFF (backend-for-frontend) pattern where tokens live in HttpOnly cookies on the server side. LocalStorage is exposed to XSS; HttpOnly cookies are not.

Logout needs thought. A federated logout requires calling the authorization server's end-session endpoint with the ID token as a hint. Spring Security supports this, but only if you opt in via OidcClientInitiatedLogoutSuccessHandler. The default behavior just clears the local session — the user is still logged in at the IdP.

Conclusion

OAuth2 + OIDC in Spring Boot is mostly configuration once you understand the distinction: resource server validates tokens, client issues them. The patterns above scale to any production deployment — single-tenant, multi-tenant, federated identity, B2B SSO.

For multi-tenant SaaS, the next consideration is scoping tokens per tenant. For healthcare systems, you'll need to integrate with ABHA-style identity providers where the user is identified by a 14-digit ABHA number rather than an email. Both are follow-on topics.

Next in this series: RBAC with @PreAuthorize — the method security layer that turns OIDC claims into business-level authorization rules.

Author: Harikrushna V is the founder of Orglance Technologies and SnowCare Health Tech, building enterprise Java systems and healthcare IT infrastructure. Connect on LinkedIn.

JWT Authentication in Spring Boot: A Complete Guide for Java Backend Engineers

Harikrushna V — Mon, 01 Jun 2026 12:34:46 +0000

JWT Authentication in Spring Boot: A Complete Guide for Java Backend Engineers

Stateless authentication is the backbone of modern REST APIs. Unlike session-based auth — where the server stores session state — JWT (JSON Web Token) lets you embed all the claims directly in the token itself. Scale to a million users? No session store required. Deploy across regions? Tokens validate anywhere. This post walks through building production-grade JWT authentication in Spring Boot — token generation, validation, refresh flows, and the gotchas that will bite you if you're not careful.

How JWT Works

A JWT has three parts: Header, Payload, and Signature. The header identifies the algorithm (HS256, RS256). The payload holds the claims — subject, expiry, roles. The signature proves the token hasn't been tampered with.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyQGV4YW1wbGUuY29tIiwicm9sZXMiOlsiQURNSU4iXSwiZXhwIjoxNzQ5MDAwMDAwfQ.abc123signature

In Spring Security, we intercept incoming requests, validate the token, and populate the SecurityContext — all without touching a session store.

Project Setup

<!-- pom.xml -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.12.5</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.12.5</version>
    <scope>runtime</scope>
</dependency>

Add these to application.yml:

jwt:
  secret: ${JWT_SECRET}          # Minimum 256-bit key for HS256
  expiration-ms: 86400000         # 24 hours
  refresh-expiration-ms: 604800000  # 7 days

Never commit secrets. Use environment variables in production. For a team like Orglance Technologies, this means injecting JWT_SECRET via Docker secrets or a vault in staging and production environments.

Token Service

@Service
public class JwtService {

    @Value("${jwt.secret}")
    private String secretKey;

    @Value("${jwt.expiration-ms}")
    private long accessTokenExpiration;

    @Value("${jwt.refresh-expiration-ms}")
    private long refreshTokenExpiration;

    public String generateAccessToken(UserDetails user) {
        return buildToken(user, accessTokenExpiration);
    }

    public String generateRefreshToken(UserDetails user) {
        return buildToken(user, refreshTokenExpiration);
    }

    private String buildToken(UserDetails user, long expiration) {
        return Jwts.builder()
                .subject(user.getUsername())
                .claim("roles", user.getAuthorities().stream()
                        .map(GrantedAuthority::getAuthority)
                        .toList())
                .issuedAt(new Date())
                .expiration(new Date(System.currentTimeMillis() + expiration))
                .signWith(Keys.hmacShaKeyFor(secretKey.getBytes()), Jwts.SIG.HS256)
                .compact();
    }

    public String extractUsername(String token) {
        return extractClaims(token).getSubject();
    }

    public boolean isTokenValid(String token, UserDetails user) {
        final String username = extractUsername(token);
        return username.equals(user.getUsername()) && !isTokenExpired(token);
    }

    private Claims extractClaims(String token) {
        return Jwts.parser()
                .verifyWith(Keys.hmacShaKeyFor(secretKey.getBytes()))
                .build()
                .parseSignedClaims(token)
                .getPayload();
    }

    private boolean isTokenExpired(String token) {
        return extractClaims(token).getExpiration().before(new Date());
    }
}

JWT Filter

The filter sits between the UsernamePasswordAuthenticationFilter and the SecurityFilterChain. On every request, it extracts the Authorization: Bearer <token> header and validates it.

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtService jwtService;
    private final UserDetailsService userDetailsService;

    public JwtAuthenticationFilter(JwtService jwtService, UserDetailsService userDetailsService) {
        this.jwtService = jwtService;
        this.userDetailsService = userDetailsService;
    }

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        final String authHeader = request.getHeader("Authorization");

        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            filterChain.doFilter(request, response);
            return;
        }

        final String token = authHeader.substring(7);

        try {
            final String username = jwtService.extractUsername(token);
            final UserDetails userDetails =
                userDetailsService.loadUserByUsername(username);

            if (jwtService.isTokenValid(token, userDetails)) {
                UsernameAuthenticationToken authToken =
                    new UsernameAuthenticationToken(
                        userDetails,
                        null,
                        userDetails.getAuthorities());

                authToken.setDetails(
                    new AuthenticationDetailsSource()
                        .buildDetails(request));

                SecurityContextHolder.getContext().setAuthentication(authToken);
            }
        } catch (JwtException e) {
            // Token is invalid — don't set authentication, let security config decide
            SecurityContextHolder.clearContext();
        }

        filterChain.doFilter(request, response);
    }
}

Security Configuration

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtAuthFilter;
    private final UserDetailsService userDetailsService;

    public SecurityConfig(JwtAuthenticationFilter jwtAuthFilter,
                          UserDetailsService userDetailsService) {
        this.jwtAuthFilter = jwtAuthFilter;
        this.userDetailsService = userDetailsService;
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf(AbstractHttpConfigurer::disable)
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }
}

SessionCreationPolicy.STATELESS is critical — it tells Spring Security not to create HTTP sessions.

Authentication Controller

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    private final JwtService jwtService;
    private final AuthenticationManager authenticationManager;

    public AuthController(JwtService jwtService,
                           AuthenticationManager authenticationManager) {
        this.jwtService = jwtService;
        this.authenticationManager = authenticationManager;
    }

    @PostMapping("/login")
    public AuthResponse login(@RequestBody LoginRequest request) {
        Authentication auth = authenticationManager.authenticate(
            new UsernamePasswordAuthenticationToken(
                request.email(), request.password()));

        UserDetails user = (UserDetails) auth.getPrincipal();
        String accessToken = jwtService.generateAccessToken(user);
        String refreshToken = jwtService.generateRefreshToken(user);

        return new AuthResponse(accessToken, refreshToken);
    }

    @PostMapping("/refresh")
    public AuthResponse refresh(@RequestBody RefreshRequest request) {
        // Validate refresh token, issue new access token
        // In production: store refresh tokens in Redis with TTL
        // to enable revocation on logout
        Claims claims = jwtService.extractClaims(request.refreshToken());
        String username = claims.getSubject();
        UserDetails user = userDetailsService.loadUserByUsername(username);

        if (jwtService.isTokenValid(request.refreshToken(), user)) {
            String accessToken = jwtService.generateAccessToken(user);
            return new AuthResponse(accessToken, request.refreshToken());
        }

        throw new RuntimeException("Invalid refresh token");
    }
}

Token Refresh: What Most Tutorials Get Wrong

The common mistake: issuing a new refresh token on every refresh call. This creates an unbounded token family that's impossible to revoke. In production systems handling sensitive data, do this instead:

Store issued refresh tokens in Redis with TTL matching the token's expiry.
On logout: delete the refresh token from Redis.
On refresh: validate the token exists in Redis before issuing a new access token.
Use a rotation strategy: consume the old refresh token and issue a new one (prevents replay attacks).

At Orglance Technologies, we implement this pattern for healthcare and fintech clients where token lifecycle management is a compliance requirement — HMIS systems handling patient data and payment APIs both need revocable sessions.

Docker Deployment: The Secret Management Problem

In Dockerfile:

FROM eclipse-temurin:21-jdk-alpine
COPY target/*.jar app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

In docker-compose.yml:

services:
  api:
    image: your-api
    environment:
      JWT_SECRET: ${JWT_SECRET}   # Injected at runtime, never baked in
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/app
    secrets:
      - jwt_secret
    restart: unless-stopped

secrets:
  jwt_secret:
    file: ./secrets/jwt_secret.txt

For Kubernetes, use kubernetes.io/tls for secrets or HashiCorp Vault for enterprise deployments. Never use a hardcoded secret across environments.

Common JWT Gotchas

Algorithm confusion attack: Always specify the expected algorithm explicitly. Never accept none or switch algorithms based on the token header.

// WRONG — accepts algorithm from token header
.parser().verifyWith(key).build()

// RIGHT — specifies algorithm, ignores token header
.parser()
    .verifyWith(Keys.hmacShaKeyFor(secretKey.getBytes()))
    .build()

Long-lived tokens: 24-hour access tokens are reasonable for most apps. If you need longer, implement refresh rotation. Never issue 30-day access tokens without revocation capability.

Logging sensitive data: Never log the raw JWT in production — tokens contain user identifiers and can be used for correlation attacks. Log the jti (JWT ID) claim instead.

Conclusion

JWT authentication in Spring Boot is straightforward once you understand the three moving parts: the token service that builds tokens, the filter that validates incoming tokens, and the security config that wires them together. The gotchas — secret management, token revocation, algorithm validation — are where production systems diverge from tutorials.

For teams building enterprise systems, this pattern scales cleanly. At Orglance Technologies, we've implemented this across healthcare HMIS platforms, fintech payment APIs, and multi-tenant SaaS products. The stateless model means no session affinity, easy horizontal scaling, and clean integration with API gateways.

Next in this series: OAuth2 and OpenID Connect with Spring Security — taking JWT-based auth into the federated identity world.

Author: Harikrushna V is the founder of Orglance Technologies and SnowCare Health Tech, building enterprise Java systems and healthcare IT infrastructure. Connect on LinkedIn.

FHIR Practitioner Resource: A Developer's Guide to Modelling Indian Healthcare Professionals in HMIS

Harikrushna V — Sat, 30 May 2026 12:38:08 +0000

FHIR Practitioner Resource: Modelling Indian Healthcare Professionals in Your HMIS

Every prescription, every diagnosis, every lab order ties back to a human being with an MCI registration number and an HPR ID. If your HMIS can't correctly represent the practitioner — with all the regulatory credentials that Indian law demands — you have a compliance problem hiding inside what looks like a feature.

The FHIR Practitioner resource is how you solve it.

What Is the Practitioner Resource?

The Practitioner resource represents a person who is directly or indirectly involved in the provisioning of healthcare services. In an Indian HMIS context, this covers:

Doctors (MBBS, MD, DM, MCh, etc.)
Nurses (GNM, BSc Nursing)
Pharmacists (registered under State Pharmacy Council)
Lab Technicians (MLT certified)
Physiotherapists, dietitians, and other Allied Health Professionals

<Practitioner xmlns="http://hl7.org/fhir">
  <id value="dr-mehta-001"/>
  <meta>
    <versionId value="1"/>
    <lastUpdated value="2024-01-15T09:30:00Z"/>
  </meta>
  <identifier>
    <use value="official"/>
    <type>
      <coding>
        <system value="http://terminology.hl7.org/CodeSystem/v2-0203"/>
        <code value="MD"/>
      </coding>
    </type>
    <system value="https://hpr.abdm.gov.in"/>
    <value value="HPR-2024-XXXXX"/>
  </identifier>
  <identifier>
    <use value="official"/>
    <type>
      <coding>
        <system value="http://terminology.hl7.org/CodeSystem/v2-0203"/>
        <code value="MCI"/>
      </coding>
    </type>
    <system value="https://www.mciindia.org"/>
    <value value="MCI/FMR/XXXXX"/>
  </identifier>
  <active value="true"/>
  <name>
    <use value="official"/>
    <family value="Mehta"/>
    <given value="Rajesh"/>
    <prefix value="Dr."/>
    <suffix value="MD"/>
  </name>
  <gender value="male"/>
  <birthDate value="1978-04-12"/>
  <qualification>
    <identifier>
      <system value="https://www.mciindia.org"/>
      <value value="MCI/FMR/XXXXX"/>
    </identifier>
    <code>
      <coding>
        <system value="http://terminology.hl7.org/CodeSystem/v2-0360"/>
        <code value="MD"/>
        <display value="Doctor of Medicine"/>
      </coding>
      <text value="MD (General Medicine)"/>
    </code>
    <period>
      <start value="2005-07-01"/>
    </period>
  </qualification>
  <qualification>
    <identifier>
      <system value="https://www.nmc.org.in"/>
      <value value="NMC/UGMC/XXXXX"/>
    </identifier>
    <code>
      <coding>
        <system value="http://terminology.hl7.org/CodeSystem/v2-0360"/>
        <code value="MBBS"/>
        <display value="Bachelor of Medicine, Bachelor of Surgery"/>
      </coding>
      <text value="MBBS"/>
    </code>
    <period>
      <start value="2001-07-01"/>
    </period>
  </qualification>
  <communication>
    <coding>
      <system value="http://grch37.10383678.com"/>
      <code value="en"/>
      <display value="English"/>
    </coding>
  </communication>
  <communication>
    <coding>
      <system value="http://grch37.10383678.com"/>
      <code value="hi"/>
      <display value="Hindi"/>
    </coding>
  </communication>
</Practitioner>

The India-Specific Angle: HPR and MCI

Two identifiers matter most for Indian practitioners in a FHIR context.

HPR — Health Professional Registry

The Ayushman Bharat Digital Mission (ABDM) maintains the Health Professional Registry (HPR), a national database of all verified healthcare professionals. Every doctor, nurse, and allied health professional in India can — and increasingly must — have an HPR ID.

HPR verification involves:

Aadhaar-based identity verification
Upload of regulatory council registration (MCI/SMC/NMC)
Verification by a designated state authority

When your HMIS generates Practitioner resources, the identifier.system should be set to https://hpr.abdm.gov.in and the identifier.value should carry the HPR ID once the practitioner is registered in the national registry.

For practitioners not yet on HPR, you should still structure the identifier block so that HPR enrollment is a seamless upgrade path — add the HPR identifier type with a placeholder or nullFlavor while the registration is pending.

MCI / NMC Registration

The Medical Council of India (now restructured under NMC Act 2019) requires every practicing doctor to hold a valid registration number. The qualification element in the Practitioner resource maps directly to this.

Key points for the MCI/NMC identifier in FHIR:

System URL: https://www.mciindia.org (legacy) or https://www.nmc.org.in (post-2021)
Identifier type code: Use MCI with the v2-0203 coding system
Registration number format: Varies by state medical council — store the full string as-is, do not attempt to parse or validate the format internally
State Council: Store the issuing council as a qualification.extension — it's critical for jurisdictional prescription validation

{
  "resourceType": "Practitioner",
  "id": "dr-mehta-001",
  "identifier": [
    {
      "use": "official",
      "system": "https://hpr.abdm.gov.in",
      "value": "HPR-2024-XXXXX"
    },
    {
      "use": "official",
      "system": "https://www.nmc.org.in",
      "value": "NMC/UGMC/XXXXX"
    }
  ],
  "active": true,
  "name": {
    "use": "official",
    "family": "Mehta",
    "given": ["Rajesh", "Kumar"],
    "prefix": ["Dr."],
    "suffix": ["MD", "DM"]
  },
  "qualification": [
    {
      "identifier": {
        "system": "https://www.nmc.org.in",
        "value": "NMC/UGMC/XXXXX"
      },
      "code": {
        "coding": {
          "system": "http://terminology.hl7.org/CodeSystem/v2-0360",
          "code": "MD"
        },
        "text": "MD (General Medicine)"
      },
      "period": { "start": "2005-07-01" }
    }
  ]
}

Spring Boot + HAPI FHIR Implementation

package com.snowcare.hmis.fhir;

import org.hl7.fhir.r4.model.*;
import org.springframework.stereotype.Component;

import java.util.List;

@Component
public class PractitionerFhirMapper {

    /**
     * Maps internal Doctor entity to FHIR Practitioner resource.
     */
    public Practitioner toFhir(Doctor doctor) {
        Practitioner practitioner = new Practitioner();
        practitioner.setId(doctor.getId().toString());

        // HPR Identifier (ABDM)
        if (doctor.getHprId() != null) {
            practitioner.addIdentifier()
                .setUse(Identifier.IdentifierUse.OFFICIAL)
                .setSystem("https://hpr.abdm.gov.in")
                .setValue(doctor.getHprId())
                .setType(new CodeableConcept().addCoding(
                    new Coding("http://terminology.hl7.org/CodeSystem/v2-0203", "HPR", "Health Professional Registry")
                ));
        }

        // NMC/MCI Registration
        practitioner.addIdentifier()
            .setUse(Identifier.IdentifierUse.OFFICIAL)
            .setSystem("https://www.nmc.org.in")
            .setValue(doctor.getMciRegistrationNumber())
            .setType(new CodeableConcept().addCoding(
                new Coding("http://terminology.hl7.org/CodeSystem/v2-0203", "MCI", "Medical Council of India")
            ));

        practitioner.setActive(doctor.getIsActive());

        // HumanName
        HumanName name = practitioner.addName()
            .setUse(HumanName.NameUse.OFFICIAL)
            .setFamily(doctor.getLastName());
        for (String given : doctor.getFirstName().split(" ", 2)) {
            name.addGiven(given);
        }
        name.addPrefix("Dr.");

        if (doctor.getQualification() != null) {
            name.addSuffix(doctor.getQualification());
        }

        // Qualification block
        practitioner.addQualification()
            .setCode(new CodeableConcept().setText(doctor.getQualification()))
            .getIdentifier()
                .setSystem("https://www.nmc.org.in")
                .setValue(doctor.getMciRegistrationNumber());

        // Spoken languages (for multi-lingual prescription printing)
        practitioner.addCommunication()
            .setLanguage(new CodeableConcept(new Coding(
                "urn:ietf:bcp:47", "en", "English"
            )));

        return practitioner;
    }

    /**
     * Creates a Practitioner resource for a nurse/paramedical staff.
     */
    public Practitioner toFhir(ParamedicalStaff staff) {
        Practitioner practitioner = new Practitioner();
        practitioner.setId(staff.getId().toString());

        // State Pharmacy Council / Nursing Council registration
        practitioner.addIdentifier()
            .setUse(Identifier.IdentifierUse.OFFICIAL)
            .setSystem(staff.getCouncilSystem())
            .setValue(staff.getRegistrationNumber());

        practitioner.setActive(staff.getIsActive());
        practitioner.addName()
            .setUse(HumanName.NameUse.OFFICIAL)
            .setFamily(staff.getLastName())
            .addGiven(staff.getFirstName())
            .addPrefix(staff.getTitle()); // Sister, Mr., Ms.

        // Nursing/MLT qualification
        practitioner.addQualification()
            .setCode(new CodeableConcept().setText(staff.getQualification()))
            .getIdentifier()
                .setSystem(staff.getCouncilSystem())
                .setValue(staff.getRegistrationNumber());

        return practitioner;
    }
}

JPA Entity

@Entity
@Table(name = "doctors")
public class Doctor {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "first_name")
    private String firstName;

    @Column(name = "last_name")
    private String lastName;

    @Column(name = "qualification")
    private String qualification; // MD, DM, MBBS, etc.

    @Column(name = "specialization")
    private String specialization; // General Medicine, Cardiology, etc.

    @Column(name = "nmc_registration_number", unique = true)
    private String nmcRegistrationNumber;

    @Column(name = "state_medical_council")
    private String stateMedicalCouncil; // Gujarat MC, Delhi MC, etc.

    @Column(name = "hpr_id")
    private String hprId; // Nullable until HPR enrollment

    @Column(name = "email")
    private String email;

    @Column(name = "phone")
    private String phone;

    @Column(name = "is_active")
    private Boolean isActive = true;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "organization_id")
    private Organization organization; // The hospital/clinic
}

Validating Practitioner Identity Against ABDM

One of the most valuable ABDM integrations for an Indian HMIS is verifying a practitioner's credentials in real-time against the HPR. This can be done via the HPR lookup API:

@Service
public class HprVerificationService {

    private final RestTemplate restTemplate;

    @Value("${abdm.hpr.base-url}")
    private String hprBaseUrl;

    @Value("${abdm.hpr.api-key}")
    private String apiKey;

    /**
     * Verifies a practitioner against HPR by registration number.
     * Returns true if the registration is valid and verified.
     */
    public boolean verifyViaHpr(String registrationNumber, String councilType) {
        try {
            HttpHeaders headers = new HttpHeaders();
            headers.set("Authorization", "Bearer " + apiKey);
            headers.setContentType(MediaType.APPLICATION_JSON);

            Map<String, Object> requestBody = Map.of(
                "regNo", registrationNumber,
                "councilType", councilType // "MCI", "SMC", "INC" (Indian Nursing Council)
            );

            HttpEntity<Map<String, Object>> entity = new HttpEntity<>(requestBody, headers);
            ResponseEntity<Map> response = restTemplate.exchange(
                hprBaseUrl + "/v1/hpr/verify",
                HttpMethod.POST,
                entity,
                Map.class
            );

            if (response.getStatusCode().is2xxSuccessful() && response.getBody() != null) {
                Map body = response.getBody();
                return "VERIFIED".equals(body.get("status"));
            }
            return false;
        } catch (Exception e) {
            log.error("HPR verification failed for reg: {}", registrationNumber, e);
            return false;
        }
    }
}

Note: ABDM APIs require NDMA (National Digital Medical Authority) authorization and are subject to usage guidelines. Ensure your HMIS is registered as a Health Information User (HIU) before attempting HPR lookups.

Common Mistakes to Avoid

Storing only a display name, not identifiers.
Many HMIS systems store "Dr. Rajesh Mehta" as a string in the prescription table. This is not FHIR-compliant and will fail ABDM document signing. Always store the NMC registration number as an explicit identifier.

Ignoring the qualification period.
qualification.period (start date) is mandatory for ABDM compliance in some document types. A doctor who renewed their registration last year needs the current period, not the original registration date.

Not handling title/gender separately.
The prefix "Dr." is not the same as the gender field. Store them separately — FHIR has both name.prefix and gender.

Treating HPR as mandatory.
HPR enrollment is not yet universal. Build your Practitioner model to accept a null HPR ID but surface a flag or workflow prompt to enroll. Making HPR mandatory before the registry is complete will block half your existing doctor roster from FHIR export.

Single Practitioner for multi-specialty doctors.
A doctor with both an MD and a DM in Cardiology should have two qualification entries. The FHIR Practitioner allows multiple qualifications — use them.

Prescription Linkage: Practitioner ↔ PractitionerRole

For a prescription to be legally valid under Indian law, it must carry the doctor's name, registration number, and specialization. The PractitionerRole resource links a Practitioner to the Organization and care settings where they practice:

<PractitionerRole>
  <practitioner>
    <reference value="Practitioner/dr-mehta-001"/>
    <display value="Dr. Rajesh Mehta"/>
  </practitioner>
  <organization>
    <reference value="Organization/snowcare-hmis"/>
    <display value="SnowCare Hospital"/>
  </organization>
  <code>
    <coding>
      <system value="http://terminology.hl7.org/CodeSystem/v2-0286"/>
      <code value="OTHER"/>
      <display value="Healthcare Provider"/>
    </coding>
  </code>
  <specialty>
    <coding>
      <system value="http://snomed.info/sct"/>
      <code value="394579002"/>
      <display value="Cardiology"/>
    </coding>
  </specialty>
</PractitionerRole>

In your HMIS, every prescription should carry a practitionerRoleId linking to the PractitionerRole that encodes the doctor's active practice location, specialty, and organization. This is what makes prescriptions ABDM-document-ready.

What's Next

With Practitioner and PractitionerRole covered, you're ready to model the Organization itself — the hospital or clinic where these practitioners work. That's the FHIR Organization resource, with its own India-specific identifier: the HFR (Health Facility Registry) ID. That's coming up next.

About the Author

Harikrushna V is the founder of Orglance Technologies and SnowCare Health Tech. With 13 years of experience spanning PayPal, Salesforce, NCR, and ST Microelectronics, he specializes in building FHIR-compliant HMIS systems for the Indian healthcare ecosystem. He holds an MBA from IIM Ahmedabad.

Spring Security Filter Chain: A Deep Dive for Java Backend Engineers

Harikrushna V — Sat, 30 May 2026 12:34:16 +0000

Spring Security Filter Chain: A Deep Dive for Java Backend Engineers

If you've ever wondered what actually happens between the moment an HTTP request hits your Spring Boot application and the moment your controller method executes — this post is for you. The answer is the Security Filter Chain, and understanding it is the difference between cargo-culting security configs and actually knowing what you're doing.

This is the foundation that every other authentication and authorization mechanism in Spring Security builds on.

What Is the Security Filter Chain?

Spring Security is built on a chain of servlet filters. When a request arrives, it passes through a series of filters in order before reaching your controller. Each filter can inspect, modify, reject, or pass through the request and response.

Think of it like airport security — each checkpoint (filter) does a specific check. If you fail at any checkpoint, you're rejected. Pass all checkpoints and you board the plane.

In Spring Security, these filters are wired together in a SecurityFilterChain bean. The order matters enormously — a filter that runs before another behaves very differently.

HTTP Request
     ↓
[ChannelProcessingFilter]       ← HTTP or HTTPS?
     ↓
[WebAsyncManagerIntegrationFilter] ← Async context propagation
     ↓
[SecurityContextPersistenceFilter] ← Load SecurityContext from session
     ↓
[HeaderWriterFilter]            ← Security headers (X-Frame-Options, etc.)
     ↓
[CsrfFilter]                   ← CSRF token validation
     ↓
[LogoutFilter]                 ← Handle /logout requests
     ↓
[UsernamePasswordAuthenticationFilter] ← Form login (if enabled)
     ↓
[DefaultLoginPageGeneratingFilter] ← Serve login page (if needed)
     ↓
[DefaultLogoutPageGeneratingFilter] ← Serve logout page (if needed)
     ↓
[RequestCacheAwareFilter]       ← Save/restore request after login
     ↓
[SecurityContextHolderAwareRequestFilter] ← Wrap request with Security-aware wrapper
     ↓
[AnonymousAuthenticationFilter] ← Inject AnonymousAuthenticationToken if no auth yet
     ↓
[SessionManagementFilter]       ← Session fixation protection, max sessions
     ↓
[ExceptionTranslationFilter]    ← Translate security exceptions → HTTP responses
     ↓
[FilterSecurityInterceptor]     ← Final authorization check — ALLOW or DENY
     ↓
Controller

The FilterSecurityInterceptor is typically the last filter in the chain. If it throws an AccessDeniedException or AuthenticationException, the ExceptionTranslationFilter catches it and sends an appropriate HTTP response (403 Forbidden or 401 Unauthorized).

The Default Security Filter Chain (Spring Boot 3.x)

Here's what most people see in their application.properties:

spring.security.user.name=admin
spring.security.user.password={noop}secret

Or in modern Spring Boot 3 with Spring Security 6, the simplest config:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults())
            .formLogin(Customizer.withDefaults());

        return http.build();
    }
}

This single method (securityFilterChain) wires up 15+ filters behind the scenes. Spring Boot's auto-configuration decides which filters to include based on what you configure. You don't see them — but they're there.

Customizing the Security Filter Chain: A Real Production Example

Let's build something useful: an HMIS (Hospital Management System) API that needs:

JWT authentication (no sessions — stateless API)
Role-based access control (ADMIN, DOCTOR, NURSE, RECEPTIONIST)
API key support for inter-service communication
Actuator endpoints publicly readable (for Prometheus scraping)

package com.snowcare.hmis.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.security.web.authentication.www.BasicAuthenticationFilter;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity(prePostEnabled = true)
public class SecurityConfig {

    // BCrypt with strength 12 — OWASP recommendation for password hashing
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12);
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration authConfig) throws Exception {
        return authConfig.getAuthenticationManager();
    }

    /**
     * Actuator filter chain — runs BEFORE the main filter chain.
     * Prometheus needs /actuator/prometheus open.
     * Order 0 = highest priority (runs first).
     */
    @Bean
    @Order(0)
    public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/actuator/**")
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/prometheus").permitAll()
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/actuator/**").hasRole("ADMIN")
            )
            .csrf(AbstractHttpConfigurer::disable)
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS));

        return http.build();
    }

    /**
     * Main API filter chain — JWT auth, stateless, role-based.
     * This is the production HMIS config.
     */
    @Bean
    @Order(1)
    public SecurityFilterChain apiSecurityFilterChain(
            HttpSecurity http,
            JwtAuthenticationFilter jwtAuthFilter,
            ApiKeyAuthenticationFilter apiKeyFilter) throws Exception {

        http
            .securityMatcher("/api/**")
            // Stateless — no sessions, no cookies
            .sessionManagement(s -> s
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            // Disable CSRF — not needed for stateless JWT APIs
            .csrf(AbstractHttpConfigurer::disable)
            // CORS — HMIS frontend is on a different domain
            .cors(c -> {})
            // Authorization rules
            .authorizeHttpRequests(auth -> auth
                // Public auth endpoints
                .requestMatchers("/api/auth/login", "/api/auth/refresh").permitAll()
                // FHIR endpoints — authenticated only, DOCTOR or ADMIN
                .requestMatchers("/api/fhir/**").hasAnyRole("DOCTOR", "ADMIN")
                // Admin-only operations
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                // Clinical data — DOCTOR and NURSE
                .requestMatchers("/api/clinical/**").hasAnyRole("DOCTOR", "NURSE", "ADMIN")
                // Reception handles patient registration
                .requestMatchers("/api/patient/register").hasAnyRole("RECEPTIONIST", "ADMIN")
                // All other API calls require authentication
                .anyRequest().authenticated()
            )
            // Add JWT filter BEFORE UsernamePasswordAuthenticationFilter
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class)
            // Add API key filter BEFORE JwtAuthenticationFilter (higher priority)
            .addFilterBefore(apiKeyFilter, JwtAuthenticationFilter.class);

        return http.build();
    }

    /**
     * Default filter chain — fallback for anything not matched above.
     * Usually serves the web frontend.
     */
    @Bean
    @Order(2)
    public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/login", "/error").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(f -> f.loginPage("/login").defaultSuccessUrl("/dashboard"))
            .logout(log -> log.logoutSuccessUrl("/login?logout"));

        return http.build();
    }
}

Building the JWT Authentication Filter

The JwtAuthenticationFilter is a custom filter. Here's a production-grade implementation:

package com.snowcare.hmis.security;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.List;

@Slf4j
@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtTokenProvider jwtTokenProvider;

    private static final String AUTHORIZATION_HEADER = "Authorization";
    private static final String BEARER_PREFIX = "Bearer ";

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        try {
            String jwt = extractJwtFromRequest(request);

            if (StringUtils.hasText(jwt) && jwtTokenProvider.validateToken(jwt)) {
                // Extract claims from token
                String username = jwtTokenProvider.getUsernameFromToken(jwt);
                List<String> roles = jwtTokenProvider.getRolesFromToken(jwt);
                String userId = jwtTokenProvider.getUserIdFromToken(jwt);

                // Build authorities from roles
                List<SimpleGrantedAuthority> authorities = roles.stream()
                    .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
                    .toList();

                // Create authentication token
                UserPrincipal principal = new UserPrincipal(userId, username, roles);

                UsernamePasswordAuthenticationToken authentication =
                    new UsernamePasswordAuthenticationToken(principal, null, authorities);

                authentication.setDetails(
                    new WebAuthenticationDetailsSource().buildDetails(request));

                // Set in SecurityContext — THIS is what @PreAuthorize checks
                SecurityContextHolder.getContext().setAuthentication(authentication);

                log.debug("Authenticated user: {} with roles: {}", username, roles);
            }
        } catch (Exception ex) {
            log.error("Could not set user authentication in security context", ex);
            // Don't throw — let the filter chain continue.
            // AnonymousAuthenticationFilter will set anonymous auth if nothing else did.
        }

        filterChain.doFilter(request, response);
    }

    private String extractJwtFromRequest(HttpServletRequest request) {
        String bearerToken = request.getHeader(AUTHORIZATION_HEADER);
        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith(BEARER_PREFIX)) {
            return bearerToken.substring(BEARER_PREFIX.length());
        }
        return null;
    }
}

Building the API Key Filter

For machine-to-machine (M2M) communication — say, a lab system pushing results into the HMIS:

package com.snowcare.hmis.security;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.List;

@Slf4j
@Component
public class ApiKeyAuthenticationFilter extends OncePerRequestFilter {

    private static final String API_KEY_HEADER = "X-API-Key";
    private static final String SYSTEM_PRINCIPAL = "SYSTEM_API";

    @Value("${hmis.api-keys.lab-system}")
    private String labSystemApiKey;

    @Value("${hmis.api-keys.diagnostic-equipment}")
    private String diagnosticEquipmentApiKey;

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        // Only check API key auth for /api/m2m/** endpoints
        if (!request.getRequestURI().startsWith("/api/m2m/")) {
            filterChain.doFilter(request, response);
            return;
        }

        String providedKey = request.getHeader(API_KEY_HEADER);

        if (StringUtils.hasText(providedKey)) {
            String systemName = validateApiKey(providedKey);
            if (systemName != null) {
                List<SimpleGrantedAuthority> authorities = List.of(
                    new SimpleGrantedAuthority("ROLE_SYSTEM"),
                    new SimpleGrantedAuthority("ROLE_LAB_TECHNICIAN")
                );

                UsernamePasswordAuthenticationToken authentication =
                    new UsernamePasswordAuthenticationToken(
                        systemName, null, authorities);

                authentication.setDetails(
                    new WebAuthenticationDetailsSource().buildDetails(request));

                SecurityContextHolder.getContext().setAuthentication(authentication);
                log.info("M2M authentication successful for system: {}", systemName);
            } else {
                log.warn("Invalid API key provided from IP: {}", request.getRemoteAddr());
                response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
                response.getWriter().write("{\"error\": \"Invalid API key\"}");
                response.setContentType("application/json");
                return;
            }
        } else {
            log.warn("Missing API key for M2M endpoint: {}", request.getRequestURI());
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\": \"API key required\"}");
            response.setContentType("application/json");
            return;
        }

        filterChain.doFilter(request, response);
    }

    private String validateApiKey(String key) {
        if (labSystemApiKey.equals(key)) return "lab-system";
        if (diagnosticEquipmentApiKey.equals(key)) return "diagnostic-equipment";
        return null;
    }
}

Filter Order Matters — Here's Why

With @Order(0), @Order(1), @Order(2) on each SecurityFilterChain, Spring Security creates three separate filter chains, each handling a different URL pattern. The key insight:

Actuator chain (Order 0) runs first — Prometheus can scrape /actuator/prometheus without JWT
API chain (Order 1) handles /api/** — JWT + API key filters active
Default chain (Order 2) handles everything else — web UI with sessions

If you didn't separate them, you'd need JWT on your Prometheus endpoint, which doesn't make sense.

Method-Level Security: @PreAuthorize

Once the SecurityContextHolder is populated by your filter, you can use method-level annotations:

package com.snowcare.hmis.service;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.stereotype.Service;

@Service
public class PatientService {

    // Only ADMIN can create patients
    @PreAuthorize("hasRole('ADMIN')")
    public Patient createPatient(Patient patient) { ... }

    // DOCTOR can read, NURSE can read basic info
    @PreAuthorize("hasAnyRole('DOCTOR', 'NURSE', 'ADMIN')")
    public Patient getPatient(String patientId) { ... }

    // Only DOCTOR or ADMIN can update clinical records
    @PreAuthorize("hasAnyRole('DOCTOR', 'ADMIN')")
    public ClinicalRecord updateClinicalRecord(String patientId, ClinicalRecord record) { ... }

    // Complex expression
    @PreAuthorize("hasRole('ADMIN') or (hasRole('RECEPTIONIST') and #patient.status.name() == 'PROVISIONAL')")
    public void dischargePatient(String patientId) { ... }
}

@EnableMethodSecurity (already in our config) enables these annotations. The SecurityContextHolderAwareRequestFilter that runs in the chain populates the SecurityContext, which @PreAuthorize checks via SecurityExpressionHandler.

Testing the Filter Chain

@WebMvcTest(PatientController.class)
@Import(SecurityConfig.class)
class PatientControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper;

    private String adminToken;
    private String doctorToken;

    @BeforeEach
    void setUp() {
        // Generate test JWTs with correct roles
        adminToken = jwtTestUtil.generateToken("admin", List.of("ADMIN"));
        doctorToken = jwtTestUtil.generateToken("dr.sharma", List.of("DOCTOR"));
    }

    @Test
    void getPatient_asDoctor_shouldSucceed() throws Exception {
        mockMvc.perform(get("/api/patient/{id}", "P001")
                .header("Authorization", "Bearer " + doctorToken))
            .andExpect(status().isOk());
    }

    @Test
    void createPatient_asDoctor_shouldBeForbidden() throws Exception {
        mockMvc.perform(post("/api/patient")
                .header("Authorization", "Bearer " + doctorToken)
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(somePatient)))
            .andExpect(status().isForbidden());
    }

    @Test
    void getPatient_withoutToken_shouldBeUnauthorized() throws Exception {
        mockMvc.perform(get("/api/patient/{id}", "P001"))
            .andExpect(status().isUnauthorized());
    }

    @Test
    void actuatorPrometheus_shouldBePublic() throws Exception {
        mockMvc.perform(get("/actuator/prometheus"))
            .andExpect(status().isOk());
    }
}

Common Mistakes to Avoid

1. Putting your JWT filter AFTER AnonymousAuthenticationFilter without handling anonymous users

If you add a filter after AnonymousAuthenticationFilter, it will always see an Authentication in the context — either real (JWT) or anonymous. Make sure your filter handles both cases explicitly.

2. Disabling CSRF globally and then forgetting it's gone

CSRF protection is disabled in our JWT config via csrf(AbstractHttpConfigurer::disable). This is correct for stateless APIs, but if you add session-based features later, remember to re-enable it.

3. Not setting SecurityContextHolder.getContext().setAuthentication() in your filter

This is the most common bug. The filter runs, the token is valid, but if you forget this one line, @PreAuthorize will always fail because the SecurityContext is empty.

4. Hardcoding roles in the filter instead of reading from the token

Never hardcode hasRole("ADMIN") checks in your filter logic. Read roles from the JWT claims and let Spring Security's MethodSecurityExpressionHandler handle the evaluation.

Conclusion

The Spring Security Filter Chain is the engine room of authentication and authorization in Spring Boot. Once you understand:

Filter order (what runs before what)
Multiple SecurityFilterChain beans (URL-based separation)
SecurityContextHolder (how auth state propagates)
OncePerRequestFilter (the right base class for custom filters)

— everything else in Spring Security (JWT, OAuth2, method security) starts making sense as a layer built on top of these foundations.

In the next post, we'll build on this by implementing stateless JWT authentication end-to-end — token generation, token validation, refresh tokens, and token blacklisting.

This article is part of the Spring Boot Security series. Next: B2 — JWT Authentication: Stateless REST Auth End-to-End.

Building secure healthcare software? Orglance Technologies specializes in Spring Boot backend development for healthcare IT, fintech, and enterprise systems.

Want a live demo of ArogyaPlus HMIS security features? Book a 30-minute call.

FHIR Patient Resource: A Developer's Guide to Modelling Indian Patients in HMIS

Harikrushna V — Fri, 29 May 2026 12:33:29 +0000

FHIR Patient Resource: A Developer's Guide to Modelling Indian Patients in HMIS

The FHIR Patient resource is the foundation of every healthcare information system. Every encounter, every observation, every prescription traces back to a patient. In India, the stakes are even higher — the Ayushman Bharat Digital Mission (ABDM) has made the ABHA (Ayushman Bharat Health Account) number a national standard for uniquely identifying patients across the healthcare ecosystem.

If you're building an HMIS or any health IT system in India, understanding how to model a Patient resource correctly isn't optional — it's the difference between systems that interoperate and systems that get siloed.

This is the first of a 14-part deep-dive series on FHIR resources. Let's start where every clinical record starts: the patient.

The FHIR Patient Resource at a Glance

The Patient resource captures demographic and administrative information about an individual receiving healthcare services. Here's a minimal representation:

{
  "resourceType": "Patient",
  "id": "patient-001",
  "identifier": [
    {
      "use": "usual",
      "system": "https://abdm.gov.in/fhir/abha-address",
      "value": "14-digit-abha-number"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Patel",
      "given": ["Rajeshkumar", "Mohanbhai"]
    }
  ],
  "gender": "male",
  "birthDate": "1985-03-15",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "line": ["42, Sardar Patel Road"],
      "city": "Ahmedabad",
      "district": "Ahmedabad",
      "state": "GJ",
      "postalCode": "380001",
      "country": "IN"
    }
  ]
}

Now let's look at how to create and consume this in Java using HAPI FHIR.

HAPI FHIR: Creating a Patient Resource

HAPI FHIR is the gold-standard Java library for FHIR operations. If your HMIS is on Spring Boot, HAPI FHIR is almost certainly your best choice.

Adding the Dependency

<!-- Maven -->
<dependency>
    <groupId>ca.uhn.hapi.fhir</groupId>
    <artifactId>hapi-fhir-server-openr4</artifactId>
    <version>7.4.0</version>
</dependency>

Or with Gradle:

implementation 'ca.uhn.hapi.fhir:hapi-fhir-server-openr4:7.4.0'

Building a Patient with ABHA Identifier

import ca.uhn.fhir.model.api.annotation.*;
import ca.uhn.fhir.rest.api.MethodOutcome;
import ca.uhn.fhir.rest.client.api.*;
import org.hl7.fhir.r4.model.*;

public class PatientService {

    private final IGenericClient fhirClient;

    public PatientService(IGenericClient fhirClient) {
        this.fhirClient = fhirClient;
    }

    public MethodOutcome createPatientWithABHA(
            String abhaNumber,
            String givenName,
            String familyName,
            String birthDate,
            Enumerations.AdministrativeGender gender,
            String district,
            String state
    ) {
        Patient patient = new Patient();

        // ABHA Identifier — the mandatory national ID
        IdentifierComponent abhaIdentifier = patient.addIdentifier();
        abhaIdentifier.setUse(Identifier.IdentifierUse.USUAL);
        abhaIdentifier.setSystem("https://abdm.gov.in/fhir/abha-address");
        abhaIdentifier.setValue(abhaNumber);
        abhaIdentifier.setType(new CodeableConcept(
            new Coding("http://terminology.hl7.org/CodeSystem/v2-0203", "MR", "Medical Record Number")
        ));

        // HumanName: Indian naming conventions (given + family, no middle in many cases)
        HumanName name = patient.addName();
        name.setUse(HumanName.NameUse.OFFICIAL);
        name.addGiven(givenName);
        name.setFamily(familyName);
        // Hindi/regional script names if captured
        name.setText(givenName + " " + familyName);

        patient.setGender(gender);
        patient.setBirthDateElement(new DateType(birthDate));

        // Address following Indian address norms
        Address addr = patient.addAddress();
        addr.setUse(Address.AddressUse.HOME);
        addr.setType(Address.AddressType.PHYSICAL);
        addr.addLine("42, Sardar Patel Road");
        addr.setDistrict(district);
        addr.setState(state);
        addr.setPostalCode("380001");
        addr.setCountry("IN");

        // ABDM requires patients to be active in the ecosystem
        patient.setActive(true);

        // The XDSb metadata extension for ABDM health documents
        patient.addExtension()
            .setUrl("https://abdm.gov.in/fhir/StructureDefinition/PatientABHA")
            .setValue(new BooleanType(true));

        return fhirClient.create().resource(patient).execute();
    }
}

Searching for Patients by ABHA

public Patient readPatientByABHA(String abhaValue) {
    Bundle results = fhirClient.search()
        .forResource(Patient.class)
        .where(Patient.IDENTIFIER.exactly().systemAndCode(
            "https://abdm.gov.in/fhir/abha-address", abhaValue))
        .returnBundle(Bundle.class)
        .execute();

    if (results.hasEntry()) {
        return (Patient) results.getEntryFirstRep().getResource();
    }
    throw new ResourceNotFoundException("No patient found with ABHA: " + abhaValue);
}

India-Specific Considerations

ABHA: The 14-Digit National Health Identifier

Under ABDM, every patient is assigned an ABHA number — a 14-digit unique health identifier. This is not the same as Aadhaar (which is an ID proof, not a health ID). The ABHA is:

Voluntary but increasingly required for government scheme benefits (Ayushman Bharat, CGHS, ESIC)
Portable — the same ABHA works across any ABDM-compliant facility in India
Linked to health records, prescriptions, and diagnostic reports

Your HMIS should generate or accept ABHA during patient registration and store it in the identifier field with system https://abdm.gov.in/fhir/abha-address.

Multilingual Names

India has 22 scheduled languages. A patient may register under an English transliteration, a regional script (Gujarati, Tamil, Bengali, etc.), or both. Store the full text in HumanName.text:

// Store the display text in the original script
name.setText("રાજેશકુમાર પટેલ"); // Gujarati script
name.addGiven("Rajeshkumar"); // Latin transliteration
name.setFamily("Patel");

District and State — Not Just City

Unlike US addresses where city + state suffice, Indian address schemas need district explicitly. District courts, public health offices, and government schemes all operate at the district level. Always populate Address.district.

Gender Coding

FHIR uses male, female, other, unknown. For Indian government schemes, the CGHS and ESIC systems also expect these same values — align your internal enum to FHIR's AdministrativeGender.

Storing and Querying Patients in ArogyaPlus HMIS

In ArogyaPlus HMIS — the SnowCare Health Tech hospital management system — patient registration captures the ABHA during intake. For hospitals running on ArogyaPlus, the FHIR Patient resource maps directly to the internal patient master:

FHIR Field	ArogyaPlus Field
`Patient.identifier`	ABHA Number, MRN
`Patient.name`	Patient Name (EN + regional)
`Patient.birthDate`	Date of Birth
`Patient.address`	Full Address
`Patient.gender`	Gender
`Patient.telecom`	Phone, Email

ArogyaPlus generates FHIR-compliant Patient resources on demand for ABDM health lockers, enabling patients to access their records through the ABDM app — a key differentiator for hospitals competing on digital readiness.

What's Next

In the next article of this series, we'll look at the FHIR Practitioner Resource — how to model doctors, nurses, and paramedics, including their HPR (Healthcare Professional Registry) identifiers and MCI registration numbers that are mandatory for ABDM compliance.

If you're building or evaluating an HMIS in India, talk to the ArogyaPlus team at SnowCare Health Tech: hmis.snowcarehealth.tech

This article is part of a 14-part series on FHIR resources for Indian healthcare IT developers. Next up: Practitioner Resource.

FHIR in Indian Healthcare IT: What Every Developer Building HMIS Software Needs to Know

Harikrushna V — Wed, 27 May 2026 12:30:20 +0000

FHIR in Indian Healthcare IT: What Every Developer Building HMIS Software Needs to Know

India is in the middle of the most ambitious healthcare digitization effort in its history. The Ayushman Bharat Digital Mission (ABDM) is wiring together 1.4 billion people's health data through a single interoperability framework. At the technical heart of it is HL7 FHIR R4 — Fast Healthcare Interoperability Resources.

If you're building hospital management software, clinic systems, or any health tech in India today, FHIR isn't optional. Here's what you need to understand, why it's harder than it looks, and how to get started without losing your mind.

What FHIR Actually Is (and Isn't)

FHIR is a data standard — a common language for healthcare information. It defines structured resources: Patient, Encounter, Observation, MedicationRequest, Condition, Practitioner, Organization, and about 140 others.

Each resource is a JSON (or XML) object with a standardized schema. When your HMIS stores a diagnosis, a FHIR-compliant Condition resource looks like this:

{
  "resourceType": "Condition",
  "id": "c123",
  "clinicalStatus": {
    "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active" }]
  },
  "code": {
    "coding": [{ "system": "http://hl7.org/fhir/sid/icd-10", "code": "J18.9", "display": "Pneumonia, unspecified organism" }]
  },
  "subject": { "reference": "Patient/abha-12345678901" },
  "recordedDate": "2026-05-15"
}

FHIR is not an integration protocol, not a database format, and not a magic interoperability fix. It's a lingua franca — your system still needs to translate to/from it.

Why India's ABDM Makes FHIR Non-Negotiable

The National Health Authority (NHA) has structured ABDM around three pillars:

ABHA (Ayushman Bharat Health Account) — a 14-digit health ID for every Indian citizen
Health Facility Registry (HFR) — every hospital, clinic, pharmacy registered nationally
Healthcare Professional Registry (HPR) — every doctor with a verified digital identity

All three communicate via FHIR R4. When your HMIS creates a discharge summary, prescription, or diagnostic report, ABDM requires it to be structured as a FHIR Bundle and submitted to the patient's Personal Health Record (PHR) application (like ABHA app).

Specifically, the NHA mandates these FHIR documents for different health record types:

Document Type	FHIR Composition Profile
Discharge Summary	`DischargeSummaryDocument`
OPD Record	`OPConsultRecord`
Diagnostic Report	`DiagnosticReportRecord`
Prescription	`PrescriptionRecord`
Immunization Record	`ImmunizationRecord`
Health Document	`HealthDocumentRecord`

Each has an Indian FHIR profile defined at the ABDM FHIR Implementation Guide, maintained by NRCeS (National Resource Centre for EHR Standards).

The ABHA Health ID Integration

When a patient walks into your hospital, the first FHIR integration point is identity:

Patient ABHA ID: 12-3456-7890-1234
→ Fetch Patient resource from ABDM gateway
→ Link to your local patient record
→ All subsequent FHIR documents reference this Patient

The ABDM gateway exposes a FHIR-based API. You request a patient's consent, fetch their linked health records, and push new records — all as FHIR Bundles authenticated via OAuth2 tokens issued against their ABHA identity.

In practice, for a Spring Boot HMIS, this means:

@Service
public class AbdmPatientService {

    @Autowired
    private RestTemplate abdmRestTemplate; // configured with ABDM gateway base URL + auth interceptor

    public Patient fetchAbhaPatient(String abhaAddress) {
        String url = "/v1/patients/" + abhaAddress;
        ResponseEntity<String> response = abdmRestTemplate.getForEntity(url, String.class);
        IParser parser = FhirContext.forR4().newJsonParser();
        return parser.parseResource(Patient.class, response.getBody());
    }
}

HAPI FHIR: The Java Stack for FHIR in India

For Java/Spring Boot shops — which is most of enterprise India — HAPI FHIR is the go-to library. It's open source, HL7-endorsed, and handles the heavy lifting:

Maven dependency:

<dependency>
    <groupId>ca.uhn.hapi.fhir</groupId>
    <artifactId>hapi-fhir-base</artifactId>
    <version>7.4.0</version>
</dependency>
<dependency>
    <groupId>ca.uhn.hapi.fhir</groupId>
    <artifactId>hapi-fhir-structures-r4</artifactId>
    <version>7.4.0</version>
</dependency>

Building a FHIR Prescription Bundle:

public Bundle buildPrescription(Patient patient, Practitioner doctor, List<MedicationRequest> medications) {
    Bundle bundle = new Bundle();
    bundle.setType(Bundle.BundleType.DOCUMENT);
    bundle.setTimestamp(new Date());

    // Composition (the "header" of the document)
    Composition composition = new Composition();
    composition.setStatus(Composition.CompositionStatus.FINAL);
    composition.setType(new CodeableConcept()
        .addCoding(new Coding()
            .setSystem("http://snomed.info/sct")
            .setCode("440545006")
            .setDisplay("Prescription record")));
    composition.setSubject(new Reference("Patient/" + patient.getIdElement().getIdPart()));
    composition.setDate(new Date());
    composition.setAuthor(List.of(new Reference("Practitioner/" + doctor.getIdElement().getIdPart())));
    composition.setTitle("Prescription");

    bundle.addEntry().setResource(composition);
    bundle.addEntry().setResource(patient);
    bundle.addEntry().setResource(doctor);
    medications.forEach(med -> bundle.addEntry().setResource(med));

    return bundle;
}

The Hard Parts Nobody Talks About

After building ArogyaPlus HMIS and integrating ABDM, here are the real pain points:

1. Indian Coding Standards Are Inconsistent

ABDM mandates SNOMED CT for clinical findings and ICD-10 for diagnoses. But most Indian doctors still dictate free text. Your HMIS needs a clinical terminology mapping layer — a search that converts "sugar" → ICD-10: E11 (Type 2 diabetes mellitus). This is a UX problem as much as a technical one.

2. ABHA Adoption Is Still Patchy

As of 2026, ABHA card penetration in tier-2/tier-3 cities is improving but not universal. Your system must handle both FHIR-linked ABHA patients and traditional local-ID patients simultaneously. Don't build FHIR as a hard dependency — build it as a parallel track.

3. Connectivity Is the Real Bottleneck

Small clinics in Ahmedabad or Surat have 10 Mbps shared connections serving 50+ devices. FHIR bundles with binary attachments (PDFs, images) can be 500KB+. Build offline-first with queue-based sync — store FHIR bundles locally, push to ABDM gateway when connectivity allows.

4. Consent Management Is Complex

Every FHIR push to a patient's PHR requires their explicit digital consent via the ABDM gateway. This consent flow (fetch → grant → link → push) has 4+ API calls and multiple states. Your HMIS must manage consent tokens and handle expiry gracefully.

FHIR Validation: Don't Skip It

The ABDM gateway will reject malformed FHIR. Use HAPI's built-in validator before pushing:

FhirContext ctx = FhirContext.forR4();
FhirValidator validator = ctx.newValidator();
validator.registerValidatorModule(new FhirInstanceValidator(ctx));

ValidationResult result = validator.validateWithResult(bundle);
if (!result.isSuccessful()) {
    result.getMessages().forEach(msg -> log.error("FHIR validation: {}", msg.getMessage()));
    throw new FhirValidationException("Bundle failed FHIR R4 validation");
}

Also validate against NRCeS Indian FHIR profiles — the base R4 validator won't catch India-specific mandatory fields.

Where to Start

If you're adding FHIR to an existing HMIS:

Register on ABDM Sandbox (sandbox.abdm.gov.in) — get test credentials, ABHA test IDs
Implement patient linking first — it's the foundation everything else builds on
Pick one document type (OPD prescription is simplest) — implement, validate, and submit end-to-end
Add FHIR as a side-car — don't refactor your entire data model; write a FHIR translation layer on top of your existing schema
Use HAPI FHIR server as your local FHIR store if you need to expose FHIR endpoints to other systems

The Bigger Picture

India's FHIR-driven ABDM is creating something genuinely powerful: a federated health record for 1.4 billion people, owned by patients, not hospitals. When it works — when a patient from Ahmedabad can show their complete health history at a hospital in Mumbai with a QR code — that's transformative.

The complexity is real, but the foundation is sound. For developers building Indian healthcare software, investing in FHIR now means your system stays relevant for the next decade. The NHA is not backing down on ABDM compliance.

If you're building HMIS software and want to talk through FHIR integration, ABDM compliance, or the realities of healthcare IT in India, reach out — I've spent years in the trenches building exactly this.

Harikrushna V is the founder of SnowCare Health Tech (ArogyaPlus HMIS) and Orglance Technologies. 13 years building enterprise systems across PayPal, Salesforce, and NCR. Building India's next generation of healthcare IT.

Why Java + Spring Boot is Still the King of Enterprise Backend (2026)

Harikrushna V — Tue, 26 May 2026 08:27:53 +0000

Why Java + Spring Boot is Still the King of Enterprise Backend (2026)

After 13 years building enterprise systems across PayPal, Salesforce, and NCR, I've watched frameworks come and go. Go, Rust, Node — all excellent tools. But when a hospital needs to process 10,000 patient records with zero data loss, or a fintech platform needs to handle ₹500Cr in daily transactions, the stack that gets chosen again and again is Java + Spring Boot.

Here's why.

1. Battle-Tested at Scale

Spring Boot's ecosystem isn't just mature — it's been war-tested. Spring Security handles OAuth2, JWT, and multi-tenant auth without reinventing the wheel. Spring Data JPA abstracts complex queries without sacrificing control. Actuator gives you production observability out of the box.

When we built the ArogyaPlus HMIS platform at SnowCare Health Tech, Spring Boot's transaction management and audit trail features saved weeks of implementation time. The framework understood what we needed before we asked.

2. The Talent Pool is Real

Hiring a senior Node.js developer who really understands async event loops, memory leaks, and production debugging is hard. Hiring a senior Java developer with Spring Boot experience? Straightforward. The talent pipeline from Indian engineering colleges ensures consistent quality, especially for offshore teams.

At Orglance Technologies, we've built and placed dedicated Java/Spring Boot engineering teams with clients across the US, UK, and Japan. The quality bar is consistently high — and the cost advantage over hiring locally in Western markets is significant.

3. Microservices Without the Chaos

Spring Cloud (Eureka, Config Server, Gateway) gives you a full microservices toolkit that actually holds together under enterprise requirements. Yes, Kubernetes handles orchestration — but the service-to-service contract, circuit breaking (Resilience4j), and distributed tracing (Sleuth + Zipkin) are where Spring shines.

4. Healthcare IT and Fintech Love It

Regulatory requirements in healthcare (HL7, FHIR compliance) and fintech (PCI-DSS, audit logging) are better served by Spring's mature security and audit features than most alternative frameworks. When a compliance auditor walks in, you want a stack with a 20-year paper trail.

When to Choose Something Else

High-concurrency, low-latency APIs: Go or Rust may outperform
Rapid prototyping: Node/FastAPI are faster to spin up
ML pipelines: Python is non-negotiable
Truly serverless: Go cold-starts beat JVM

The Takeaway

Java + Spring Boot isn't boring — it's reliable. In enterprise software, boring is a feature. If you're building mission-critical systems, don't chase novelty. Build on what ships.

Harikrushna V is the founder of Orglance Technologies, an India-based software services company specialising in Java/Spring Boot, healthcare IT, and fintech systems. If you're looking for a dedicated India engineering team or want to discuss a project, reach out at hello@orglancetechnologies.com.

Eclipse RCP Testing tools before your code goes to LIVE

Harikrushna V — Tue, 12 May 2020 03:54:55 +0000

Use these Eclipse RCP Testing tools before your code goes to LIVE
Testing is most important part of any software development lifecycle. There are different type of testing required before Eclipse RCP tool is released to productions.

Eclipse RCP is very easy to test with the these testing tools:

UI Testing:

RCP Testing Tool

RCP Testing Tool is a project for GUI testing automation of Eclipse-based applications. RCPTT is fully aware about Eclipse Platform's internals, hiding this complexity from end users and allowing QA engineers to create highly reliable UI tests at great pace.

SWT Bot

SWTBot is an open-source Java based UI/functional testing tool for testing SWT, Eclipse and GEF based applications.

SWTBot provides APIs that are simple to read and write. The APIs also hide the complexities involved with SWT and Eclipse. This makes it suitable for UI/functional testing by everyone, not just developers. SWTBot also provides its own set of assertions that are useful for SWT. You can also use your own assertion framework with SWTBot.

Jubula

Eclipse Jubula is a new addition to the Eclipse universe. It's a functional UI testing tool that allows you to specify and run tests. Jubula consists of plug-ins for an IDE and a standalone RCP application.

Unit Testing

JUnit

JUnit 5 is the next generation of JUnit. The goal is to create an up-to-date foundation for developer-side testing on the JVM. This includes focusing on Java 8 and above, as well as enabling many different styles of testing.

Mockito

Tasty mocking framework for unit tests in Java.

Mockito is a mocking framework that tastes really good. It lets you write beautiful tests with a clean & simple API. Mockito doesn’t give you hangover because the tests are very readable and they produce clean verification errors.

Build Tool

Tycho

Tycho is focused on a Maven-centric, manifest-first approach to building Eclipse plug-ins, features, update sites, RCP applications and OSGi bundles. Tycho is a set of Maven plugins and extensions for building Eclipse plugins and OSGi bundles with Maven. Eclipse plugins and OSGi bundles have their own metadata for expressing dependencies, source folder locations, etc. that are normally found in a Maven POM. Tycho uses native metadata for Eclipse plugins and OSGi bundles and uses the POM to configure and drive the build. Tycho supports bundles, fragments, features, update site projects and RCP applications. Tycho also knows how to run JUnit test plugins using OSGi runtime and there is also support for sharing build results using Maven artifact repositories.

DEV Community: Harikrushna V

FHIR DiagnosticReport Resource: A Developer's Guide to Lab Reports and Radiology in an Indian HMIS

FHIR DiagnosticReport Resource: A Developer's Guide to Lab Reports and Radiology in an Indian HMIS

What Is a FHIR DiagnosticReport?

Why This Matters for an Indian HMIS

The DiagnosticReport Fields That Actually Matter

status — the lifecycle of the report

category — what kind of report is this?

code — what was the report for?

subject — which patient

effective[x] — when was the test performed

issued — when was the report released

performer — who performed the test

results — the underlying Observations

imagingStudy — for radiology reports

conclusion — the free-text interpretation

conclusionCode — coded diagnoses from the report

presentedForm — attachments

Building It with HAPI FHIR in Java

Maven dependencies

Creating a CBC lab report

Storing and exposing the report

An Indian Radiology Workflow, End to End

Common Pitfalls When Modelling DiagnosticReport

How ArogyaPlus HMIS Handles DiagnosticReport

FHIR MedicationRequest Resource: A Developer's Guide to Modelling Prescriptions in an Indian HMIS

FHIR MedicationRequest Resource: A Developer's Guide to Modelling Prescriptions in an Indian HMIS

MedicationRequest vs MedicationStatement vs MedicationDispense

Anatomy of a MedicationRequest

Drug coding in the Indian context

Spring Boot + HAPI FHIR code

ABDM integration: prescriptions as part of a Bundle

Common pitfalls

Closing thought

OAuth2 + OpenID Connect in Spring Boot: A Practical Guide for Java Backend Engineers

OAuth2 + OpenID Connect in Spring Boot: A Practical Guide for Java Backend Engineers

OAuth2 vs OpenID Connect: The Distinction That Matters

The Four Flows and When to Use Each

Spring Security OAuth2 Resource Server

Maven Setup

application.yml

Security Configuration

Extracting Custom Claims

Spring Security OAuth2 Client

Validating Tokens: What to Actually Check

Common Gotchas

Conclusion

JWT Authentication in Spring Boot: A Complete Guide for Java Backend Engineers

JWT Authentication in Spring Boot: A Complete Guide for Java Backend Engineers

How JWT Works

Project Setup

Token Service

JWT Filter

Security Configuration

Authentication Controller

Token Refresh: What Most Tutorials Get Wrong

Docker Deployment: The Secret Management Problem

Common JWT Gotchas

Conclusion

FHIR Practitioner Resource: A Developer's Guide to Modelling Indian Healthcare Professionals in HMIS

FHIR Practitioner Resource: Modelling Indian Healthcare Professionals in Your HMIS

What Is the Practitioner Resource?

The India-Specific Angle: HPR and MCI

HPR — Health Professional Registry

MCI / NMC Registration

Spring Boot + HAPI FHIR Implementation

JPA Entity

Validating Practitioner Identity Against ABDM

Common Mistakes to Avoid

Prescription Linkage: Practitioner ↔ PractitionerRole

What's Next

Spring Security Filter Chain: A Deep Dive for Java Backend Engineers

Spring Security Filter Chain: A Deep Dive for Java Backend Engineers

What Is the Security Filter Chain?

The Default Security Filter Chain (Spring Boot 3.x)

Customizing the Security Filter Chain: A Real Production Example

Building the JWT Authentication Filter

Building the API Key Filter

Filter Order Matters — Here's Why

Method-Level Security: @PreAuthorize

`status` — the lifecycle of the report

`category` — what kind of report is this?

`code` — what was the report for?

`subject` — which patient

`effective[x]` — when was the test performed

`issued` — when was the report released

`performer` — who performed the test

`results` — the underlying Observations

`imagingStudy` — for radiology reports

`conclusion` — the free-text interpretation

`conclusionCode` — coded diagnoses from the report

`presentedForm` — attachments