With the Pega^® Mashup SDK, you can authenticate with a Pega Platform instance in a native Android mobile app in several ways. However, it is recommended that you use the SnapStart object to authenticate either asynchronously or synchronously with a Pega Platform instance. When you obtain an instance of the authenticated SnapStart object, you can use it to access an embedded Pega Platform application in a hybrid web view. For example, you can use the Mashup SDK to create or open a case, open a harness, or run an activity.

• Authenticate asynchronously by using the SnapStart object
• Authenticate synchronously by using the SnapStart object
• Authenticate using the ISnapStartAuthenticator object
• Authenticate by using the Pega basic Authenticator object
• Standard authentication errors

Prerequisites

Before you continue, make sure that you have read the following information:

• Setting up the Mashup SDK for Android app development

Make sure that you also have access to the Mashup SDK Javadoc documentation that is included with the Pega Mashup SDK distribution package.

Authenticate asynchronously by using the SnapStart object

Connect to a Pega Platform instance in a native Android mobile app by calling the asynchronous login() method for the SnapStart object. This method takes the following parameters:

• The SnapStart.LoginListener object.
• URL (string type) address of the Pega Platform server that you want to connect to. The URL address must be specified in the following format:http://<SERVER_NAME>:<PORT>/prweb/
• The user name (string type) used to log in to the Pega Platform server.
• The password (string type) used to log in to the Pega Platform server.

The SnapStart.LoginListener object contains three public methods that indicate what to do before you attempt to log in, when you have logged in to Pega Platform successfully, or when you have failed to log in to Pega Platform. The onSuccess() method passes the instance of the initialized SnapStart object for the connected Pega Platform instance. The onFailure() method passes one of the AuthenticatorResult enumeration values specified in the table in the Standard authentication errors section that describes the error during authentication.

SnapStart.login( new MySnapStartLoginListener(),  
   "http://host:port/path",  
   "jdoe",   
   "secret");  
  
class MySnapStartLoginListener extends SnapStart.LoginListener {  
 
  @Override  
  public void onStart() {  
    // do any actions prior to logging in, for example, 
    // display a progress dialog 
  }; 
  @Override  
  public onSuccess( SnapStart snapStart ) {  
    // perform any actions once successfully logged in   
  };  
  @Override  
  public onFailure( SnapStartLoginException cause ) {  
    // handle error that occurred during logging in   
  };  
};

Authenticate synchronously by using the SnapStart object

To authenticate to a Pega Platform instance synchronously with the SnapStart object, you must call the login() method. This method takes the following parameters:

• URL (string type) address of the Pega Platform server that you want to connect to. The URL address must be specified in the following format:http://<SERVER_NAME>:<PORT>/prweb/
• The user name (string type) used to log in to the Pega Platform server.
• The password (string type) used to log in to the Pega Platform server.

If successful, the method returns a SnapStart object. Make sure to include the login() method within a try{} and catch{} statement so that if an error occurs while logging in, the method throws a SnapStartLoginException with one of the AuthenticatorResult enumeration values specified in the table in the Standard authentication errors section that describes the error.

SnapStart mySnapStart;  
try   {  
  mySnapStart = SnapStart.login( "http://host:port/path", "jdoe", "secret");  
}   catch(SnapStartLoginException e){  
  // handle error    
}

Authenticate by using the ISnapStartAuthenticator object

If you plan to authenticate to the Pega Platform instance in a custom way, for example, for each login request you require an additional header or a parameter, you must use your own implementation of the ISnapStartAuthenticator object to call the login() method. This interface object includes the following methods:

• getHttpHeaders()– The returned headers are added to every SnapStart HTTP request.
• getHttpPostParameters()– The returned parameters are added to every SnapStart action.
• login() – Authenticates to a Pega Platform application.
• logout()– Signs out from a Pega Platform application.

class MySnapStartAuthenticator implements ISnapStartAuthenticator {  
 
  @Override 
  public  String login() throws SnapStartLoginException { 
    // used to log in using username/password and   
    // Pega Platform instance url.  
  }  
 
  @Override 
  public PegaAuthenticatorResult logout() {  
  } 
 
  @Override 
  public Map <String, String> getHttpHeaders() { 
    Map<String, String> headers = new HashMap<>(); 
    headers.put("ObligatoryHeader", "ItsValue"); 
    return headers; 
    // the defined headers will be added to each  
    // query of the SnapStart object instance 
  } 
 
  @Override 
  public List <SnapStartActionParameter> getHttpPostParameters() { 
    List<SnapStartActionParameter> params = new ArrayList<>();  
    params.add(new SnapStartActionParameter("ObliogatoryParam", "ItsValue"));  
    return params;  
    // the defined parameters will be added to each  
    // query of the SnapStart object instance  
  }  
 
SnapStart mySnapStart;  
try {  
  mySnapStart = SnapStart.login(new MySnapStartAuthenticator( 
  /* add any arguments necessary to login here */)); 
} catch(SnapStartLoginException e){ 
  // handle error    
}

Authenticate by using the Pega basic Authenticator object

The Pega Mashup SDK includes a Java API Authentication module that you can alternatively use to authenticate to a Pega Platform instance in a native Android mobile app:

• Obtain the Authentication object
• Log in using the Authenticator object
• Log out using the Authenticator object
• Check whether you are currently logged in

Obtain the authentication object

To log in, log out, or check the current login status of the Pega Platform instance, you must create an instance of the PegaAuthenticator object.

To obtain the PegaAuthenticator object, call the following method in your Java code:

ContainerProvider.get(PegaAuthenticator.class);

Log in

To authenticate the user in the Pega Platform instance, you must call the logIn(serverUrl, credentials) method on the instance of the PegaAuthenticator object. Pass parameters to this method that specify the following:

• The URL address of the Pega Platform server (of string type) that you want to connect to. The URL address must be specified in the following format:http://<SERVER_NAME>:<PORT>/prweb/
• The Credentials object that contains a user name and a password (both of string type)

The following example shows the Java code:

String serverUrl =  "http://host:port/path"; 
Credentials credentials =  new Credentials("jdoe","secret"); 
PegaAuthenticatorResult result = pegaAuthenticator.logIn(serverUrl, credentials); 
// if the result's getType() is AuthenticatorResult.SUCCESS, the operation was successful

Because running the logIn() method is a network operation, to avoid NetworkOnMainThreadException errors in your application, do not run this method on the main thread. When you call the logIn() method, an instance of the PegaAuthenticatorResult object is returned. You can then call the getType() method on this returned object to verify whether the authentication process was successful. The returned value of AuthenticatorResult type for this method is one of the values specified in the table in the Standard authentication errors section.

You can also call the getData() method for the instance of the PegaAuthenticatorResult object.

Log out

To log out of the Pega Platform instance, you must call the logOff(serverUrl) method on the instance of the PegaAuthenticator object, passing the method to the URL address of the server as a parameter of string type. This URL address of the Pega Platform instance is obtained during login. The logOff() method returns a value that specifies whether your logout was successful. To verify, you can use the getType() method on this returned object to see whether it is set to AuthenticatorResult.SUCCESS.

result = pegaAuthenticator.logOff(serverUrl)  
// if the result's getType() is AuthenticatorResult.SUCCESS, the operation was successful

Check whether you are currently logged in

To check whether you are currently logged in to the Pega Platform instance from the Android mobile app, you must call the asynchronous isLoggedIn() method on the PegaAuthenticator object, passing the method to the URL address of the server as a parameter of string type. The URL address of the Pega Platform instance is obtained during login.

result = pegaAuthenticator.isLoggedIn(serverUrl);  
// if the result's getType() is AuthenticatorResult.SUCCESS, the operation was successful

Standard authentication errors

When you try to log in to Pega Platform in any of the ways outlined above, the following authentication errors can be generated. They are defined in the AuthenticatorResult enumeration.