public class

UserCredentials

extends Object
implements Serializable
java.lang.Object
   ↳ com.esri.core.io.UserCredentials

Class Overview

This class represents user credential for accessing secure ArcGIS Services and Tasks. A user's credential is either composed of a user account (username and password) or a secure token.

If you wish to store and reuse UserCredentials, the best way of doing this is by serializing them to disk. This should be done to a secure location, and should use some form of encryption if possible.

Note: Because of a current issue with how credentials work with portals, if you want to serialize a UserCredentials object, and then later deserialize and use it, you must do the following: Once you have verified that the credentials work with the portal (by accessing something secured) when you go to serialize, check to see if the credentials object has a password. If it does, create a new UserCredentials object, copy over just the username and password, and serialize that object. If the credential does not have a password, just serialize the object that is stored in the Portal object. This will be addressed in the next release.

Summary

Nested Classes
enum UserCredentials.AuthenticationType The supported authentication type. 
Public Constructors
UserCredentials()
Constructs an instance of UserCredentials.
UserCredentials(UserCredentials other)
Instantiates a copy of the given credential.
Public Methods
static void clearCachedCredentials(String url)
Clears any credentials that the Apache HttpClient has cached for the provided URL.
boolean equals(Object obj)
UserCredentials.AuthenticationType getAuthenticationType()
Gets the authentication type of the credentials.
UserCredentials getCopy()
Returns a copy of the instance.
String getDomain()
Gets the domain of the UserCredentials.
String getPassword()
Returns the password that this instance was initialized with.
String getReferer()
Returns the referer that was supplied with the token string.
static UserCredentials.AuthenticationType getServiceAuthenticationType(String url)
Queries the service to determine the type of authentication used (if any).
String getToken()
Returns the token that this instance was initialized with.
long getTokenExpiry()
String getTokenServiceUrl()
Returns the remote token service URL that this instance was initialized with.
String getUserName()
Returns the username that this instance was initialized with.
int hashCode()
static boolean isDefaultReadObject()
Checks whether Java's default read object method should be used when deserializing a credential object, instead of the manual implementation introduced in 10.2.4.
boolean isEmpty()
Returns true if the credentials is empty or lack of enough information.
boolean isSSLRequired()
Returns whether or not the service should only be connected to with SSL encryption (usually https).
void setAuthenticationType(UserCredentials.AuthenticationType type)
Sets the authentication type of the UserCredentials.
static void setDefaultReadObject(boolean defaultReadObject)
Sets a static variable used to specify whether credential objects should be deserialized using the new manual implementation or the previous default Java method.
void setDomain(String domain)
Sets the domain of the UserCredentials.
void setSSLRequired(boolean required)
Sets whether or not the service should only be connected to with SSL encryption (usually https).
void setTokenServiceUrl(String tokenServiceUrl)
Sets the URL to a remote token service if it is different from the default ArcGIS token service.
static void setTrustStore(KeyStore clientCA, String password, KeyStore trustCA)
Sets KeyStores which contain server and client certificates for accessing HTTPS GIS service endpoints in an application.
static void setTrustStore(KeyStore keyStore)
Sets a KeyStore that contains trusted self-signed certificates for accessing HTTPS GIS service endpoints in an application.
void setUserAccount(String userName, String password)
Sets the user account (username and password) for accessing a secure Service or Task in an application.
void setUserName(String userName)
void setUserToken(String token, long tokenExpiry, String referer)
Sets the user token for accessing a secure Service or Task in an application.
void setUserToken(String token, String referer)
Sets the user token for accessing a secure Service or Task in an application.
String toString()
Returns a string representation of the class.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public UserCredentials ()

Constructs an instance of UserCredentials.

public UserCredentials (UserCredentials other)

Instantiates a copy of the given credential.

Parameters
other UserCredentials: the instance to copy.

Public Methods

public static void clearCachedCredentials (String url)

Clears any credentials that the Apache HttpClient has cached for the provided URL. When the authentication type encountered is HTTP, the Apache HttpClient will cache credentials to use against that host.

Parameters
url String: the url to clear cached credentials for
Throws
EsriSecurityException if the url is malformed.

public boolean equals (Object obj)

Parameters
obj Object
Returns
boolean

public UserCredentials.AuthenticationType getAuthenticationType ()

Gets the authentication type of the credentials. Unless explicitly set, this will return null until the credentials are used in a network request, at which point the type will be determined.

Returns
UserCredentials.AuthenticationType the authentication type

public UserCredentials getCopy ()

Returns a copy of the instance.

Returns
UserCredentials a copy.

public String getDomain ()

Gets the domain of the UserCredentials. The domain is used for NTLM authentication.

Returns
String the domain.

public String getPassword ()

Returns the password that this instance was initialized with.

Returns
String the password

public String getReferer ()

Returns the referer that was supplied with the token string.

Returns
String the referer

public static UserCredentials.AuthenticationType getServiceAuthenticationType (String url)

Queries the service to determine the type of authentication used (if any).

Parameters
url String: The service to query
Returns
UserCredentials.AuthenticationType The authentication type used by the service (if any)

public String getToken ()

Returns the token that this instance was initialized with.

Returns
String the token

public long getTokenExpiry ()

Returns
long the token expiration.

public String getTokenServiceUrl ()

Returns the remote token service URL that this instance was initialized with.

Returns
String the remote token service URL

public String getUserName ()

Returns the username that this instance was initialized with.

Returns
String the username

public int hashCode ()

Returns
int

public static boolean isDefaultReadObject ()

Checks whether Java's default read object method should be used when deserializing a credential object, instead of the manual implementation introduced in 10.2.4. Please see setDefaultReadObject(boolean) for more information and example code.

Returns
boolean true if Java's default read object method should be used when deserializing credential objects

public boolean isEmpty ()

Returns true if the credentials is empty or lack of enough information.

Returns
boolean true if the credentials is empty or lack of enough information.

public boolean isSSLRequired ()

Returns whether or not the service should only be connected to with SSL encryption (usually https).

Returns
boolean Returns returns true if using SSL.

public void setAuthenticationType (UserCredentials.AuthenticationType type)

Sets the authentication type of the UserCredentials.

Parameters
type UserCredentials.AuthenticationType: The authentication type to set.

public static void setDefaultReadObject (boolean defaultReadObject)

Sets a static variable used to specify whether credential objects should be deserialized using the new manual implementation or the previous default Java method. This allows backwards compatibility with credentials that were serialized at the 10.2.2 or 10.2.3 release. Once an object has been reserialized from 10.2.4 onward, that object will no longer need this flag to be set in order to be deserialized. This is used for a one time conversion. An example workflow would be as follows:

 UserCredentials creds = null;
 FileInputStream fileIn = null;
 ObjectInputStream in = null;
 try {
  fileIn = new FileInputStream("/path/to/serialized/credential");
  in = new ObjectInputStream(fileIn);
  creds = (UserCredentials) in.readObject();
 } catch (Exception e) {
  // First failure likely means object was serialized at a previous release
  try {
    // Set flag so that Java's default method will be used, as was the case in 10.2.2/3
    UserCredentials.setDefaultReadObject(true);
    fileIn = new FileInputStream("/path/to/serialized/credential");
    in = new ObjectInputStream(fileIn);
    creds = (UserCredentials) in.readObject();
   } catch (Exception e1) {
    // If we still fail, we cannot deserialize the credential
   } 
 } finally {
   try {
    if (in != null) {
       in.close();
    }
    if (fileIn != null) {
       fileIn.close();
    }
   } catch (Exception e2) {
    // Cannot close streams...
   }
 } 
 

Parameters
defaultReadObject boolean: whether to use Java's default read object method

public void setDomain (String domain)

Sets the domain of the UserCredentials. The domain is used for NTLM authentication.

Parameters
domain String: The domain to set.

public void setSSLRequired (boolean required)

Sets whether or not the service should only be connected to with SSL encryption (usually https).

Parameters
required boolean: set to true to use SSL.

public void setTokenServiceUrl (String tokenServiceUrl)

Sets the URL to a remote token service if it is different from the default ArcGIS token service. If the application invoking this API is an Android application which along with the token service is part of the same LAN, then the hostname in the URL must be fully qualified to avoid DNS name resolution problems in Android.

Parameters
tokenServiceUrl String: a URL to a remote token service

public static void setTrustStore (KeyStore clientCA, String password, KeyStore trustCA)

Sets KeyStores which contain server and client certificates for accessing HTTPS GIS service endpoints in an application.

Parameters
clientCA KeyStore: the KeyStore of the client certificates.
password String: the password to access the client certificates.
trustCA KeyStore: the KeyStore of server CAs to trust.
Throws
EsriSecurityException the ESRI security exception

public static void setTrustStore (KeyStore keyStore)

Sets a KeyStore that contains trusted self-signed certificates for accessing HTTPS GIS service endpoints in an application.

Parameters
keyStore KeyStore: the KeyStore of CAs to trust.
Throws
EsriSecurityException the esri security exception

public void setUserAccount (String userName, String password)

Sets the user account (username and password) for accessing a secure Service or Task in an application.

Parameters
userName String: the username
password String: the password

public void setUserName (String userName)

Parameters
userName String

public void setUserToken (String token, long tokenExpiry, String referer)

Sets the user token for accessing a secure Service or Task in an application. The token is a secure token generated by an ArcGIS Token service or a Remote token service. See the ArcGIS for Server help page Acquiring ArcGIS tokens for more info.

Regardless of which option is chosen, it is always necessary for a client parameter to be specified for generating a secure token. The client is typically the identity of the client application consuming the secure service. For Android/Java applications, the client would be the referer string that is either the name of the application consuming the secure service or any other client identification string that is appropriate for the application. It is required that the referer string that was used to generate the token be supplied to this method.

For more information see About ArcGIS tokens.

Parameters
token String: the secure token string
tokenExpiry long: expiry date of token
referer String: the referer string used to generate the token string

public void setUserToken (String token, String referer)

Sets the user token for accessing a secure Service or Task in an application. The token is a secure token generated by an ArcGIS Token service or a Remote token service. Tokens are generated either by sending an HTTP URL request to a Token service end-point or through an HTML page. See the ArcGIS for Server help page Acquiring ArcGIS tokens for more info.

Regardless of which option is chosen, it is always necessary for a client parameter to be specified for generating a secure token. The client is typically the identity of the client application consuming the secure service. For Android/Java applications, the client would be the referer string that is either the name of the application consuming the secure service or any other client identification string that is appropriate for the application. It is required that the referer string that was used to generate the token be supplied to this method.

For more information see About ArcGIS tokens.

Parameters
token String: the secure token string
referer String: the referer string used to generate the token string

public String toString ()

Returns a string representation of the class. The format and content of the returned string is not part of the contract of the method and is subject to change in any future release or patch without further notice.

Returns
String