Skip To Content

Use OAuth 2.0 authentication

In this topic

You may have used OAuth 2.0 to log on to third-party applications using a social network account, such as Twitter or Facebook. For general information about OAuth 2.0 in ArcGIS and how to use it in different scenarios, see OAuth 2.0 authentication.

As a developer using the ArcGIS platform, you can use OAuth 2.0 to build the following two types of apps:

  • Apps that target users of the ArcGIS platform—These apps allow users to log in to the platform via your app. These types of logins are known as user logins. In this scenario, your app redirects to a page that prompts the user for their ArcGIS Online user name and password, and uses their credentials to access content.
  • Apps that target users who are unknown to the ArcGIS platform—These apps need to log in to the platform for the user. These types of logins are known as app logins. In this scenario, your app accesses content using hard-coded credentials that belong to the app. This allows access to content to which the user otherwise would not have permission.

Authenticating with ArcGIS for Portal or an organization account for ArcGIS Online provides a way to license your ArcGIS Runtime SDK app at the Standard level. See the License your app topic for more details.

OAuth user logins

OAuth user logins allow app users to authorize themselves on an ArcGIS portal and access secured resources for which they have permission, without the app handling the user's credentials. User logins can be implemented in all types of apps: browser-based Web apps, server-based Web apps, device or tablet-based apps, and desktop apps. A Web app redirects the user to the login page on the remote server, while device, tablet, and desktop-based apps use client side browser controls to integrate this login experience into the app. Your app receives a unique alphanumeric string known as an authorization code in response to a successful login. An authorization code provides proof to the server that the user has authenticated successfully and allows access to resources for which the user has permission.

There are a few broad steps involved for implementing a user login with OAuth 2.0 in your ArcGIS Runtime app.

  1. Respond to attempts to access secured resources in your app. If credentials are available for the server that hosts the resource, they are included automatically, otherwise the user is challenged to authenticate.
  2. If needed, get an authorization code for the user by opening a browser window (or control) and directing the user to a portal URL where they can log in using their user name and password. The user's credentials are entered directly at the specified server endpoint, so your app does not handle the user's login information. Upon successfully logging in at the specified URL, your app receives an authorization code for the user.
  3. Use the authorization code to get a corresponding access token, which is used to return secured resources for which the user has permission. The identity manager handles this step for you, automatically obtaining and storing an access token once an authorization code is available. All requests for secured resources require the access token, which is automatically included when using the identity manager in your app.

Register servers with IdentityManager

The IdentityManagerclass abstracts some of the details of working with secured resources in your app, such as challenging the user for credentials when a secured resource is accessed, storing credentials when the user successfully authenticates, and automatically including credentials in requests for secured content when they are available.


IdentityManager is a singleton, which means there is always exactly one instance. You can get a reference to this instance in C++ using the instance method on the IdentityManager class, and use this instance to connect the signals and slots.

IdentityManager maintains a collection of servers for your app that require authentication for access to secured services. You can register a server with the identity manager using the server's URL and indicating what type of authorization should be used. For OAuth user or app logins, you need to provide additional information about the client app:

  • Client ID—An alphanumeric string that identifies the app on the server. See the Get Client ID and Client Secret section in this topic for instructions on creating a client ID for your app with ArcGIS Online.
  • Redirect URI—An address to which a successful authentication response is sent. For a server app, this might be the URL of a web service that can accept the authorization response. You can use the special value of urn:ietf:wg:oauth:2.0:oob to deliver the response to a portal URL (/oauth2/approval). This value is typically used by applications that don't have a web server or a custom URI scheme where the code can be delivered. When received by your app, the response is read from the authentication success page.

The following example instantiates UserCredentials with OAuthClientInfo to be used to generate an access token for a secured resource. The OAuth client information is configured with the user login authentication type EsriRuntimeQt::OAuthMode::User.

// Instantiate user credentials to be supplied to access a secure resource
  OAuthClientInfo clientInfo("CLIENT_ID", QString(), "REDIRECT_URI", OAuthMode::User);
  UserCredentials* credentials = new UserCredentials(this);

  // Add the credentials to the identity manager

When a request is made for a secured resource, the identity manager can see if the request is to one of its registered servers. If the user has already authorized with the server, the identity manager automatically includes the user credential with the request. Otherwise, the identity manager challenges the user for login information according to the authorization method that has been defined for the registered server.

Handle access to secured content

For OAuth, the aim is to prevent the app from having to deal directly with login information by directing the user to a login UI hosted on the server. Challenging the user for a login is handled by signals emitted from the identity manager. To handle OAuth user authorization, you must connect to the oAuthCodeRequired signal emitted from IdentityManager.

The following example connects to the identity manager's OAuth code challenge signal and responds with the appropriate authorization code.

// Connect from IdentityManager signal oAuthCodeRequired to a slot
  connect(IdentityManager::instance(), SIGNAL(oAuthCodeRequired(const QString& authorizationUrl)), 
  this, SLOT(onOAuthCodeRequired(const QString& authorizationUrl)));

// Slot for oAuthCodeRequired signal
void MyApplication::onOAuthCodeRequired(const QString& authorizationUrl)
  // Access URL in the authorizationUrl property to obtain auth code
  QString authCode = // …
  // Apply the auth code to the identity manager
  IdentityManager::setOAuthCodeForUrl(authorizationUrl, authCode);

If the user authorizes successfully, an access token is returned and stored with the identity manager.

An access token is an alphanumeric string that provides a key for accessing the platform on behalf of the user, and must be sent with all requests for secured content on the server. The IdentityManager instance manages access tokens for portals used by the app and automatically includes one when needed for requests made by ArcGIS Runtime components.

When a user authenticates with a portal, in addition to the access token, the identity manager receives and stores a refresh token. The refresh token is used to obtain a new access token when it expires. The identity manager automatically handles getting the new access token using the refresh token when needed.

Sign in and out

To sign out of a portal, you need to remove the credential stored with the identity manager or call signOut() on a Portal instance which removes the cached credential automatically.

OAuth app logins

If your app targets users unknown to the ArcGIS platform, the app can log in to the ArcGIS platform and access secured resources to which it has permission. Unlike the user logins described previously in this topic, your user will not be prompted with a UI to enter a login and password. Instead, your app is required to authenticate with the portal to receive an access token.

What does an app use to authenticate? The equivalent of user name and password for an app is Client ID and Client Secret. For an OAuth app login, your app needs to provide this information to the portal hosting the secured resources. As with a user login, your app receives an access token that the identity manager can use for working with secured resources.

Get a Client ID and Client Secret

Your app's Client ID and Client Secret are created by logging into your developer account at Click the Applications tab at the top of the page, and click New Application.

Provide a name, some identifying tags (to make your app searchable), a description, and optionally a redirect URI. After creating the app, click the OAuth Credentials tab to see the Client ID and Client Secret generated for you.


The name you provide for your app on does not need to match the name of your actual app. The information you provide when creating an app, such as the name, tags, description, and redirect URIs is essentially metadata and can be updated at any time. The Client ID and Client Secret are used by the server to uniquely identify your app and cannot be edited.

The Client ID is required for user logins, as described previously, as well as for app logins. Unlike user logins, however, an app login also requires that you provide the Client Secret.


With an app's Client ID and Client Secret, a user can access secured and billable content on It's therefore important that you keep your app's Client Secret a secret. Care must be taken to prevent malicious users from extracting the client secret from the application using developer tools. For most apps, this implies that the app must have a server side component that keeps these credentials secure and performs work on behalf of the app.

Get OAuth client credentials

Getting credentials with an OAuth app login works much the same way as for user logins. The only differences are:

  • Set the oAuthMode property on the OAuthClientInfo object to EsriRuntimeQt::OAuthMode::App.
  • Set the client secret property of the oAuthClientInfo property on the UserCredentials object to app's client secret.

Although it's possible to run code on the client that gets an app login using the Client ID and Client Secret, it's not recommended to do so due to security concerns. Remember that access to secured services by a malicious user may be billed to your app. This scenario is described in more detail in the topic App logins and OAuth 2.0 with some suggestions as to how to secure the Client Secret.

Qt WebEngine or WebView

If your app uses Qt's WebEngine or WebView controls to support the OAuth login UX, make sure that you include the necessary settings in your Qt Creator project file, add the header file includes, and initialize the WebEngine.

  1. Within the project's *.pro file, add the following lines to include the webengine module if it is supported.
    qtHaveModule(webengine) {
    QT += webengine
  2. In main.cpp include the QtWebEngine headers if they are available.
    #include <QtWebEngine>
  3. Later in your application, initialize the WebEngine before invoking any of the APIs or view components.

If you use Qt WebEngine in your Windows app, your deployed app may encounter a crash due to the Qt bug 42083 titled WebEngine deployment issue on Windows. Please see the bug report for a discussion and possible work-around for this issue.