Identity-aware proxies

An Identity-Aware Proxy (IAP) is a piece of software that generally operates as a reverse proxy, or as part of a piece of software that combines reverse proxy and load balancing capabilities. What makes this concept different from those standard architectural components is the role of the IAP in authenticating incoming requests, rather than relying exclusively on a backend system or external authentication pattern.


This topic almost exclusively applies to ArcGIS Enterprise, most ArcGIS Online workflows do not interact with an Identity-Aware Proxy directly, though external services or URLs added as items to ArcGIS Online could be protected in this fashion.

What is an IAP?

In most deployments where a reverse proxy or load balancer is used, the component operates largely in a transparent mode, meaning that requests from a client are not edited or changed by the proxy in a significant way, but are forwarded directly to the backend system, sometimes with the addition of a request header to identify to the backend system that the request was made through this proxy. In these architectures, authentication to an ArcGIS system for a user passing through the reverse proxy or load balancer is functionally identical to a user who is accessing the software directly without this intermediate layer.

When an IAP is used, the reverse proxy first checks whether the user is authenticated by looking for an authentication credential or object, such as a token, API key or site-specific cookie, and if it is not present or is invalid, any request to the backend system will immediately be redirected to an authentication provider or process based on the IAP configurations. Only after the user has authenticated properly through that identity provider, and is returned to the IAP interface with a valid security token or credential, will their request be forwarded to the backend system. Importantly, this security identifier is maintained outside the backend system, i.e. the backend system is usually unaware of the user’s IAP-negotiated session. Importantly, this means that in a scenario where ArcGIS Enterprise is placed behind an IAP, after the initial IAP-initiated login the user would need have to re-authenticate to the IdP specified by ArcGIS in order to establish a session with ArcGIS.


While many different software components and systems can be configured to support IAP-like functionality, some common examples include the following:

  • Microsoft Entra Application Proxy when configured for Pre-Authentication
  • Google Cloud Identity-Aware Proxy (IAP)
  • F5 BIG-IP Access Policy Manager
  • AWS Application Load Balancer with a listener rule that enforces authentication
  • Citrix NetScaler
  • Oracle Access Manager

Effectively, any reverse proxy which provides a “pre-authentication” layer, or which requires a token, cookie or other credential to pass through, can be considered an Identity-aware Proxy for the purposes of ArcGIS architecture discussions. Some IAPs are more, or less configurable, may allow exemptions for certain URLs, or may provide different authentication methods, ranging from simple forms-based login to OpenID Connect and SAML-based login options.

IAPs are often used to protect custom public-facing web applications and endpoints, where a user is primarily accessing a web application through a web browser and the requests to the backend APIs are on the same domain as the application, so an initial login can be reused by the user to make further requests. Some backend APIs may be developed to consume a header or other request property that passes through the IAP (like a signature that indicates the user’s username) and then use that information to affect API response content or logic.

Challenges introduced by IAPs

Most ArcGIS client applications, whether web, desktop, or mobile-based, initiate authentication to ArcGIS through OAuth. This process, which involves registering the client app with ArcGIS, initiating a login session, providing valid credentials, and then using the response code to generate a token, is consistent across each of these client types. This OAuth login process involves several different web pages or HTTP requests and usually occurs within an embedded browser (for native apps) or in the same browser window (for web apps).

The ArcGIS OAuth process, and specifically the in-app use of the resulting ArcGIS access token, assumes that the client has transparent access to the backend system. Said differently, ArcGIS clients only understand how to authenticate to ArcGIS systems – while the OAuth process in the browser may include sending the user to a SAML or OIDC identity provider, in the end the resulting OAuth code that is generated is what is returned to the user, and the additional browser window for native apps is closed. After the OAuth login is completed, the client expects to be able to send transparent HTTP requests (including the ArcGIS token) to ArcGIS Online or ArcGIS Enterprise endpoints for further use, any credential or session set by the IDP is no longer used or considered relevant to ArcGIS. In an IAP scenario, the IAP is constantly checking whether each incoming requester has previously been authenticated against the IAP, which can lead to several common issues.

In an ArcGIS OAuth login process, there are usually two configured properties that guide how to initiate the OAuth process: the client_id and the portal_url.

  • For applications accessing ArcGIS Online, this portal_url is usually or an organization-specific subdomain like
  • For ArcGIS Enterprise deployments, this portal_url is usually something like – including a domain name and a Web Context (/portal).

ArcGIS client application behavior generally approaches this process by first checking whether the configured URL is a valid ArcGIS Enterprise or ArcGIS Online system, by sending a request like (portal_url) + /sharing/rest/info?f=json`

This request returns a short JSON response that identifies the API version used, to ensure that the system is a supported version for that specific client application.

  1. When an ArcGIS application asks a user to provide an ArcGIS Enterprise URL to connect to, the initial request from the ArcGIS client to /sharing/rest/info?f=json will often return a 302 HTTP response redirecting the user to the IAP login page.

    This causes the ArcGIS client application to not accept the endpoint as valid, as it does not represent itself as an ArcGIS deployment but as ah HTML login page. This results in a denial as the client application is trying to prevent a malicious website from imitating an ArcGIS Enterprise deployment, such as someone using domain-misspelling techniques to request information or asking the user to enter their credentials into that site where they could be stolen and misused.

  2. For native apps, including ArcGIS Pro and ArcGIS mobile apps, the OAuth login is completed through an embedded browser, and while the IAP session may be successfully established in that browser, after that browser closes the cookie that is generally set (to identify the user as already having authenticated to the IAP) is lost, so the subsequent requests to ArcGIS initiated directly from the native application are blocked with a renewed 302 response.

Successful IAP implementation patterns

Several workflows can be successfully combined with IAP functionality when carefully designed.

  • Most workflows that exclusively occur in a desktop or mobile browser can be made to work with an IAP. This is because many IAPs use a session cookie to store the user’s status, and browsers are designed to maintain those cookies as well as re-send them on subsequent requests to the same hostname. In this case, as long as the web application launches a new tab or redirects the user to the IAP login page, the user will have a session established and future requests (to ArcGIS Enterprise, for example) will be able to traverse the proxy successfully.
  • A custom native mobile application may be configured to work successfully with an IAP or IAP-like capability, as the initial “pre-authentication” login can be written explicitly into the application and requests can be intercepted in a way that forces them to include a header, subscription key or cookie and transparently pass through the IAP.
  • Custom automation patterns such as Python Scripts or cloud-native automation or workflow tools may be written in a way that they can navigate the IAP authentication and communicate directly with the ArcGIS Enterprise system. The feasibility of this approach is highly subjective to the workflow and system desired.

Future support for use of IAPs with ArcGIS

While identity-aware proxies are clearly a fairly common class of application protection, there is currently little standardization or consistency across their implementations, which makes support for a broad set of IAP-like systems difficult to reliably implement. Esri is investigating future support for more IAP-based workflows from native applications and will seek to provide support in a commonly implementable, standards-based method that can be applied to many different software distributions in the future.