Authentication API

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:

Use dark colors for code blocksCopy
#include "Authentication/AuthenticationManager.h"

Then use the AuthenticationManager as follows:

Use dark colors for code blocksCopy
    // 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:

ArcGISAuthenticationChallenge is raised if the ArcGIS secured resource requires OAuth or ArcGIS Token authentication.
NetworkAuthenticationChallenge is 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 handleArcGISAuthenticationChallenge and handleNetworkAuthenticationChallenge 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:

continueWithCredential - Handles the challenge with the specified credential.
continueAndFail - Handles the challenge without a credential, causing it to fail with the original authentication error
cancel - Cancels the request that initiated the challenge.
cancelWithError - 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.

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 ArcGISAuthenticationChallengeHandler:

Use dark colors for code blocksCopy
// 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:

continueWithCredential - Handles the challenge with the specified credential.
continueAndFail - Handles the challenge without a credential, causing it to fail with the original authentication error
cancel - Cancels the request that initiated the challenge.
cancelWithError - 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.

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 NetworkAuthenticationChallengeHandler:

Use dark colors for code blocksCopy
// 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.

ArcGISCredentialStore stores ArcGIS credentials.
NetworkCredentialStore stores 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 ArcGISCredentialStore::removeAll() and NetworkCredentialStore::removeAllAsync().

Use dark colors for code blocksCopy
    // 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();