Access services with OAuth credentials

Before starting this tutorial:

1. You need an ArcGIS Location Platform or ArcGIS Online account.

2. Your system meets the system requirements.

3. The ArcGIS Maps SDK for Qt, version 300.1.0 or later is installed.

4. The Qt 6.8.2 software development framework or later is installed.

5. The CMake build system is installed.

Option 1: Develop the code

Create a new ArcGIS Maps Qt Creator Project

1. Start Qt Creator.

2. In the top menu bar, click File > New Project.

3. In the New Project dialog, in the left frame, under Projects, select ArcGIS. Then select the ArcGIS Maps 300.1.0 Qt Quick C++ app project template (or a later version) and click Choose. This will launch the template wizard.

4. In the Project Location template, name your project AccessServicesWithOAuth. You can specify your own “create in” location for where the project will be created or leave the default. Click Next.

5. In the Define Build System template, keep the default choice of CMake for your build system. Click Next.

6. In the Define Project Details template, give this app a description or leave as is. For the GeoView type dropdown menu, select 2D Map. For the ArcGIS Online Basemap dropdown menu, select Topographic. Do not supply an API Key (also called an access token); leave it blank. We will be using OAuth for the project to access secured web mapping services, this will be discussed in a later section. Click Next.

7. In the Kit Selection template, check on the kit you previously set up when you installed Qt (Desktop Qt 6.8.2 MSVC2022 64bit or higher required). Click Next.

8. In the Project Management template, the option to Add as a subproject to root project is only available if you have already created a root project. If you have a version control system set up, you can select it in the dropdown but it is not needed to complete this tutorial. Click Finish to complete the template wizard.

9. Close any open files as a result of the creation of the new Qt project process.

Add a map

Use the map view A map view is a user interface that displays map layers and graphics in 2D. It controls the area (extent) of the map that is visible and supports user interactions such as pan and zoom. Learn more to display a map A map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. Learn more centered on the Santa Monica Mountains in California. The map will contain a layer built from the ArcGISTopographic BasemapStyle.

In the project AccessServicesWithOAuth > AccessServicesWithOAuth > Header Files folder of Qt Creator, double-click the AccessServicesWithOAuth.h file to open it. Add the declaration void setupViewpoint(); under private: section. Then save the file.

private:
    Esri::ArcGISRuntime::MapQuickView* mapView() const;
    void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);

    void setupViewpoint();

    Esri::ArcGISRuntime::Map* m_map = nullptr;
    Esri::ArcGISRuntime::MapQuickView* m_mapView = nullptr;

In the project AccessServicesWithOAuth > AccessServicesWithOAuth > Source Files folder of Qt Creator, double-click the AccessServicesWithOAuth.cpp file to open it. Add the following #include statements. Then save the file.

#include "AccessServicesWithOAuth.h"

#include "Map.h"
#include "MapQuickView.h"
#include "MapTypes.h"

#include "ArcGISMapImageLayer.h"
#include "LayerListModel.h"
#include "Point.h"
#include "Portal.h"
#include "PortalItem.h"
#include "SpatialReference.h"
#include "Viewpoint.h"

#include <QFuture>

Create the view point

Staying in the AccessServicesWithOAuth.cpp file, add code to implement the setupViewpoint method. This method creates a center Point based on a SpatialReference along with longitude and latitude. It also creates a Viewpoint based on center and sets scale. Lastly, it asynchronously sets the initial Map viewpoint.

The center Point and scale value keep the initial Viewpoint centered and focused on the Santa Monica Mountains. The scale value sets the level of detail to focus on the area of interest.

The spatial reference A spatial reference is a set of parameters, typically defined by a WKID, that define the coordinate system and spatial properties for geographic data. Applications use a spatial reference to correctly display the position of geographic data in a map or scene. Learn more created above is set to use World Geodetic System 1984 (WGS84), the spatial reference commonly used for GPS, and it has the well known id 4326. To learn more, see Spatial References in the ArcGIS Maps SDK for Qt Guide.

MapQuickView *AccessServicesWithOAuth::mapView() const
{
    return m_mapView;
}

void AccessServicesWithOAuth::setupViewpoint()
{

    const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
    const Viewpoint viewpoint(center, 100000.0);

    m_mapView->setViewpointAsync(viewpoint);

}

Add the following line of code to call setupViewpoint. Then save the file.

// Set the view (created in QML)
void AccessServicesWithOAuth::setMapView(MapQuickView *mapView)
{
    if (!mapView || mapView == m_mapView) {
        return;
    }

    m_mapView = mapView;
    m_mapView->setMap(m_map);

    setupViewpoint();

    emit mapViewChanged();
}

Add the secured traffic layer

The ArcGIS World Traffic service is a dynamic map service that presents historical and near real-time traffic information for different regions of the world. This service requires an ArcGIS Online organizational subscription. You will add a portal item referencing this service, and create a traffic layer from that.

ArcGIS World Traffic service data is updated every five minutes to provide traffic speed and traffic incident visualization and identification. Traffic speeds are displayed as a percentage of free-flow speeds, which is frequently the speed limit or how fast cars tend to travel when unencumbered by other vehicles. The streets are color coded as follows:

• Green (fast): 85 - 100% of free flow speeds
• Yellow (moderate): 65 - 85%
• Orange (slow); 45 - 65%
• Red (stop and go): 0 - 45%

Staying in the AccessServicesWithOAuth.cpp file, add code to create a Portal that will use the boolean true which forces the login to occur to gain access to the secured ArcGIS World Traffic service.

void AccessServicesWithOAuth::setupViewpoint()
{

    const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
    const Viewpoint viewpoint(center, 100000.0);

    m_mapView->setViewpointAsync(viewpoint);

    // Create a new portal using the boolean `true` which forces the login to occur.
    constexpr auto loginRequired = true;
    Portal* portal = new Portal(loginRequired, this);

}

Now add code to create a PortalItem using the traffic service’s item ID An item ID is a unique identifier representing a single item stored, managed, and accessed in a portal, such as a web map, hosted layer, or file. Learn more . Then create an ArcGISMapImageLayer to display the traffic service. Finally, append the traffic layer to the map’s collection of data layers (operational layers). Then save the file.

void AccessServicesWithOAuth::setupViewpoint()
{

    const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
    const Viewpoint viewpoint(center, 100000.0);

    m_mapView->setViewpointAsync(viewpoint);

    // Create a new portal using the boolean `true` which forces the login to occur.
    constexpr auto loginRequired = true;
    Portal* portal = new Portal(loginRequired, this);

    // Create a new portal item using the inputs of: a portal and the String ID for the
    // ArcGIS World Traffic service. This causes the OAuth challenge to occur.
    PortalItem* portalItem = new PortalItem(portal, "ff11eb5b930b4fabba15c47feb130de4", this);

    // Create a new ArcGIS map image layer using the input of the portal item.
    ArcGISMapImageLayer* arcGISMapImageLayer = new ArcGISMapImageLayer(portalItem, this);

    // Append the traffic layer to the map's data layer collection.
    m_map->operationalLayers()->append(arcGISMapImageLayer);

}

Configure the CMakeLists.txt file

The CMakeLists.txt file contains information required by CMake to build an application, a library, or a plugin. To utilize the Authenticator control, you will need to set the path to where the root directory of the ArcGIS Maps SDK for Qt Toolkit is located on your development system.

In the project AccessServicesWithOAuth folder of Qt Creator, double-click the CMakeLists.txt file to open it. Remove the following CMake statements, we will add some more robust statements in its place next.

target_link_libraries(${PROJECT_NAME} PRIVATE
  Qt6::Core
  Qt6::Quick
  Qt6::Multimedia
  Qt6::Positioning
  Qt6::Sensors
  Qt6::WebSockets
  ArcGISRuntime::Cpp)

# To integrate the toolkit, copy the `toolkitcpp` and the `common` subdirectories from the toolkit
# into your project's directory. Then uncomment the following lines to add it to your project.
# See https://github.com/Esri/arcgis-maps-sdk-toolkit-qt for details
# add_subdirectory(toolkitcpp)
# target_link_libraries(${PROJECT_NAME} PRIVATE libtoolkitcpp)

Now add the following CMake statements and set the correct path for the ARCGIS_TOOLKIT_REPOSITORY variable (for example: C:/applications/arcgis-maps-sdk-toolkit-qt). These new statements will copy the necessary directories from the ArcGIS Maps SDK for Qt Toolkit into the tutorial project location for compilation. Then save the file.

target_link_libraries(${PROJECT_NAME} PRIVATE
  Qt6::Core
  Qt6::Quick
  Qt6::Multimedia
  Qt6::Positioning
  Qt6::Sensors
  Qt6::WebSockets
  ArcGISRuntime::Cpp)

# TODO: Replace the <path_to_toolkit_repo> with a valid location where the Qt Toolkit
# root directory resides on your system, example: C:/applications/arcgis-maps-sdk-toolkit-qt

set(ARCGIS_TOOLKIT_REPOSITORY "<path_to_toolkit_repo>")

if(NOT "${ARCGIS_TOOLKIT_REPOSITORY}" STREQUAL "<path_to_toolkit_repo>")
  set(TOOLKIT_SOURCE_DIR "${ARCGIS_TOOLKIT_REPOSITORY}/uitools/toolkitcpp")
  set(COMMON_SOURCE_DIR "${ARCGIS_TOOLKIT_REPOSITORY}/uitools/common")

  if(NOT EXISTS "${TOOLKIT_SOURCE_DIR}/CMakeLists.txt" OR
     NOT EXISTS "${COMMON_SOURCE_DIR}/CMakeLists.txt")
    message(FATAL_ERROR
      "ARCGIS_TOOLKIT_REPOSITORY must contain uitools/toolkitcpp and uitools/common")
  endif()

  add_subdirectory(${TOOLKIT_SOURCE_DIR} toolkitcpp)
  target_link_libraries(${PROJECT_NAME} PRIVATE libtoolkitcpp)
endif()

Implement user authentication using OAuth credentials

The OAuth sign in web page is implemented using the Authenticator class and the Qt WebView, which is part of the ArcGIS Toolkit.

In the project Display_a_map > Display_a_map > Source Files folder of Qt Creator, double click the main.cpp file to open it., add #include statements for QtWebView and register.h for the Toolkit.

#include "AccessServicesWithOAuth.h"

#include "ArcGISRuntimeEnvironment.h"
#include "MapQuickView.h"

#include <QDir>
#include <QGuiApplication>
#include <QQmlApplicationEngine>


#include <QtWebView>
#include "Esri/ArcGISRuntime/Toolkit/register.h"

Add code to initialize QtWebView.

int main(int argc, char *argv[])
{

    // Initialize the QtWebView to use the web based login dialog.
    QtWebView::initialize();

Add code to register the Toolkit. Then save the file.

    // Initialize application view
    QQmlApplicationEngine engine;

    // Register the toolkit
    Esri::ArcGISRuntime::Toolkit::registerComponents(engine);

In the project AccessServicesWithOAuth > AccessServicesWithOAuth > Resources > ../qml > qml.qrc > /qml folder of Qt Creator, double click the AccessServicesWithOAuthForm.qml file to open it. Add an import statement for the Toolkit.

import QtQuick
import QtQuick.Controls
import Esri.AccessServicesWithOAuth

import Esri.ArcGISRuntime.Toolkit

Now that the toolkit is available, declare an Authenticator component. Then save the file.

    // Declare the C++ instance which creates the map etc. and supply the view
    AccessServicesWithOAuth {
        id: model
        mapView: view
    }

    // Declare an Authenticator to support login.
    Authenticator {
        anchors.centerIn: parent
    }

NOTE: The Authenticator is a Toolkit component that simplifies the authentication workflow to automatically display the correct login user interface for each security method (Token, OAuth, PKI, and so on).

Create an OAuth user configuration

Using the Redirect URL and Client ID information obtained from the earlier prerequisites section Create OAuth credentials for user authentication in the tutorial when creating your OAuth credentials, you will create a new OAuthUserConfiguration object. This object is used as the input for the Qt Toolkit OAuthUserConfigurationManager to make use of the Qt WebView based login dialog.

In the project AccessServicesWithOAuth > AccessServicesWithOAuth > Source Files folder of Qt Creator, double-click the AccessServicesWithOAuth.cpp file to open it. Add #include statements for the required header files as shown.

#include "AccessServicesWithOAuth.h"

#include "Map.h"
#include "MapQuickView.h"
#include "MapTypes.h"

#include "ArcGISMapImageLayer.h"
#include "LayerListModel.h"
#include "Point.h"
#include "Portal.h"
#include "PortalItem.h"
#include "SpatialReference.h"
#include "Viewpoint.h"

#include <QFuture>

#include "OAuthUserConfigurationManager.h"

#include "Authentication/OAuthUserConfiguration.h"

Add another namespace statement as shown.

using namespace Esri::ArcGISRuntime;

using namespace Esri::ArcGISRuntime::Authentication;

In the setupViewpoint function, add the following code to create a OAuthUserConfiguration object. Replace the “REDIRECT_URL” and “CLIENT_ID” placeholders strings (created earlier in this tutorial in the section Create OAuth credentials for user authentication).

void AccessServicesWithOAuth::setupViewpoint()
{

    const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
    const Viewpoint viewpoint(center, 100000.0);

    m_mapView->setViewpointAsync(viewpoint);

    // Define the Redirect URL string obtained when creating the OAuth credentials.
    // TODO: You need to replace the "REDIRECT_URL" with your own valid string,
    // ex: "urn:ietf:wg:oauth:2.0:oob"
    const auto qStringRedirectUrl = QString{"REDIRECT_URL"};

    // Define the URL of the portal to authenticate with.
    const QUrl qUrlPortal = QUrl{"https://www.arcgis.com/"};

    // Define a unique identifier associated with an application registered with the
    // portal that assists with client/server OAuth authentication.
    // TODO: You need to replace the "CLIENT_ID" with your own valid string.
    const QString qStringClientId = QString{"CLIENT_ID"};

    // Create a new OAuth user configuration using: the Url to ArcGIS online, the Client ID
    // string, and the Redirect Url string.
    auto* oAuthUserConfiguration = new OAuthUserConfiguration(qUrlPortal, qStringClientId,
                                                              qStringRedirectUrl, this);

    // Call the Toolkit's OAuthUserConfigurationManager static `addConfiguration`
    // method to use the OAuth dialog. This will require the input of a valid username/password.
    Toolkit::OAuthUserConfigurationManager::addConfiguration(oAuthUserConfiguration);

    // Create a new portal using the boolean `true` which forces the login to occur.
    constexpr auto loginRequired = true;
    Portal* portal = new Portal(loginRequired, this);

    // Create a new portal item using the inputs of: a portal and the String ID for the
    // ArcGIS World Traffic service. This causes the OAuth challenge to occur.
    PortalItem* portalItem = new PortalItem(portal, "ff11eb5b930b4fabba15c47feb130de4", this);

    // Create a new ArcGIS map image layer using the input of the portal item.
    ArcGISMapImageLayer* arcGISMapImageLayer = new ArcGISMapImageLayer(portalItem, this);

    // Append the traffic layer to the map's data layer collection.
    m_map->operationalLayers()->append(arcGISMapImageLayer);

}

Press Ctrl + R to run the app.

The app will open and you should see the Sign In prompt you for to enter your ArcGIS Online Username and Password for the Authenticator Qt Toolkit control. When entered, click the Sign In button.

After authenticating successfully with ArcGIS Online, a map with the topographic basemap layer centered on the Santa Monica Mountains in California. The map will appear with the traffic layer also displayed.

Option 2: Download the solution

Click the Download solution link on this page under the Solution title and unzip the file to a location on your machine.

In Qt Creator, choose File > Open File or Project… from them menus. In the Open file dialog, navigate to the CMakeLists.txt file for the solution you unzipped and click the Open button.

The Configure Project window will appear for you to specify the Qt Kit to use to compile the project. Check on the Qt Kit called Desktop Qt 6.8.2 MSVC2022 64bit before clicking the Configure Project button at the bottom of the page.

Since the downloaded solution does not contain authentication credentials (API Key or User authentication), you must add the developer credentials that you created in the Set up authentication section.

Set path to the Qt Toolkit in the project

Ensure you have completed the prerequisites listed at the beginning of this tutorial. In particular, ensure you have done the step Download the ArcGIS Maps SDK for Qt Toolkit and have noted the path of the root directory of the ArcGIS Maps SDK for Qt Toolkit cloned repo that resides on your system (for example: C:/applications/arcgis-maps-sdk-toolkit-qt). The root directory will have the file README.md, the subdirectory \uitools, and more. To utilize Authenticator, you will need to know this information.

In the project AccessServicesWithOAuth folder of Qt Creator, double-click the CMakeLists.txt file to open it. Locate the line that sets the ARCGIS_TOOLKIT_REPOSITORY variable and specify the path of the root directory of the ArcGIS Maps SDK for Qt Toolkit cloned repo that resides on your system (for example: C:/applications/arcgis-maps-sdk-toolkit-qt). If this is not correct the OAuth dialog will not appear for you to enter your user credentials. Then save the file.

# TODO: Replace the <path_to_toolkit_repo> with a valid location where the Qt Toolkit
# root directory resides on your system, example: C:/applications/arcgis-maps-sdk-toolkit-qt

set(ARCGIS_TOOLKIT_REPOSITORY "<path_to_toolkit_repo>")

Set developer credentials in the solution

To allow your app users to access ArcGIS location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Static Maps service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more , use the developer credentials that you created in the Create OAuth credentials for user authentication step to authenticate requests for resources.

In the project AccessServicesWithOAuth > AccessServicesWithOAuth > Source Files folder of Qt Creator, double-click the AccessServicesWithOAuth.cpp file to open it. Set your values for the REDIRECT_URL and the CLIENT_ID strings. Then save the file.

// Define the Redirect URL string obtained when creating the OAuth credentials.
// TODO: You need to replace the "REDIRECT_URL" with your own valid string,
// ex: "urn:ietf:wg:oauth:2.0:oob"

const auto qStringRedirectUrl = QString{"REDIRECT_URL"};

// Define the URL of the portal to authenticate with.
const QUrl qUrlPortal = QUrl{"https://www.arcgis.com/"};

// Define a unique identifier associated with an application registered with the
// portal that assists with client/server OAuth authentication.
// TODO: You need to replace the "CLIENT_ID" with your own valid string.

const QString qStringClientId = QString{"CLIENT_ID"};

Press Ctrl + R to run the app.

The app will open and you should see the Sign In prompt you for to enter your ArcGIS Online Username and Password for the Authenticator Qt Toolkit control. When entered, click the Sign In button.

After authenticating successfully with ArcGIS Online, a map with the topographic basemap layer centered on the Santa Monica Mountains in California. The map will appear with the traffic layer also displayed.