OpenMRS SSO with Keycloak and OAuth2 guide

How OpenMRS SSO with Keycloak changes login, roles and app launch

Teams that want OpenMRS staff to sign in through their existing identity provider, rather than with local OpenMRS accounts, need the OAuth2 Login module. It replaces OpenMRS basic authentication with an OAuth 2.0 provider, so passwords are checked by the identity system and not stored as OpenMRS user credentials. SMART on FHIR app launch depends on the same identity setup: the FHIR2 module provides the FHIR REST API, and the SMART on FHIR module supports the SMART App Launch Framework on top of it, so the login design you choose here also determines how third-party apps are authorized from the patient record. The case for this usually comes from three places. A clinic network or national program wants central account management, so that a person's access is granted and removed in one directory instead of in every site's OpenMRS instance. Offboarding becomes consistent, because disabling the identity account stops OpenMRS sign-in as well. And teams that launch third-party apps from the record need a single, governed identity that those apps can trust. Keycloak is the documented default authorization server for the SMART on FHIR module, which makes it the usual starting point, although another OAuth 2.0 provider can be used if your environment requires it. Confirm the provider configuration against the module documentation for your version. The work is harder than it looks for three reasons. First, the module creates users on the fly at first login, so the name, email and role claims the provider sends must be correct and complete. A missing email or an unexpected name format creates accounts that staff cannot use or that cannot be matched to existing records. Second, role mapping lives in two systems: roles defined in the identity provider must be translated into OpenMRS roles and privileges, and both sides must be kept in step as roles change. Third, SMART apps add scopes and redirect configuration on top of login. Each app needs registered redirect URIs, the correct scopes and a clear decision about which clinical data it may read. Before a build starts, decide which identity provider is authoritative, list the roles that must map to OpenMRS privileges, and test first login with a sample of real user profiles in a non-production instance. Ask your implementation partner to show the claim-to-user mapping and the role mapping as written configuration, and confirm how local administrator accounts will be kept as a break-glass path if the provider is unavailable.

Which OpenMRS components and identity settings are involved

An OpenMRS SSO build touches the core platform, the OAuth2 Login module, the identity provider, and the FHIR and SMART modules that depend on the same identity. Each component has a specific setting the team will change, and several of them must agree on the same issuer, client and network path.

OpenMRS core on Tomcat or Jetty

The OpenMRS core is written in Java, built with Maven, and runs on Tomcat or Jetty with MySQL, MariaDB or PostgreSQL as the database. The team confirms the servlet container and database version it will deploy, then checks the runtime configuration that the OAuth2 Login module reads at startup. Confirm the exact supported versions for your chosen core release in the openmrs-core repository before you commit to a stack.

OAuth2 Login module configuration

This module replaces OpenMRS basic authentication with an OAuth 2.0 provider and is the main place where login behavior is set. The team defines the issuer, client identifier, client secret and scopes, and decides whether users are created on first login. Check the module's documented Keycloak and Google configurations and confirm which properties your release expects.

Identity provider and client registration

Keycloak is the documented example, and Google is documented as a second configuration. The team registers OpenMRS as a client, sets the redirect URIs to the gateway address, and maps the name, email and role claims that OpenMRS will read. Keep the issuer URL identical in every component, because a mismatch is a common cause of failed logins.

Role and attribute mapping

The OAuth2 Login module maps names, email and roles from the token onto OpenMRS users and roles. The team decides which identity provider groups or roles map to which OpenMRS roles, and whether unmapped users receive any access. Review this mapping with the clinical and security owners, and test it with accounts that hold each intended role.

JWT service accounts

The OAuth2 Login module supports JWT-based service accounts for non-interactive callers such as integrations. The team decides which systems need a service account, which client credentials they use, and what OpenMRS privileges those accounts hold. Limit these accounts to the minimum privileges their integration requires and record who owns each one.

FHIR2 module and R4 REST API

The FHIR2 module provides the FHIR REST API for OpenMRS, focused on FHIR R4 with translation support for R3. Every FHIR request must carry a token that OpenMRS accepts, so the team checks that the FHIR endpoints sit behind the same identity configuration. Confirm which FHIR resources your integrations need and test each one with a token issued by the chosen provider.

SMART on FHIR module and authorization server

The openmrs-module-smartonfhir module supports the SMART App Launch Framework with FHIR2 and uses Keycloak as its default authorization server. The team decides whether launches use the default Keycloak setup or a different authorization server, and registers each SMART app with the expected scopes and redirect URIs. Verify each app launch end to end, because a launch can fail even when the basic login succeeds.

O3 gateway and network reachability

In the O3 Reference Application Docker Compose setup, the Nginx gateway terminates TLS and routes requests, and the optional Certbot service can supply certificates. The identity provider must be reachable from the OpenMRS backend for token validation and from the user's browser for login redirects. Test both paths separately, since a provider address that resolves only inside the Docker network will break browser login.

Decisions to settle before configuring OpenMRS login

This table compares the decisions that shape OpenMRS single sign-on with Keycloak or another OAuth 2.0 provider, and the operational cost each option carries. Read each row to find the option that fits your sites, staffing and clinical risk, then confirm the trade-offs with your OpenMRS implementer before configuration starts.

Decision	Option and when it fits	Operational cost to plan for
Identity provider	Keycloak already in the estate: fits organizations with existing Keycloak administration skills and a second system to protect. Another OAuth 2.0 provider: fits where a corporate directory is the source of truth. Google: fits a small pilot with few users.	Keycloak adds a service to patch and back up. Other providers need confirmed OAuth2 Login configuration. Google depends on an external account model that may not match clinical access rules.
User creation	On first login: fits pilots and a single site where the OAuth2 Login module creates accounts on the fly. Pre-provisioned: fits national or multi-site programs that need an approved user list before anyone can sign in.	First login is quick to start but leaves account review to later. Pre-provisioning needs a joiner and leaver process that someone owns.
Role source	Identity provider groups: fits organizations that already manage roles centrally and want one place for access reviews. Roles inside OpenMRS: fits teams that want clinical privileges managed by the implementation team.	Group-based roles need mapping rules kept in step with OpenMRS roles. In-application roles mean maintaining assignments in two places whenever staff change duties.
Break-glass account	Keep a local account: fits any production site, so staff can still reach the system during an identity provider outage. Remove it: fits only when the provider has its own tested recovery path.	The local account needs a strong, stored credential, restricted access and periodic testing. Someone must record each use and review it.
SMART app authorization server	Default Keycloak server: fits deployments that already run the smartonfhir module with Keycloak. Another authorization server: fits where app vendors require a specific server or token format.	A separate server adds configuration and certificate work. Launch depends on the chosen server being available, so app launch fails when it is down.
Platform runtime	WAR on Tomcat with an existing MySQL, MariaDB or PostgreSQL database: fits sites with established Java hosting. O3 container stack: fits deployments built on the O3 Reference Application and its Docker Compose services.	Each runtime has its own patching, module compatibility and upgrade path. Confirm which OAuth2 Login and SMART modules support your chosen version before you commit.

OpenMRS SSO with Keycloak build sequence

This sequence takes an OpenMRS deployment from a confirmed version and hosting model to single sign-on with Keycloak or another OAuth 2.0 provider. It maps identities and roles into OpenMRS, sets first-login behavior, and then enables SMART on FHIR app launch and, where needed, system-to-system service accounts. Each step closes with a check the team can observe.

Confirm OpenMRS version and deployment model
Record the OpenMRS line you will run, either the O3 Reference Application or the Platform deployed as a WAR file on Tomcat, along with the hosting model and database, such as MySQL, MariaDB or PostgreSQL. The latest supplied releases are O3 3.7.1 and Platform 2.8.1, but confirm which module versions support your chosen line in the OpenMRS module documentation before building. Agree this decision in writing with the DeployOpen engineers and your clinical owner. Check: the environment record names one version, one database and one hostname for staging and production, and the staging instance reports the expected version in its administration pages.
Stand up the OAuth 2.0 provider and client
Run Keycloak or select another OAuth 2.0 provider, create a dedicated realm for OpenMRS, and register a confidential client for it. Set redirect URIs to the exact scheme, host and path of the deployed OpenMRS instance, including any gateway hostname, and use separate clients for staging and production so their redirect URIs never overlap. Add a logout redirect where the provider supports one. Check: the provider's discovery document loads from the OpenMRS server, and the authorization endpoint for the staging realm returns its login page in a browser.
Configure the OAuth2 Login module
Install the OAuth2 Login module and set the issuer URL, client ID, client secret and requested scopes in the runtime properties. Store the client secret in your secrets store, not in version control. Map the claims for name, email and roles to the attributes OpenMRS expects, using the Keycloak example in the module documentation as the starting point and checking each claim name against what your provider actually issues. Check: a decoded token from a staging login contains name, email and role claims under the names the mapping uses, and the server log shows no startup errors from the module.
Map roles and test with staging users
Map provider roles or groups to OpenMRS roles and privileges, granting each group only the functions its work requires. Create one test user per mapped role in the staging realm, sign in as each, and compare the functions visible in OpenMRS with the mapping table. Remove any mapping that grants more than its purpose. Check: each test user lands on the expected home page and can open only the functions in the table, and a user with no mapped role is denied access.
Set first-login user creation behavior
Decide whether the OAuth2 Login module creates an OpenMRS user the first time a provider user signs in, or whether an administrator pre-creates and links accounts. Automatic creation determines who gets a record account without review, so record the decision with the clinical governance owner before enabling it. Configure the chosen behavior in staging and test with one new provider user and one pre-created user. Check: the new user appears in the OpenMRS user list with the expected name, email and roles, and a provider user without an approved account is rejected or routed as the decision specifies.
Install FHIR2 then the SMART on FHIR module
Install the FHIR2 module first, since the SMART on FHIR module works with it, and confirm the FHIR R4 endpoints answer an authenticated request. Then install the SMART on FHIR module, which uses Keycloak as its default authorization server, and register the SMART app in the authorization server with its redirect URI, launch context and scopes. Limit scopes to what the app reads or writes. Check: a SMART launch from the registered app opens an authorization request, the token response includes the patient or encounter context the app expects, and a resource outside the granted scopes returns an authorization error.
Configure JWT service accounts for system calls
Configure JWT service accounts only if the integration must call OpenMRS without a user present. Generate the signing key pair, keep the private key in your hosting environment's secrets manager, register the service account client in the provider, and assign the narrowest roles the integration needs. Write down who rotates the key and how often your policy requires. Check: the service account obtains a token without a browser session, the token carries the expected client identity and roles, and a FHIR read with that token succeeds while the same call under an out-of-scope identity is refused.

How to test OpenMRS SSO and confirm it fails safely

Before go-live, the team should prove that OpenMRS SSO grants the right access, denies the wrong access, and falls back safely when the identity provider is unavailable. Run these tests against the same Keycloak realm, client registration and OAuth2 Login module configuration that production will use, not a convenience setup. Start with a test matrix that lists each role you have mapped in Keycloak, each OpenMRS privilege set it should receive, and the expected result for every test case below. Keep the matrix in the project record so that every later change can be checked against it. For login behavior, test a successful sign-in for each role, confirming that the user lands with the privileges that role should carry and nothing more. Then test a user who exists in Keycloak but has no mapped role, and confirm that access is denied rather than silently creating an account with default rights. For first-login creation, use a new test identity and check that the account in OpenMRS shows the correct given name, family name and email, since the OAuth2 Login module maps these from the token. Next, remove a role from the test user in Keycloak and confirm the change takes effect on the next session. Also check that an expired token and a revoked token are both rejected by OpenMRS and by any SMART app that relies on it. For SMART on FHIR launch, test a launch with a correct redirect URI and an incorrect one. The incorrect launch should fail, and the failure should not expose tokens or patient data. Record the exact response in both cases. Keep in mind that the SMART module depends on the FHIR2 module and uses Keycloak as its default authorization server, so test the launch path in the same environment you plan to run. Fail-safe behavior needs its own checks. Stop Keycloak in a test environment and document what a user sees when they try to sign in: the message should be clear, should not show a stack trace, and should not offer an alternative login that bypasses the identity provider. Confirm that the break-glass administrator account still works while Keycloak is down, and that it is limited to administrators and cannot be used by ordinary clinical staff. Finally, confirm that basic authentication is no longer the path to sign in once the module is active, by attempting a username and password login through the standard form and documenting the outcome. Record test evidence for every case: date, tester, module and Keycloak versions, configuration snapshot, screenshots or logs, and the pass or fail result. Auditors and assessors will ask for this record, and it is easier to produce during the build than to reconstruct later. Confirm the exact behavior of each OAuth2 Login and SMART module version in your own environment, because module behavior can change between releases and this plan does not replace testing against the versions you deploy.

What drives SSO effort and cost on an OpenMRS deployment

This table lists the factors that change how much work an OpenMRS SSO build takes, why each one matters, and what the team can do to keep it contained. Use it to check that a quote itemizes each driver against the written scope. The main takeaway is that role design, identity provider choice and the number of sites and SMART apps usually move effort more than the Keycloak or OAuth2 configuration itself.

Driver	Why it changes effort	How to keep it down
User groups and roles	Each OpenMRS role must be mapped from a group or claim in the identity provider, and every mapping needs testing against real privileges.	Agree a shared role model before build, and limit mappings to the roles each site actually uses.
Existing identity provider	If the organization already runs a directory or provider the team can administer, the Keycloak work is mostly federation. If not, the team also builds and operates a new identity service.	Reuse the existing provider where the team can support it, and confirm administrator access and supported versions early.
Number of sites and environments	Each site may have its own users, locations and redirect addresses, and development, test and production each need separate clients and secrets.	Use one identity provider for all sites and keep environment configuration in version-controlled templates.
Number of SMART apps and scopes	Each SMART on FHIR app needs its own client registration, scope set and launch testing, and broader scopes increase the review and test surface.	Keep the SMART app list small, request only the scopes each app needs, and add new apps through a defined intake step.
Custom modules or distributions touching authentication	Custom code or a modified distribution that handles login, sessions or user creation must be analyzed and retested against the OAuth2 Login module.	Confirm early which custom modules touch authentication and decide whether to adapt, replace or retire them.
High availability or Kubernetes	Session handling, token validation, TLS termination and secret storage must work across several nodes or clusters, which adds design and test steps.	Decide the hosting model before build so the identity design targets it once, and confirm the platform version in use.
Compliance evidence to keep	Assessors may ask for access reviews, configuration records, change history and test results for login and role assignment, and these must be produced from the working system.	Agree the evidence list with the compliance owner at scoping, and build logging and review exports into the design. DeployOpen prepares evidence but does not issue audit reports.

How SSO setup differs across single node, containers and air-gapped sites

A single node running the OpenMRS WAR on Apache Tomcat with an existing MySQL database is the most direct model. The OAuth2 Login module runs in the same Tomcat process that holds the user session, so most of the work sits in the identity provider registration and the module settings. There is one public hostname, one set of callback paths and one trust store to maintain.

What changes in this model:

Redirect URIs: register the exact callback URL the OpenMRS host answers on, including scheme, host name and port, on the identity provider client.
Certificate trust: if the provider uses a certificate issued by an internal CA, add that CA to the Java trust store used by Tomcat so token and metadata calls succeed.
Network paths: the server needs outbound access to the provider's authorization, token and user information endpoints, and its existing connection to MySQL must stay unchanged.
Testing: check a first login for a new user, a returning user and a user with no matching role mapping, then confirm the user record and roles that OpenMRS created.

Confirm the module version and configuration keys against the OAuth2 Login module documentation before you copy any example into your environment.

Securing OAuth2 client secrets, redirect URIs and service accounts

Once OpenMRS delegates logins to Keycloak, the identity provider becomes the front door to patient records. The controls below cover the credentials, endpoints and accounts that connect OpenMRS to that provider, and they decide whether a single compromised secret or misconfigured redirect exposes clinical data. Work through them together, because a strong client secret does little if redirect lists are loose or the basic login path still accepts passwords.

Keep the client secret out of configuration files

The OAuth2 Login module needs a client secret to exchange authorization codes with Keycloak. Do not place it in properties files committed to source control or baked into container images. Load it at startup from a managed secret store, restrict read access to the OpenMRS service identity, and confirm that rotation can be done without rebuilding the deployment. Check the secret's presence in backups and deployment logs as well.

Set redirect URIs and origins per environment

Define exact redirect URI and web origin entries in each Keycloak client for development, test and production, rather than wildcard patterns that match unintended hosts. Each environment should have its own client so that a test redirect cannot receive production authorization codes. Review the list whenever the gateway hostname changes, because a stale entry is a common route for token leakage.

Terminate TLS at the gateway with trusted certificates

The O3 Docker Compose setup places an Nginx gateway in front of the backend and offers an optional Certbot service for certificates. Confirm that the gateway serves a valid certificate chain for the public hostname, and that the OpenMRS backend and Keycloak trust the issuing authority on their internal connections. Disable plaintext listeners on the public path and verify the redirect and token endpoints are reached only over HTTPS.

Limit SMART app scopes to what each app needs

The SMART on FHIR module uses Keycloak as the default authorization server, so each registered SMART app receives the scopes it requests. Grant read-only scopes to apps that only display data, and write scopes only where a documented workflow requires them. Review the scope list for each app before go-live and whenever an app is updated, since broad scopes extend what a compromised app can reach.

Manage signing keys and rotation for service accounts

JWT service accounts used by integrations need signing keys that are generated, stored and rotated under a written schedule. Confirm which key algorithm Keycloak and the OAuth2 Login module are configured to accept, and remove any key that is no longer assigned to a live integration. Test a rotation in the non-production environment first so that a failed key swap does not stop interfaces during clinic hours.

Restrict the basic authentication path after SSO

Once the OAuth2 Login module replaces basic authentication, decide whether password logins remain available for any user group. Disable the basic path or restrict it to a named network segment, and confirm that no local account retains a usable password. Test that the login page routes users to Keycloak and that direct calls to the legacy login endpoint are refused, since a leftover path undermines the MFA controls set in the identity provider.

Monitor the break-glass administrator account

Keep one local administrator account for recovery when Keycloak is unavailable, and store its credentials in a sealed, access-logged location. Alert on every login with that account, require a documented reason, and review the access log after each use. Confirm with the team that the account cannot be used for routine clinical work and that its password is rotated after each emergency access event.

Map roles to minimum clinical privileges

The OAuth2 Login module maps names, email and roles from the identity provider into OpenMRS. Define a role map that grants each clinical group only the OpenMRS privileges its work requires, and do not map Keycloak administrator roles to OpenMRS administrator privileges. Check the mapping with a sample account from each group, and review it when staff change posts. Database and patching concerns are covered in the OpenMRS security hardening topic.

What to monitor, back up, upgrade and document after SSO goes live

Once OpenMRS delegates logins to Keycloak or another OAuth 2.0 provider, the login path becomes a production dependency. If the identity provider is slow or down, clinicians cannot reach the chart, so the first ongoing duty is monitoring. Watch failed logins and token errors in both the OpenMRS logs and the Keycloak event log, and track availability of the identity provider endpoints that the OAuth2 Login module and the SMART launch flow call. Set alert thresholds with the clinical operations lead, because a spike in failures at one site may point to a clock drift, an expired client secret or a certificate problem rather than a password issue. Confirm with your team which log retention period applies to authentication events under your own data governance rules. Back up the identity provider configuration with the same discipline you apply to the OpenMRS database. The Keycloak realm, its clients, role mappers and identity mappers define who can sign in and which OpenMRS roles they receive. Export them on a schedule and store the exports with the database backups, so that a restore brings back users, clients and mappers that match the OpenMRS data they unlock. Test a restore of both into a non-production environment at least once, and record how long the restore took and which manual steps were needed. Client secrets and signing keys should be handled through your secrets store, not written into the export files. Retest login and SMART launch after every OpenMRS Platform or O3 upgrade and after every module update, including updates to the OAuth2 Login, FHIR2 and SMART on FHIR modules. These modules move with the core, so a version change in one can break a token claim, a role mapping or an app launch context without any visible error on the login page. Build a short regression script that signs in with each role, opens a patient chart, and launches a SMART app, and run it in staging before each change reaches production. The upgrade process itself is covered in the OpenMRS upgrades and support topic. Rotate client secrets and signing keys on a schedule that your organization sets, and write that schedule into your change calendar. Rotation of a signing key must be coordinated with the identity provider configuration and the OpenMRS module settings, so that tokens issued under the old key remain valid for the agreed overlap window. Ask your partner to confirm how the chosen OpenMRS module version reads new keys, and rehearse one rotation in staging before the first production rotation. Note that OpenMRS has no paid edition, so no vendor will issue security notices for you. Your organization or its implementation partner must own module upgrades and must keep at least two people who can read and change the Keycloak and OpenMRS configuration. Document the role mapping between identity provider roles and OpenMRS privileges, the joiner and leaver process that creates and disables accounts, and the test evidence from each regression run. The role mapping table should name each source group, the OpenMRS role it grants and the owner who approves changes. The joiner and leaver process should state who requests access, who approves it, how fast a departing user is disabled in the identity provider, and how that is checked against OpenMRS user records. Keep the test evidence with the change record so that an internal reviewer or external auditor can trace each release to the checks that passed.

Questions teams ask before setting up OpenMRS SSO

Can an in-house team configure the OAuth2 Login module themselves?

Yes, in principle. A team with Java, Maven and Tomcat experience can work from the OAuth2 Login module documentation and a test identity provider. The module documents Keycloak and Google configurations, which gives a starting point.

The harder parts are role design and testing discipline. Decide which OpenMRS roles map to which identity provider groups, who approves that mapping, and how each role is tested with named test accounts before go-live. Teams that skip the role matrix often discover wrong privileges only after users sign in.

Ask whether someone on your team can own the mapping and the test plan through the project and after it. Those responsibilities outlast the initial configuration.

How long does OpenMRS SSO setup take and what drives it?

No duration can be stated without a written scope. The time depends on how many identity providers and client applications are involved, how complex the role design is, how many test users and sites must be verified, and whether SMART on FHIR app launch is included.

Network and certificate access also shape the schedule. Each delay in providing access adds coordination time.

Ask for a timeline broken into discovery, configuration in a test environment, role mapping, test cycles, staging and cutover, with the dependencies for each stage named. Compare proposals against the same list of assumptions. A shorter timeline built on fewer test cycles or a single identity provider covers a different scope.

What does our team need to provide for OpenMRS SSO?

Plan to provide five things.

Administrative access to the identity provider, including the ability to create clients, scopes and group or role claims.
A named role owner who decides which OpenMRS privileges each group receives and signs off on the mapping.
Test users covering each role and each site type, so access can be verified.
Network paths between OpenMRS, the identity provider and user browsers, plus the TLS certificates for those endpoints.
A decision on whether SMART on FHIR apps will launch from OpenMRS, because that changes the FHIR2 and SMART module scope.

Confirm exact access levels with your identity team before kickoff. They vary by identity provider and by how your security policy separates duties.

Is Keycloak required for OpenMRS OAuth2 single sign-on?

No. Keycloak is the documented example and the default authorization server for the SMART on FHIR module. The OAuth2 Login module is built to work with OAuth 2.0 providers, and it documents Keycloak and Google configurations.

Using another OAuth 2.0 provider is a decision to confirm against the module documentation for your release. Check how it handles user creation, name and email mapping, role claims and JWT service accounts. Ask the provider's team which claims it can emit, then confirm they match what the module reads.

If your organization already runs an enterprise identity provider, evaluate it in a test environment before committing. Keycloak may still be the simpler choice where a documented path already exists.

Does SMART on FHIR app launch need a separate identity setup?

It adds scope. SMART on FHIR app launch runs through the SMART on FHIR module, which depends on the FHIR2 module that provides the FHIR REST API. The SMART module supports the SMART App Launch Framework and uses Keycloak as its default authorization server.

App registration, scopes and launch context must be set up and tested alongside the login flow. Decide early which apps need access, which clinical scopes they request, and which user roles may authorize them.

The FHIR2 module focuses on FHIR R4 with translation support for R3, so confirm each app's FHIR version before scoping. If SMART apps fall outside the first phase, state that in the written scope so the identity design leaves room for them later.

What does a fixed-scope OpenMRS SSO engagement cover?

A fixed-scope engagement covers the work listed in the written scope, agreed before work starts, with deliverables and timelines attached.

For this topic, the scope typically includes reviewing the identity design, configuring the OAuth2 Login module in a test environment against your chosen identity provider, mapping roles to OpenMRS privileges, testing with named users, preparing the deployment for your hosting, and handing over documentation. Whether SMART on FHIR, production cutover or ongoing support is included depends on what is agreed in writing.

DeployOpen implements, hardens and documents open-source platforms inside your own infrastructure, so environments and access stay under your control. Ask for a list of exclusions alongside the inclusions.

What should a quote for OpenMRS SSO include?

A quote should follow from the written scope and show cost components separately.

Ask for the one-time items: discovery, identity provider configuration, role design, testing, environment setup, documentation and cutover. Then ask which items recur, such as support, module updates when new OpenMRS releases ship, and periodic access reviews.

Ask who pays for identity provider licenses and hosting, since these may sit outside the implementation fee. Ask what each test cycle includes, how many environments are covered, and how changes to requirements after sign-off are handled. Ask how SMART on FHIR is priced, because app registration and testing add work.

DeployOpen does not publish a price list, so the written quote is where these components become specific.

How are OpenMRS roles mapped from identity provider claims?

The OAuth2 Login module creates users when they first sign in and maps names, email and roles from the token the identity provider issues. Your identity provider must therefore emit the role or group claims the module reads, in the format it expects.

Start by listing every OpenMRS role your sites use and the identity provider group that should carry it. Test one user per mapping, including users with several groups and users with none.

Check what happens to existing accounts created under basic authentication. Decide whether access is removed when a group is removed at the identity provider. Confirm claim names and formats against the module documentation for your release, because these details differ between providers.

How DeployOpen scopes, builds and hands over OpenMRS SSO work

DeployOpen treats OpenMRS login delegation as a fixed-scope engagement inside your own infrastructure. We agree the identity provider, role model and SMART on FHIR launch requirements in writing before build starts, then deliver the configuration, tests, documentation and handover for your team to run.

How we scope

Confirm which OAuth 2.0 provider you run or select, such as Keycloak, and which realm, clients and redirect URLs are needed.
Map which OpenMRS roles and privileges your staff hold today and which must come from identity provider groups or claims.
Record in the written scope whether SMART on FHIR app launch through the FHIR2 and SMART modules is included, and which apps need it.

How we build

Configure the OAuth2 Login module to replace basic authentication, with name, email and role mapping agreed in the scope.
Set up the identity provider client, token settings and JWT service account handling needed for integrations.
Test first logins, on-the-fly user creation, role assignment, logout and failed-login behavior in a non-production environment before cutover.

How we hand over

Deliver configuration files, deployment steps and a role mapping table in the form your team can review and reproduce.
Provide runbooks for rotating client secrets, adding roles and troubleshooting failed token exchanges.
Walk your administrators through the setup and record the open items that remain with your organization after handover.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the build.
Retainer work can cover re-testing the login flow when OpenMRS Platform or module versions change.
Confirm with us and your identity provider vendor which security updates apply to your environment before you commit to a support model.