You can manage the authentication process in your application code using the authentication API provided by ArcGIS Maps SDK for Qt. This is the same API used by the Authenticator toolkit component, and gives you fine-grained control over the authentication process. When using the API rather than the toolkit, you are responsible for the code that handles authentication details.
Make sure to add the following include statement first in your .cpp file:
#include "Authentication/AuthenticationManager.h" Then use the AuthenticationManager as follows:
// Use the static ArcGISRuntimeEnvironment::authenticationManager() method to get the object // responsible for issuing authentication challenges and managing credential stores. AuthenticationManager* authenticationManager = ArcGISRuntimeEnvironment::authenticationManager(); The AuthenticationManager provides:
- Credential stores for your application to hold ArcGIS and network credentials that are automatically checked when your application attempts to connect to secure resources. These stores can be persisted in a keychain so that user does not have to sign in again when the application is re-launched. For more information, see Create and store credentials.
- ArcGIS and network challenge handlers that allow your application to respond to the authentication challenges. For example, you can write code to present the user with a login screen and then continue to authenticate with those credentials. For more information, see Handle authentication challenges.
Handle authentication challenges
If your application attempts to access a secure resource and there is no matching credential in the credential store, an authentication challenge is raised:
ArcGISAuthenticationChallengeis raised if the ArcGIS secured resource requires OAuth or ArcGIS Token authentication.NetworkAuthenticationChallengeis raised if the ArcGIS secured resource requires network credentials, such as Integrated Windows Authentication (IWA) or Public Key Infrastructure (PKI).
You can catch and respond to these authentication challenges using the ArcGISAuthenticationChallengeHandler and NetworkAuthenticationChallengeHandler, respectively. These are functional interfaces that each implement a single abstract method called handle and handle respectively. Instead of creating a class that implements the interface, you can use a lambda expression.
ArcGIS authentication challenge handler
The ArcGISAuthenticationChallengeHandler is used to handle authentication challenges from ArcGIS secured resources that require OAuth or ArcGIS Token authentication. Handle the challenge using any of the following options:
continue- Handles the challenge with the specified credential.With Credential continue- Handles the challenge without a credential, causing it to fail with the original authentication errorAnd Fail cancel- Cancels the request that initiated the challenge.cancel- Cancels the request with the error that resulted from the failure to obtain a token (for example). Using this method will determine if the challenge should be reattempted and send another challenge automatically if needed.With Error
It is recommended to use RAII techniques to delete challenges after sending a response. All challenges are owned by the handler, and persist until the handler is deleted.
The following pseudo-code shows the generic steps to override the ArcGIS:
// Helpful reference docs: // https://developers.arcgis.com/qt/cpp/api-reference/esri-arcgisruntime-authentication-arcgisauthenticationchallengehandler.html#handleArcGISAuthenticationChallenge // https://developers.arcgis.com/qt/cpp/api-reference/esri-arcgisruntime-authentication-arcgisauthenticationchallenge.html#continueWithCredential // https://doc.qt.io/qt-6/qobject.html#deleteLater class MyCustomChallengeHandler : public ArcGISAuthenticationChallengeHandler { public: MyCustomChallengeHandler(QObject* parent) : ArcGISAuthenticationChallengeHandler(parent) { } ~MyCustomChallengeHandler() override = default; private: void handleArcGISAuthenticationChallenge(ArcGISAuthenticationChallenge* challenge) override { ArcGISCredential* credential; // create appropriate credential here challenge->continueWithCredential(credential); challenge->deleteLater(); } }; Network authentication challenge handler
The NetworkAuthenticationChallengeHandler is used to handle authentication challenges from ArcGIS secured resources that require network credentials, such as Integrated Windows Authentication (IWA) or Public Key Infrastructure (PKI). Handle the challenge using any of the following options:
continue- Handles the challenge with the specified credential.With Credential continue- Handles the challenge without a credential, causing it to fail with the original authentication errorAnd Fail cancel- Cancels the request that initiated the challenge.cancel- Cancels the request with an error that resulted from the failure to obtain a token (for example). Using this method will determine if the challenge should be reattempted and send another challenge automatically if needed.With Error
It is recommended to use RAII techniques to delete challenges after sending a response. All challenges are owned by the handler and persist until the handler is deleted.
The following pseudo-code shows the generic steps to override the Network:
// Helpful reference docs: // https://developers.arcgis.com/qt/cpp/api-reference/esri-arcgisruntime-authentication-networkauthenticationchallengehandler.html#dtor.NetworkAuthenticationChallengeHandler // https://developers.arcgis.com/qt/cpp/api-reference/esri-arcgisruntime-authentication-networkauthenticationchallenge.html#continueWithCredential // https://doc.qt.io/qt-6/qobject.html#deleteLater class CustomNetworkChallengeHandler : public NetworkAuthenticationChallengeHandler { public: CustomNetworkChallengeHandler(QObject* parent) : NetworkAuthenticationChallengeHandler(parent) { } ~CustomNetworkChallengeHandler() override = default; private: void handleNetworkAuthenticationChallenge(NetworkAuthenticationChallenge* challenge) override { NetworkCredential* credential; // create appropriate credential here... challenge->continueWithCredential(credential); challenge->deleteLater(); } }; Create and store credentials
When an authentication challenge is raised, your application can create a credential that is held in the ArcGIS and network credential stores provided by the AuthenticationManager.
ArcGISCredentialStorestores ArcGIS credentials.NetworkCredentialStorestores Network credentials.
These credential stores exist for the lifetime of the application. They ensure that an authentication challenge is only raised if a matching credential does not exist in the store.
During application sign-out, you should revoke all tokens and clear all credentials from the credential stores using the functions ArcGIS and Network.
// Use the static ArcGISRuntimeEnvironment::authenticationManager() method to get the // authentication manager which is responsible for issuing authentication challenges // and managing credential stores. AuthenticationManager* authenticationManager = ArcGISRuntimeEnvironment::authenticationManager(); // Get the ArcGIS credential store from the authentication manager. ArcGISCredentialStore* arcGISCredentialStore = authenticationManager->arcGISCredentialStore(); // Remove all of the credentials from the ArcGIS credential store. arcGISCredentialStore->removeAll(); // Get the network credential store from the authentication manager. NetworkCredentialStore* networkCredentialStore = authenticationManager->networkCredentialStore(); // Remove all of the credentials from the network credential store. QFuture<void> qFutureVoid = networkCredentialStore->removeAllAsync();