public final class

AuthenticationManager

extends Object
java.lang.Object
   ↳ com.esri.arcgisruntime.security.AuthenticationManager

Class Overview

Manages user authentication when connecting to secured services. Provides a central place to configure the following aspects of authentication:

  • Set a central AuthenticationChallengeHandler that will allow your users to authenticate with secured services

    In Android, 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 Authentication manager:

    AuthenticationManager.setAuthenticationChallengeHandler(new
     DefaultAuthenticationChallengeHandler(context));

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

    In Java, the DefaultAuthenticationChallengeHandler class can take care of user credential and OAuth challenges. For other challenges you must implement AuthenticationChallengeHandler and pass an instance of your handler to setAuthenticationChallengeHandler(AuthenticationChallengeHandler).

    The AuthenticationManager's AuthenticationChallengeHandler is null by default; if no handler is set, the request to the secured resource will fail as it cannot be authenticated; for example, a Loadable that uses a secured resource may have a FAILED_TO_LOAD and the getLoadError() will indicate an authorization failure.

  • 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 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

    AuthenticationChallenges 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 behaviour 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 OAuthConfigurations

    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 OAuthConfigurations is stored in-memory only and does not persist between sessions. When using the DefaultAuthenticationChallengeHandler for OAuth, you need to also use the DefaultOAuthIntentReceiver.

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

See the ArcGIS for Developers website for an overview of ArcGIS Security and Authentication.

Summary

Nested Classes
class AuthenticationManager.CredentialCache Encapsulates a map of server contexts to credentials that may be used to access them. 
Public Methods
static void addOAuthConfiguration(OAuthConfiguration oAuthConfiguration)
Adds an OAuthConfiguration that will be used to provide the client ID and redirect URI for the portal URL specified in the configuration (or all portals if the portal URL is null).
static void clearKeyStores()
This method is deprecated. As of 100.2.0, this method has been deprecated. Use clear() instead.
static void clearOAuthConfigurations()
Clears the current OAuthConfigurations.
static void clearTrustedCertificates()
Removes all cached trusted server certificates.
static AuthenticationChallengeHandler getAuthenticationChallengeHandler()
Gets the current AuthenticationChallengeHandler.
static OAuthConfiguration getOAuthConfiguration(String portalUrl)
Gets the OAuthConfiguration that was added for the specified portal URL.
static SelfSignedCertificateListener getSelfSignedCertificateListener()
Returns the user defined SelfSignedCertificateListener.
static boolean isTrustAllSigners()
Returns true if all signers are trusted.
static boolean removeOAuthConfiguration(String portalUrl)
Removes the OAuthConfiguration with the specified URL if it has previously been added.
static void setAuthenticationChallengeHandler(AuthenticationChallengeHandler handler)
Sets an authentication challenge handler which will be used to handle any authentication exceptions that arise while executing requests.
static void setKeyStores(KeyStore clientCertStore, String clientStorePass, KeyStore serverTrustStore)
This method is deprecated. As of 100.2.0, this method has been deprecated. Use CertificateCredential instead and set it on the RemoteResource
static void setSelfSignedCertificateListener(SelfSignedCertificateListener listener)
Sets the SelfSignedCertificateListener to handle self-signed certificates.
static void setTrustAllSigners(boolean trustAllSigners)
Set to true to trust all signers.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public static void addOAuthConfiguration (OAuthConfiguration oAuthConfiguration)

Adds an OAuthConfiguration that will be used to provide the client ID and redirect URI for the portal URL specified in the configuration (or all portals if the portal URL is null).

Parameters
oAuthConfiguration the OAuthConfiguration to add
Throws
IllegalArgumentException if oAuthConfiguration is null

public static void clearKeyStores ()

This method is deprecated.
As of 100.2.0, this method has been deprecated. Use clear() instead.

Clears the client certificate and server trust keystores used for certificate based authentication.

Throws
IOException if there is an issue setting up a new SSL context after clearing the keystores

public static void clearOAuthConfigurations ()

Clears the current OAuthConfigurations.

public static void clearTrustedCertificates ()

Removes all cached trusted server certificates. This does not affect client certificates. This will cause all previously trusted server certificates to become untrusted again.

public static AuthenticationChallengeHandler getAuthenticationChallengeHandler ()

Gets the current AuthenticationChallengeHandler. See setAuthenticationChallengeHandler(AuthenticationChallengeHandler) for more details.

Returns
  • the AuthenticationChallengeHandler currently used to handle authentication exceptions

public static OAuthConfiguration getOAuthConfiguration (String portalUrl)

Gets the OAuthConfiguration that was added for the specified portal URL. If there is an OAuthConfiguration that was added with a null portal URL, that will be returned regardless of the portal URL that was passed.

Parameters
portalUrl the portal URL for which to get an OAuthConfiguration
Returns
  • the OAuthConfiguration
Throws
MalformedURLException if the portal URL is malformed

public static SelfSignedCertificateListener getSelfSignedCertificateListener ()

Returns the user defined SelfSignedCertificateListener.

Returns
  • the SelfSignedCertificateListener

public static boolean isTrustAllSigners ()

Returns true if all signers are trusted. See setTrustAllSigners(boolean) for more information.

Returns
  • true if all signers should be trusted, otherwise false

public static boolean removeOAuthConfiguration (String portalUrl)

Removes the OAuthConfiguration with the specified URL if it has previously been added.

Parameters
portalUrl the portal URL of the OAuthConfiguration to remove, or null to remove the global configuration
Returns
  • true if the OAuthConfiguration was removed; otherwise false (for example, if it was never actually added)
Throws
MalformedURLException if the portal URL is malformed

public static void setAuthenticationChallengeHandler (AuthenticationChallengeHandler handler)

Sets an authentication challenge handler which will be used to handle any authentication exceptions that arise while executing requests. This handler should use the challenge provided to determine what went wrong, and then provide some way for the user to indicate how to proceed. Challenges are handled one at a time. Passing null has no effect.

Parameters
handler the AuthenticationChallengeHandler that should be used to handle authentication exceptions

public static void setKeyStores (KeyStore clientCertStore, String clientStorePass, KeyStore serverTrustStore)

This method is deprecated.
As of 100.2.0, this method has been deprecated. Use CertificateCredential instead and set it on the RemoteResource

Sets a client certificate store and a trust store. The former is a store of certificates which can be used to identify the client to the server. The latter is a list of server certificates that should be trusted. This will not allow trusting of expired or not yet valid certificates; it simply trusts the issuer of the certificate. To accept expired or not yet valid certificates, a SelfSignedCertificateListener must be implemented and set using setSelfSignedCertificateListener(SelfSignedCertificateListener).

Parameters
clientCertStore the keystore of client side certificates
clientStorePass the password to the client certificate keystore
serverTrustStore the keystore of server certificates to trust
Throws
IOException if there is an issue applying the keystores
KeyStoreException

public static void setSelfSignedCertificateListener (SelfSignedCertificateListener listener)

Sets the SelfSignedCertificateListener to handle self-signed certificates. With the listener, users have full control over all certificates. This should not be confused with isTrustAllSigners(). The trusted certificates will be cached in the session. You can clear the cache by calling clearTrustedCertificates().

Parameters
listener the SelfSignedCertificateListener to set

public static void setTrustAllSigners (boolean trustAllSigners)

Set to true to trust all signers. This will not allow trusting of expired or not yet valid certificates; it simply disregards the issuer of the certificate. To accept expired or not yet valid certificates, a SelfSignedCertificateListener must be implemented and set using setSelfSignedCertificateListener(SelfSignedCertificateListener). Setting this to false will cause all previously trusted server certificates to become untrusted again.

Parameters
trustAllSigners whether to trust all certificate signers