Access Secure Resources

Your application may need to access secured resources that are restricted to authorized users. For example, your organization may host private data layers or feature services that are only accessible by verified users. You may also need to take advantage of premium ArcGIS Online services, such as routing, that require secured user access. The ArcGIS platform provides many ways to secure access to your organization's content and services. The ArcGIS API for JavaScript provides full support for access to secured ArcGIS Enterprise and Online resources using the following authorization methods:

• OAuth 2.0: This secures delegated access to server resources.
• ArcGIS Tokens: This is Esri's proprietary token-based authentication mechanism.
• Network credential: HTTP secured service / Integrated Windows Authentication (IWA).

OAuth 2.0

OAuth 2.0 is a standard for handling authentication decisions among various web-enabled devices and server. The ArcGIS Platform determines user authenticity and a token is supplied to the client application. This token is then used in subsequent requests for secured resources. This is available in both ArcGIS Online and ArcGIS Enterprise version 10.3 and later and can be used with both user and application logins. Please refer to the What is OAuth 2.0 documentation for additional information.

ArcGIS Tokens

Token-based authentication services require that a token be included in each request for a secured resource. Both ArcGIS Online and ArcGIS Enterprise version 10.2 and later support token-based authentication that can be used with both user and application logins. Please refer to the About ArcGIS Tokens documentation for additional information.

Network Credential

HTTP/Windows Authentication via HTTP basic, HTTP digest, or Integrated Windows Authentication (IWA) resources are protected by username and password set on the service. Prompts are then provided by a browser popup or session cookie. When you use IWA, logins are managed through Microsoft Windows Active Directory. Users do not sign in and out of the portal website; instead, when they open the website, they are signed in using the same accounts they use to log in to Windows. For more information, refer to Integrated Windows Authentication with your portal.

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.

Both OAuth 2.0 and ArcGIS Tokens make use of the user login approach. In this pattern, users authorize your application to access content and services on their behalf. In this scenario your application prompts the user for their username and password and then uses their credentials to access content.

Implementing these security methods in your application can potentially be a lot of work. In the user login approach, the ArcGIS API for JavaScript provides classes to help simplify authentication and automate the process. Two primary classes are the IdentityManager and OAuthInfo classes (the latter if using the OAuth 2.0 approach). These classes, in addition to others, reside within the esri/identity namespace.

To use the IdentityManager simply include esri/identity/IdentityManager as part of your require statement. Once the application runs and requests a resource that is secure, the IdentityManager takes over and handles prompting the user for the appropriate credentials. Once the correct credentials are supplied, a token is generated and appended to the resource. In addition to this, it also takes care of refreshing the token as needed.

When using the OAuth approach, you will also need to add the OAuthInfo class and register it with the IdentityManager. The OAuthInfo class works with registered applications.

require (["esri/identity/OAuthInfo", "esri/identity/IdentityManager"], function(OAuthInfo, esriId) {
    var oAuthInfo = new OAuthInfo({
        appId: "<enter the registered app id here>"
    });
    esriId.registerOAuthInfos([oAuthInfo]);
});

For a working example of this, please refer to the Access ArcGIS Online items using OAuth 2.0 sample.

Application logins

There may be scenarios where you have secured resources but may not want your end users to have to log in to access them. In situations like this, application logins provide users access to content on your behalf. In this scenario, your application accesses content using hard-coded credentials belonging to either:

• A user that has access to these resources, or
• The registered application.

These credentials are saved within a proxy service. This allows the application to access content that the user may not have permission to access. No login prompts are needed since the credentials are already supplied via the credentials specified within the proxy file.

The proxy will need to be configured based on whatever authentication method used. For example, if working with a self hosted resource proxy and using OAuth 2.0, you would need to configure it with the clientId and clientSecret of the registered application. When accessing a secured ArcGIS tokens resource with a self hosted resource proxy, you must configure a valid username and password for a specified resource.

The only requirement within your application's code is to specify what URL should be proxied and then point to the correct location of the proxy file.

1. First, add esri/core/urlUtils to your require statement.
2. Next, specify the URL for the secured resource.
3. Lastly, specify the location to the proxy file.

require (["esri/core/urlUtils"], function(urlUtils) {
    urlUtils.addProxyRule({
        urlPrefix: "route.arcgis.com", // specify resource location
        proxyUrl: "/sproxy/" // specify location of proxy file
    });
});

For a working example of this, please refer to the Directions and RouteTask samples.

Additional resources

The following are additional resources that provide information on the various topics discussed above.

• Sample - Access ArcGIS Online items using OAuth 2.0: OAuth 2.0 named user login approach
• Sample - Directions widget: Application login approach (can use either OAuth 2.0 or ArcGIS Tokens authentication with this)
• Sample - RouteTask: Application login approach (can use either OAuth 2.0 or ArcGIS Tokens authentication with this)
• API Reference - IdentityManager
• API Reference - OAuthInfo
• Working with the ArcGIS Platform