Security and authentication

Authentication is used to keep corporate and network data secure and ensure that only valid, authenticated users can access private information. Your application or its users are required to authenticate their credentials through a qualified, compatible ArcGIS platform such as ArcGIS Online or ArcGIS Enterprise whenever attempting to:

• Access private user or corporate-owned information.
• Create, edit, or publish content.
• Access premium (payment-secured) web content or services.

You must implement an authentication method in order to grant your app's users access to secured resources. The authentication method you decide to implement might vary based upon the resources required by your application. Esri's preferred authentication methods are:

• ArcGIS identity (OAuth 2.0): This method obtains user credentials and authentication through an ArcGIS platform sign-on, and the platform responds with an OAuth 2.0 access_token to the client app. The app uses this token in all subsequent requests to the platform. This is the recommended method, and is most commonly used with ArcGIS Online and ArcGIS Enterprise.

• API key: This unique identifier is used to authenticate a user, developer, or calling program to an API, although most typically used to authenticate a project rather than a human user.

ArcGIS identity

When your app requires access to user content or if you are distributing your app through ArcGIS Marketplace, you should implement OAuth 2.0 to obtain an ArcGIS identity. This allows individual users to authorize your app to use the content and services to which that user has been granted access.

• Users sign in with their ArcGIS Online or ArcGIS Enterprise accounts via OAuth 2.0
• Tokens expire and require re-authentication or a refresh token call
• Tokens can be short-lived or long-lived depending on use cases
• Cross-functional: Can be used with browsers, devices, or servers
• Tokens can be used to access both:
  • Location services
  • Any ArcGIS Online or Enterprise content shared with the user

Learn more about ArcGIS identity.

API keys

API keys allow access to location services with a permanent key that can be restricted to specific services and included in public applications.

• Permanent access keys
• Used for accessing specific location services
• Restricted to specific referrer headers
• ArcGIS Developer accounts can use API keys to access their own (read only) private content

Choose an authentication method

The choice of which type of authentication to implement is mostly dependent upon the resources required by your application. Also consider the strengths and limitations of the API or SDK technology on which your application is built.

In general, it is recommended that you use:

• API keys if your application needs to access location services from Esri.
• ArcGIS identity if users of your application will authenticate with their ArcGIS Online or ArcGIS Enterprise accounts.

Your choice of authentication method is also affected by the API with which you build your application. ArcGIS APIs contain a built in IdentityManger or AuthenticationManager, which provide helper methods and patterns for implementing ArcGIS identity workflows.

Authentication manager

ArcGIS APIs contain a built authentication manager, which provides helper methods and patterns for implementing ArcGIS identity workflows.

Set a central authentication challenge handler that will allow your users to authenticate with secured services

The DefaultAuthenticationChallengeHandler class can take care of showing an authentication dialog for all types of security that ArcGIS supports (including OAuth and certificates, read more below about each of these options), allowing users to provide credentials or choose a certificate (as appropriate for the service). The easiest way to ensure your app allows users to authenticate is to set an instance of the DefaultAuthenticationChallengeHandler onto the AuthenticationManager:

 AuthenticationManager.setAuthenticationChallengeHandler(new DefaultAuthenticationChallengeHandler(context));

Alternatively, implement and set a custom AuthenticationChallengeHandler, to customize the logic or user interface of handling authentication challenges.

Manage an in-memory cache of credentials

When a user is challenged and enters credentials which successfully allow access to the resource, those credentials are automatically added to the AuthenticationManager.CredentialCache. When secured resources from the same server and port are accessed subsequently, credentials in this cache are reused automatically, avoiding unnecessary challenges. Certificates are also cached, see below for more details.

If your app allows a user to sign out of a portal or server, call AuthenticationManager.CredentialCache.clear() to remove all cached credentials when the user signs out, to prevent users accessing resources for which they do not have permission.

The credential cache can be serialized to json, enabling it to be stored between app sessions. However, the serialized credential cache should be secured using an appropriate mechanism for your platform to ensure that credentials are not available to other apps or processes.

Manage the certificates for accessing certificate secured resources

Authentication challenges issued for self-signed server certificates can be handled as follows. Use the setSelfSignedCertificateListener(SelfSignedCertificateListener) method to provide a listener that will handle self signed certificates as they are encountered (Other types of AuthenticationChallenge will continue to be sent to the current AuthenticationChallengeHandler). This approach is useful when you want to add specific logic for trusting self-signed certificates on a case-by-case basis, but the behavior of the DefaultAuthenticationChallengeHandler is suitable for all other authentication challenges.

For testing purposes, setTrustAllSigners(boolean) can be called with a value of true to indicate an app is willing to trust all valid, non-expired, self-signed certificates. This should never be used in production code.

Manage a set of OAuth configurations

If your app will connect to OAuth secured resources, and you have set an instance of the DefaultAuthenticationChallengeHandler onto the AuthenticationManager, then add an OAuthConfiguration for a specific client ID and portal by calling addOAuthConfiguration(OAuthConfiguration). The set of OAuthConfiguration is stored in-memory only and does not persist between sessions. When using the DefaultAuthenticationChallengeHandler for OAuth, you need to also use the DefaultOAuthIntentReceiver.

Using OAuth login manager directly

You can also use OAuthLoginManager directly for custom OAuth login flows, but this is not necessary when using the DefaultAuthenticationChallengeHandler. If you do use the OAuthLoginManager, then you need not set OAuthConfiguration on the AuthenticationManager.

What's Next?

For more information about Security and Authentication, see the Security and Authentication chapter.

Samples

Authenticate with OAuth

Integrated Windows authentication

Token authentication