OpenMRS FHIR2 module and SMART on FHIR

A SMART app launch passes through three parties: the external app, Keycloak as the authorization server, and OpenMRS with the FHIR2 module as the resource server. Understanding the order of those hand-offs is the fastest way to find where a launch fails. The SMART on FHIR module supports the SMART App Launch Framework on top of the FHIR2 API and uses Keycloak as its default authorization server, so the flow below assumes that pairing. Treat it as a conceptual map. Your own realm, client definitions and scope configuration determine what actually happens in your environment, and you should walk the flow end to end against those settings before any clinical user or partner app depends on it.

In plain steps, the app first identifies itself to Keycloak as a registered client and redirects the user's browser to the authorization endpoint with the scopes it asks for. For a user-facing launch, the user signs in at Keycloak and consents where consent is configured. Keycloak then returns an authorization code, which the app exchanges at the token endpoint for an access token. The app calls FHIR2 endpoints with that token as a bearer credential. Each request carries the scopes that were granted, and the scopes are the boundary the app is supposed to stay inside. A backend system app follows a similar pattern with the client credentials grant and a system scope, with no interactive user. Confirm which scope patterns your SMART configuration accepts for patient, user and system access, because an app that requests a broader scope than your client permits should be refused at the token step, not at the data step.

The OAuth2 Login module is where OpenMRS stops relying on its own basic authentication and starts trusting the identity provider. When a token holder signs in for the first time, the module can create the OpenMRS user on the fly, populating name and email from the identity claims and assigning roles from the token. This is convenient, but it means OpenMRS accepts whatever the identity provider asserts. Decide before go-live which claims supply the username, name, email and roles, and document the mapping for each realm and client. The module documents Keycloak configuration, so start from that reference and then verify the claim names your realm actually emits.

Role mapping is where access rules most often go wrong. A realm role, a client role and a group can all look like the same permission to a person reading the admin console, yet only one of them may reach the OpenMRS privilege the team intended. Common failures include a default role granted to every new user, a composite role that quietly includes an administrative privilege, a mapper that copies roles from a different client, and a token that carries roles from a previous sign-in because sessions were not expired. Test with several accounts that hold deliberately different roles, and check both what the token contains and what OpenMRS grants after login. Keep the mapper configuration under version control with the realm export so changes are reviewed like code.

Before a partner app or national exchange is connected, run a test plan that covers a successful launch, a launch with a scope the client should not hold, a user with no mapped role, a revoked or expired session, and a backend system call. Record the token claims and the resulting OpenMRS privileges for each case. Ask your implementation team and your identity administrator to confirm the Keycloak version and database support for your environment against the current Keycloak documentation, since realm and client behavior is tied to the release you run. Because the exact settings depend on your deployment, the results of this test plan, not the diagram, are the evidence you should keep.

The FHIR2 module can only expose what OpenMRS already records consistently. A FHIR Observation is only as useful as the concept it points to, an Encounter is only as useful as its encounter type, and a Patient resource is only as trustworthy as its identifiers. For that reason the concept dictionary, encounter types and identifier schemes should be stable before a national system or third-party app starts testing against the API. Changes to concepts after partners have mapped them tend to break mappings silently, so treat the dictionary as a release that is frozen for the exchange scope.

Start with coded data. Review the concepts that will appear in exchanged Observations, Conditions and Medication Requests, and confirm that each one has a clear name, a concept class, a datatype and a reference term in the code system your partner expects. Check for duplicate concepts that express the same clinical idea, and for locally created concepts that duplicate a shared concept already in the dictionary. The sibling topic on Open Concept Lab covers how shared and local concepts are managed, including subscriptions, validation rules and offline imports, so use it to settle those decisions first rather than repeating the work in the exchange project.

Next, check patient data. Run a duplicate patient review against the identifiers that the FHIR Patient resource will carry, and decide which identifier type is the exchange identifier. Confirm that each identifier type has a documented format, a validation rule and an owner, and that the partner understands which system URI identifies it. Where the same person has records under several identifier types, decide how merges are handled before any Patient is published, because a merge after exchange has started must be communicated to every consuming system. Also confirm that encounter types and visit types are used consistently across sites, since partners will often filter on them.

Legacy forms need a separate decision. The O3 form migration tool was built by Palladium Kenya to convert legacy OpenMRS HTML forms to the O3 form schema, and the community adopted it. It matters only if legacy HTML forms feed the data you plan to exchange. If they do, confirm which forms are involved, whether their concept mappings are complete, and whether the converted forms produce the same concepts and encounter types as the originals. If no exchanged data originates from HTML forms, you can leave this tool out of scope and say so in the statement of work.

Before the partner begins testing, agree a short written readiness checklist and have the OpenMRS team sign it off. It should list the concepts and encounter types in scope, the identifier types used for exchange, the duplicate patient review result, the status of legacy forms, and the named owner for each item. Ask the partner which terminology and identifier conventions they require, and confirm that your deployment's FHIR2 and SMART on FHIR configuration can produce them, because some requirements will need data cleanup rather than configuration.