Package com.esri.arcgisruntime.security

Class 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

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

      Java and Android:   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.
      Android Only:   When using the DefaultAuthenticationChallengeHandler for OAuth, you need to also use the DefaultOAuthIntentReceiver.

      Using OAuthLoginManager Directly (Android Only):

      In Android, 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 OAuthConfigurations on the AuthenticationManager.

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

    Since:
    100.0.0
    See Also:
    Portal.addCredentialChangedListener(CredentialChangedListener), DefaultAuthenticationChallengeHandler

    • Method Detail

      • 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. Passing null has no effect.
        Parameters:
        handler - the AuthenticationChallengeHandler that should be 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

      • setKeyStores

        @Deprecated
public static void setKeyStores​(KeyStore clientCertStore,
                                String clientStorePass,
                                KeyStore serverTrustStore)
                         throws IOException,
                                KeyStoreException
        Deprecated.
        As of 100.2.0, use CertificateCredential 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
        Since:
        100.0.0