Authenticate with the Mashup SDK on Android
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:
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 }; };
login(SnapStart.LoginListener listener, String url, String username, String password, boolean legacyMode)
method for the SnapStart
object and set the legacyMode
parameter to true.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 }
login(String url, String username, String password, boolean legacyMode)
method for the SnapStart
object and set the legacyMode
parameter to true.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.
logIn(String url, PegaActivity pegaActivity, Credentials credentials)
method and set the pegaActivity
parameter to the PegaActivity.GET_ACCESS_GROUP_DETAILS
enum value.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.
Error | Description |
---|---|
INVALID_CREDENTIALS | Wrong user name or password was entered. |
INTERNAL_ERROR | Internal error has occurred. |
INVALID_INPUT_DATA | Invalid input has been passed. |
NETWORK_ERROR | A network error has occurred. |
UNEXPECTED_SERVER_RESPONSE | An unexpected response was received from the Pega Platform server. |