Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.security

Class AuthenticationManager

java.lang.Object
com.esri.arcgisruntime.security.AuthenticationManager
public final class AuthenticationManager extends Object
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

    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.

    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 LoadStatus.FAILED_TO_LOAD and the Loadable.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 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

    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.

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

Since:
100.0.0
See Also:

  • Method Details

    • setAuthenticationChallengeHandler

      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.
      Parameters:
      handler - the AuthenticationChallengeHandler that should be used to handle authentication exceptions
      Since:
      100.0.0

    • getAuthenticationChallengeHandler

      public static AuthenticationChallengeHandler getAuthenticationChallengeHandler()
      Gets the current AuthenticationChallengeHandler. See setAuthenticationChallengeHandler(AuthenticationChallengeHandler) for more details.
      Returns:
      the AuthenticationChallengeHandler currently used to handle authentication exceptions
      Since:
      100.0.0

    • addOAuthConfiguration

      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
      Since:
      100.0.0

    • removeOAuthConfiguration

      public static boolean removeOAuthConfiguration(String portalUrl) throws MalformedURLException
      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
      Since:
      100.0.0

    • getOAuthConfiguration

      public static OAuthConfiguration getOAuthConfiguration(String portalUrl) throws MalformedURLException
      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
      Since:
      100.0.0

    • clearOAuthConfigurations

      public static void clearOAuthConfigurations()
      Clears the current OAuthConfigurations.
      Since:
      100.0.0

    • getSelfSignedCertificateListener

      public static SelfSignedCertificateListener getSelfSignedCertificateListener()
      Returns the user defined SelfSignedCertificateListener.
      Returns:
      the SelfSignedCertificateListener
      Since:
      100.0.0

    • setSelfSignedCertificateListener

      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
      Since:
      100.0.0

    • isTrustAllSigners

      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
      Since:
      100.0.0

    • setTrustAllSigners

      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
      Since:
      100.0.0

    • clearTrustedCertificates

      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.
      Since:
      100.0.0