Hello OpenMRS community,
We would like to seek guidance regarding a project idea that was initially proposed for GSoC but not officially selected: Password Authentication Re-work.
we are exploring the possibility of structuring this work as a targeted community sprint. This would be a fantastic, hands on opportunity for our active newbies who recently attained their Dev/1 developer badge and applied for GSoC but were never selected to collaborate on a critical core initiative.
Before we outline the sprint logistics, we want to ensure we are aligning with current community and implementing organization needs.
Is this project still considered a priority for any implementation?
Are there specific implementing organization(s) currently facing pain points around password authentication that this sprint could help resolve?
If the community agrees this is still a worthwhile priority, we would also highly appreciate any volunteers willing to provide technical oversight or mentorship to the squad. This will ensure our Dev/1 contributors meet OpenMRS standards while gaining valuable sprint experience.
Thank you for your time, feedback, and continued guidance!
Best regards.
cc @Madiro , @Mekom , @PIH , @PalladiumKenya , @SolDevelo , @openmrs , @devnull , @dev1 , @dev2 , @dev3 , @dev4 , @dev5. @beryl
This is such a great initiative for the newbies. Kudos for the thoughtful framing and for your continued contributions to OpenMRS.
Just wanted to flag some closely related work happening on the AMPATH side that’s worth being aware of as you scope this, because the password rework is foundational to a much bigger authentication picture that Kenya, for example, is moving towards.
What AMPATH already has in place:
OTP-based patient consent at the start of a visit - used to verifiably capture patient consent before accessing their health record. Where a patient doesn’t have a phone, the OTP is usually forwarded to a Facility Admin as a fallback.
Integrations with the national health stack that all lean on the authentication layer - like SHA, for example, for insurance claims.
What AMPATH is working towards:
Biometric login for providers - the Government of Kenya is actively distributing fingerprint scanners to facilities, and the longer-term direction is to move from passwords and OTPs to biometrics for security and cost reasons.
Configurable authentication workflows - some facilities will continue using OTP and others will move to biometrics, depending on facility capability, ideally with the same OTP mechanism reused across both provider login and patient consent flows.
Following the recent platform discussion, we noted that OpenMRS lacks a modern, flexible, and standards-based password authentication system. This results in reliance on outdated hashing approaches that do not support modern security features such as work factors and adaptive encoding thereby creating long-term security and maintainability risks. This post outlines a focused modernization effort for password authentication using Spring Security per the discussion during the squad call.
The scope of this project is strictly limited to :
Migrating all password handling to Spring Security PasswordEncoder
Supporting secure modern hashing (BCrypt/Argon2-ready)
Ensuring seamless backward compatibility with existing users
Enabling safe, incremental migration without service disruption
Success Criteria are:
Spring Security encoding fully integrated that entails all password changes use PasswordEncoder and the encoding strategy is configurable and extensible.
Deterministic bootstrap password mechanism: Derived from userUUID + systemSalt and used only for initial provisioning or controlled resets.
Legacy password rehash schema implemented: System detects legacy encodings and maps them to modern encoder formats
Automatic password upgrade (lazy rehash): On successful login:
Detect legacy encoding
Re-encode using current encoder
Persist updated hash transparently
The work will be done by the newbies squad under the mentorship of @dkayiwa and is targeted for delivery before August 31, 2026. Every Monday a blog will be shared on the progress and a presentation on the progress during the platform call. See you there and feel free to share your inputs
I’m excited to announce that we have officially started work on the Password Authentication Modernization project.
As many of you are aware, OpenMRS’s password authentication system has remained largely unchanged since 2009. While it continues to function, it lacks support for modern security features such as configurable work factors, hash iterations, and integration with Spring Security’s PasswordEncoder abstraction. Following the recent community discussions around reviving this initiative, we have structured this as a focused development effort with a dedicated team of Newbies.
Project Scope
Our work is strictly limited to the following areas:
Argon2id Password Encoder – Implementing a secure, production-ready Argon2id encoder using Spring Security, with configurable work factors (memory, iterations, parallelism) to suit different deployment environments.
Legacy Hash Detection – Identifying and validating passwords hashed using the old OpenMRS algorithm (SHA-512 without salt/iterations) to ensure existing users can continue logging in without interruption.
Automatic Lazy Rehash – On successful login with a legacy password, the system will transparently re-encode and persist the hash using the modern Argon2id encoder. This enables incremental, zero-downtime migration of all active users.
Deterministic Bootstrap Password – A secure password derivation mechanism (userUUID + systemSalt) for initial provisioning and controlled resets, eliminating the need to store temporary passwords.
Collaboration with the Auth Framework
This project is running in parallel with the broader Authentication and Authorization Framework Rework initiative, which is handling the overall Spring Security integration. Our teams are closely coordinating to ensure seamless integration.
Timeline & Status
We are targeting to deliver before 31st August 2026.
Get Involved
We welcome community feedback and questions. If you have experience with Argon2id, or password migration strategies, we’d love to hear your insights.
We’ll provide regular updates as we progress through each milestone.
Acknowledgments
Special thanks to our mentor @dkayiwa and @ibacher@mseaton@burke@achachiez who provided guidance and scoped this project, and to the broader OpenMRS community for keeping this initiative alive.
Looking forward to delivering a more secure authentication experience for OpenMRS!
We may be able to upgrade to Spring Security by the end of August so the targeted delivery for password authentication re-work is a bit off, unless you can build it without Spring Security and integrate later.
Thank you @raff . Absolutely yes we are going to build it initially without relying on Spring Security, then it will be integrated later as soon as the Spring Security is ready.
Thanks @kpraise, for the revised project scope. To me it’s clear and straight to the point. we hope @raff and the team are able to upgrade to Spring on time so that we beat th 31st August deadline
Hello everyone! Here is our latest sprint blog on our journey from legacy password hashing to modern authentication in OpenMRS. We would appreciate your feedback and thoughts! Happy Sabbath and a Happy weekend too
Here is our latest