Secured services

Version 3.7

There are a few ways to handle security when working in applications built with the ArcGIS API for Flex. Three methods used to manage user and/or app logins are as follows:

  1. OAuth2-based authentication
  2. Token-based authentication
  3. HTTP/Windows-based authentication

These methods can be applied to various platforms, these platforms can be thought of as either:

  • A secured ArcGIS Server service that works with token-based authentication, or
  • ArcGIS Online or a Portal for ArcGIS installation and any of its associated services.

User versus app logins

As a developer using the ArcGIS platform, you can build the following two types of applications:

  • Applications that target end users of the ArcGIS platform. These applications need to allow users to login to the platform via the application. These types of logins are known as user logins.
  • Applications that target end users who are unknown to the ArcGIS platform. These applications need to login to the platform on behalf of the application. These kinds of logins are known as app logins.

User logins

User logins are probably the more familar of the two as this is what ArcGIS Server's existing token-based authentication uses with the generateToken REST API call . If an application tries to access a secured service, it requires a valid token to unlock the service. For example, a web application that accesses a secure service can be configured to prompt a user for their user name and password credentials. This specific end user would need to have permission set with the platform so that their credentials can unlock this service. This user login is known to the platform; in this scenario, the platform is a secured ArcGIS Server service.

Managing users and their roles can be handled various ways in ArcGIS Server. Please see the Configuring ArcGIS Server Security top for additional information regarding how this works.

App logins

When working with app logins, the application code logs into the platform on behalf of itself. Simply stated, an application registered with can log in regardless of who is accessing it. This is useful when it is not necessary to have users directly log in to access an application. This can be the case in circumstances where you may not know all of the end users accessing the application. You just need to make certain they have access to and the resources within it. You will want to be cognizant of how the application is being used to avoid any misuse since anyone can access it. This will be discussed further in the OAuth2 authentication section below.

OAuth2-based authentication

Beginning with version 3.5, support for OAuth2 authentication is provided directly in the ArcGIS for Flex API's Identity Manager. This built-in functionality handles a lot of the fine-grained work that you would typically have to do when implementing this type of authentication.

When working with OAuth2 authentication, the platform you work with is ArcGIS Online. If you have an organizational account, you are able to register applications with this platform. Please see the Adding items help topic for steps on how to do this.

When you register your application you need to add one or more redirect URIs. This is the URI of the app and the URI to which the token will be returned. Once you register your application with the platform, you will have an associated application ID (App ID) and application secret (App Secret). These can be viewed similarly as a user name and password where the App ID is open to the public and can be seen by everyone whereas the secret is kept confidential, similar to that of a password.

App registration in ArcGIS Online

The screen capture above displays the registered application's ID, type, and redirect URI's.

OAuth2-based authentication and user logins

When working with OAuth2-based authentication you can work with either user or app logins. Applications that support user logins use OAuth2 to allow end-users to log in to the ArcGIS platform via a login page. User login is performed in a single step which requires the application to direct the browser to the OAuth2 authorization URL for the portal, for example
client_id = "RRGuEoGwvId9cs0I"&
redirect_uri =

Once the user logs in, the application receives a token that it can use to access the platform on behalf of the user. The server returns a token by redirecting the browser to the specified redirect_uri. This token needs to be sent to the platform with all requests.

The default expiration time for the token returned by this approach is two hours. To request an token that is valid for a longer period provide an expiration time (in minutes) using the expires parameter. The maximum expiration time set by the platform will override the expiration time requested by the application.

The Identity Manager component simplifies the process of working with the token by appending the token in all requests and acquiring a new token when necessary. The OAuthInfo class contains information regarding the OAuth configuration such as the appID, expiration, locale, and portalURL. For additional information on this, see the reference.

For additional information on how to build a user login application, see the Web Map (OAuth) sample that provides the ability to work with the Identify Manager to log-in and access a web map in ArcGIS Online.

OAuth2-based authentication and app logins

Applications that target end users who are not known to the platform use application (app) logins to connect to the platform. In this case the application will login to the platform on behalf of itself and its end users will not be prompted for their credentials. Applications that use app logins must use both the OAuth2 AppID and AppSecret.

Malicious users that gain access to both the AppID and AppSecret can access billable services on, all of this billed to the application. Developers are responsible for keeping the AppSecret confidential. This implies that the application will need to have a server side application component that keeps the application credentials secure since client source code can be inspected.

The server-side application component that has access to the applications credentials can obtain a token using a single request by making a POST request to the portal's OAuth2 token endpoint with an OAuth2 grant_type value equal to client_credentials.
client_id = "RRGuEoGwvId9cs0I"&
client_secret = "this is where you would enter the app secret"&
grant_type = "client_credentials"

Successful authentication directly returns a JSON response containing the token that allows access to resources shared with it.

To get a better idea of how a server side component handles the process of storing credentials, acquiring the token, and appending it to all requests, view the resource proxy on GitHub. You will also want to review the Using the Proxy Page help topic for details on how to work with the proxy from an application built with the ArcGIS API for Flex.

View the Infographic or any of the other GeoEnrichment samples for an example of an application that uses a proxy to store the authentication information. This information is what is used to access the ArcGIS GeoEnrichment service used in the sample.

Token-based authentication

Token-based authentication services require that a token be included in each request for a map, query, etc. ArcGIS Server, ArcGIS Online and Portal for ArcGIS all support token-based authentication via a token service that can be used with both application and user logins. Upon successful authentication the token service returns a token that needs to be appended to all future requests.

The request to the token service must be made over HTTPS and all subsequent requests that use the token also need to be made over HTTPS if required by the resource.

Token-based authentication and user logins

Applications that support user logins are responsible for providing a login dialog that prompts users for their credentials. The application is responsible for keeping these credentials secure by transmitting them over HTTPS.

If you are building an application that accesses resources from ArcGIS Online, Portal for ArcGIS or services from ArcGIS Server 10.0 SP1 or later the recommended approach is to use the Identity Manager to handle the process of gathering the credentials and acquiring and using the token. To use the Identity Manager simply enable the Identity Manager component in your application.

import com.esri.ags.components.IdentityManager;
IdentityManager.instance.enabled = true;

Token-based authentication and app logins

Applications that access secured resources using token-based authentication can do so via an app login approach. This occurs when the user does not log in to the application by supplying credentials. Rather, a generic 'user' will need to be provisioned with a supplied user name and password. These credentials are then provided when making a request for a token to the token service.

Developers are responsible for keeping the credentials a secret, including from users who inspect browser source code using developer tools. This implies that the application will need to have a server side application component that keeps the application credentials secure.

One way to do this would be via a proxy server-side component. The proxy could be written to handle storing credentials, acquiring the token, and appending the token to all requests. View the resource proxy on GitHub for an example.

HTTP/Windows authentication

When a request is made to a service secured with HTTP authentication (including Windows authentication using IIS), the server issues an authentication challenge. The application or user must respond with appropriate user credentials using standard HTTP authentication methods.

The two approaches to accessing a secured service using HTTP/Windows authentication are as follows:

  • Use server-side code (ASP.NET, JSP, PHP, and so on) to set an identity for the request. The server sends the request with the identity; the end user does not need to log in. For more information, see Using the proxy page.
  • Do not supply any credentials within your application. Instead, let the server challenge the browser user. The user will see a login dialog box in the browser and must provide a valid user name and password for the ArcGIS Server system that issued the challenge. Work with your system administrator to ensure that end users have login information. For additional information on this, please see the ArcGIS Server help.

Additional Information

  • If HTTP Basic authentication is used, you should require that users employ HTTPS when accessing your application to prevent password interception. Other authentication methods, such as Digest or Integrated Windows Authentication, may protect user logins, but for maximum security, HTTPS is recommended when users are logging in.
  • Authentication is required only for the initial request to the secure service. This may result in a user encountering a login dialog box midway through a session. For example, if the user requests a nonsecure map, then tries to perform a query on a secure server, the login dialog box will appear only after the query. To avoid this, send a request in the background to the ArcGIS Server system when the application starts, such as a simple REST request for service information. The user would be prompted to log in on startup rather than when using the application.
  • Supplying end users with a user name and password is not appropriate when services from more than one ArcGIS Server system are used in an application, as multiple logins would be required. This limitation does not apply when using multiple services within the same ArcGIS Server system, since the challenge is issued for the entire server.
  • The ArcGIS API for Flex supports basic use of secured services from ArcGIS for Server 9.3 and above. There is no support for ArcIMS secured services.
  • If you are the administrator of an ArcGIS Server system, you can restrict access to your ArcGIS web services. Information on restricting access is available in the help documentation for ArcGIS for Server.
  • If working in Internet Explorer using client certification authorization, an additional line needs to be added to the HTML wrapper similar to what is displayed below.
    <script type="text/javascript"