{"id":1085,"date":"2025-11-06T15:03:28","date_gmt":"2025-11-06T15:03:28","guid":{"rendered":"https:\/\/www.esri.com\/en-us\/software-engineering\/blog\/?post_type=blog&p=1085"},"modified":"2025-11-06T15:03:50","modified_gmt":"2025-11-06T15:03:50","slug":"lessons-from-swapping-out-our-authentication-system","status":"publish","type":"blog","link":"https:\/\/www.esri.com\/en-us\/software-engineering\/blog\/articles\/lessons-from-swapping-out-our-authentication-system","title":{"rendered":"Lessons from Swapping Out Our Authentication System"},"content":{"rendered":"\n

TL;DR<\/strong> – We learned many lessons from swapping out our authentication system in Qt Maps SDK with the shared API used by the ArcGIS Maps SDKs for Swift, Kotlin, and Flutter. What looked like a targeted migration became a complex project involving technical, logistical, and usability challenges. By implementing the new authentication system in parallel alongside the legacy system, we were able to ship when we were ready, keep quality high, and de-risk the rollout.\u00a0<\/p>\n\n\n\n

Backstory<\/h2>\n\n\n\n

If you\u2019ve been aware of ArcGIS Maps SDKs for Native Apps (formerly ArcGIS Runtime) for long enough, you\u2019ve likely heard us talk about our shared C++ Core <\/strong>(aka Core<\/em> or Runtime Core<\/em>); a single engine that powers multiple SDKs including Native Maps SDKs for .NET, Qt, Swift, Kotlin, and Flutter. Features are designed and implemented in Core, and each SDK team wraps Core to expose APIs using the conventions from their respective framework. Following this pattern keeps features and quality consistent while avoiding duplicated work. This architecture isn\u2019t without challenges, but it\u2019s been our secret sauce over the years for bringing ArcGIS to so many different platforms and frameworks, such as our recent roll-out of the brand new Flutter Maps SDK<\/a>.\u00a0<\/p>\n\n\n

\n
\"\"
Architecture of ArcGIS Maps SDK for Native Apps <\/figcaption><\/figure><\/div>\n\n\n

While the Core-first architecture works for most features, there are exceptions where an SDK team builds its own functionality outside of Core. Sometimes there are technical reasons, other times it\u2019s simply historical or resourcing related. Nevertheless, authentication was historically one of those outliers.\u202fThat changed in 2023 with the arrival of the new Native Maps SDKs for Swift and Kotlin. Faced with the prospect of writing two separate implementations for the new products, the group made a strategic decision: invest in a single, shared authentication API in Core.\u202fNot long after, the Native Maps SDK for Flutter joined the lineup. Thanks to the new Core API, it spun up its authentication system quickly, validating the decision.  <\/p>\n\n\n\n

Meanwhile, Qt Maps SDK had been using its same authentication system for nearly a decade. While it did the job, it was becoming challenging to add new features and fix bugs. Observing the successes of the Core innovations from the sidelines, our Qt team decided to align with this new pattern. This alignment would modernize our supported environments and workflows, reduce maintenance, improve quality, and unify behavior across Native Maps SDKs.  <\/p>\n\n\n\n

Now that you’ve seen how the Native Maps SDKs team values code reuse and support for many platforms, let’s zoom into the Qt Maps SDK team and see how we migrated to a new authentication system. We embraced many different techniques, from elegant object-oriented programming patterns to less-desirable, but pragmatic copy-paste efforts.  <\/p>\n\n\n\n

Setting the stage<\/h2>\n\n\n\n

We started planning in early 2024 with a major semantic release 300.0 on the horizon (targeting April 2026).  <\/p>\n\n\n\n

The goal<\/strong>: Implement and release the new Authentication API by version 300.0.\u00a0<\/p>\n\n\n\n

After an initial research spike and prototype, we quickly realized we could not make both systems work together, nor could we shim the old authentication system with the new system under the hood. While it would be great to avoid breaking changes for users, the two systems were too different, and we would regret merging the systems in the long run.\u00a0We could, however, have both systems exist side-by-side, allowing users to opt into the system of their choosing.<\/p>\n\n\n\n

With that initial information in place, we settled on the most important decision of the project: to build and release the new system alongside the legacy system<\/strong>. We then set forth the following principles:\u00a0<\/p>\n\n\n\n