Logging into the future: Introducing the Next Generation of Authentication in ArcGIS Maps SDK for Qt

ArcGIS Maps SDK 200.8 for Qt introduces a brand-new pattern for authenticating with ArcGIS. We offer this new pattern alongside our existing “legacy” authentication API and it is functionally equivalent, supporting Token, OAuth (app and user), SAML, IWA, and PKI workflows.  Some added benefits include a more explicit API that separates ArcGIS logins (Token, OAuth) and network logins (IWA, PKI), an external out-of-process browser login workflow with OAuth on mobile platforms, and an improved PKI login experience. In addition, the new authentication API utilizes the same underlying logic and design patterns used by the other ArcGIS Maps SDKs for Native Apps. This means you can expect better consistency in capabilities and improved quality and stability.

While you can continue to use the legacy system at 200.8, we recommend that you start to migrate as early as possible, because we have deprecated the legacy system and plan to remove it in version 300.0.

You may be asking the question, “So, what do I need to do to use the new authentication system?” First, you’ll need to opt out of the legacy system. To do this, you will need to add the following line of code prior to any outgoing network requests, ideally in the first few lines of the main.cpp. 

ArcGISRuntimeEnvironment::setUseLegacyAuthentication(false); 

Next, we recommend you use the Toolkit component Authenticator to respond to authentication challenges. Authenticator is a view component that automatically displays the proper UI for authenticating with ArcGIS, regardless of whether your organization uses OAuth, IWA, PKI, or some other system. Moreover, Authenticator provides a great user experience out of the box, requiring you to write virtually no client code.

To use Authenticator, follow the setup instructions in the Toolkit, and declare an Authenticator in your QML code: 

Authenticator { 
        anchors.centerIn: parent 
} 

And with just those two blocks of code, you have successfully started using the new authentication system.  

While Authenticator covers many common workflows with a default experience, you may have scenarios where your app code needs to manage and respond to authentication challenges on its own. The Security and Authentication guide topic explains several important concepts of the new system in detail. Instead of rehashing those, I will compare the two systems, which should aid in migration: 

• The new authentication system distinguishes between ArcGIS authentication and network authentication. ArcGIS authentication refers to OAuth and Token workflows, where users use an ArcGIS credential to sign in. Network authentication refers to technologies such as Integrated Windows Authentication (IWA) and Public Key Infrastructure (PKI), where authentication happens at the network level (such as through Windows Active Directory), which creates a streamlined login experience where users don’t need to maintain separate ArcGIS credentials. The legacy system doesn’t make a distinction between the two patterns, whereas the new system does. Therefore, developers can separately listen and respond to ArcGIS and network authentication challenges, resulting in a more explicit API for the different paradigms and options that go with them. 

• To respond to a challenge in the legacy system, you connect to the AuthenticationManager::authenticationChallenge signal. To respond to a challenge in the new system, you subclass ArcGISAuthenticationChallengeHandler or NetworkAuthenticationChallengeHandler and set it on Esri::ArcGISRuntime::Authentication::AuthenticationManager. 

• In the legacy system, the CredentialCache manages credentials from past requests. ArcGISCredentialStore and NetworkCredentialStore provide similar capabilities in the new system. 

• In the legacy system, developers can directly set a Credential preemptively on any object that implements the RemoteResource interface. The new system no longer supports this pattern, and instead, developers should create challenge handlers to respond to authentication challenges. 

Here are a few additional important tips to keep in mind with the new authentication system: 

• The new authentication system resides in a new namespace named Esri::ArcGISRuntime::Authentication. Importantly, there is a new Esri::ArcGISRuntime::Authentication::AuthenticationManager, which differs from the Esri::ArcGISRuntime::AuthenticationManager class.  

• All new authentication headers are in an “Authentication” include subfolder.  

• The new and legacy systems are mutually exclusive and cannot be intermixed. We’ve added header guards to prevent you from mixing the two systems.

• The legacy authentication system contains compile-time deprecation warnings. Ensure you’ve addressed all deprecation warnings as soon as possible to streamline upgrading to future versions of ArcGIS Maps SDK for Qt.

We intend to add numerous additional features in future releases, some of which include: 

• Identity Aware Proxy, to support technologies such as Microsoft Entra 

• Persistent Credential Store (e.g. Apple’s Keychain) 

• Custom HTTP requests using authentication 

• Additional PKI variations (dual PKI/OAuth authentication, smart cards, etc.) 

In summary, we’ve released the new authentication system in ArcGIS Maps SDK 200.8 for Qt alongside the legacy system. Along with functional equivalence, the new system introduces a more explicit API design, OAuth out-of-process browser logins on mobile, an improved PKI login experience, and improved product stability. We’ve provided a streamlined migration path with the Authenticator toolkit component, and we’ve updated our documentation, samples, and tutorials to showcase the new patterns in action. With this information, we hope you are inspired to start migrating your apps today.

Please reach out on Esri Community’s Qt Maps SDK Questions forum if you have any questions. Happy coding!