The Pega Mashup SDK includes an Objective-C API Authentication module that allows a user to set the Pega 7 Platform instance URL, log in and log out from this Pega 7 Platform instance, and also check whether the user is currently logged in, all from a native iOS app. This article describes the API.

• Obtaining the authentication object
• Logging in
• Logging out
• Checking login status

Obtaining the authentication object

To instantiate the authentication object, you must first create NSURLSessionConfiguration (session configuration object) to specify the timeout interval for logging in and whether to store credentials. You can set additional properties in the session configuration object. Next, you must call the initWithURL() method, passing it the session configuration object as the parameter.

The following example shows the Objective-C code.

NSURLSessionConfiguration *config = [NSURLSessionConfiguration defaultSessionConfiguration];
config.timeoutIntervalForRequest = 30.0;
config.URLCredentialStorage = nil;
NSURL *URL = [NSURL URLWithString:@"http://test.server.com:8243/prweb"];
NSURLSession *session = [NSURLSession sessionWithConfiguration:config];
AHCPRPCAuthentication *authenticationService = [[AHCPRPCAuthentication alloc] initWithURL:URL session:session];”

After you create an instance of the authentication object and configure it, you can use it to log in, log out, or check its current login status.

Logging in

To log in to the Pega 7 Platform instance, you must call the loginWithCredential() method on the instance of the authentication object, passing it the user name and password credentials as the first parameter and the completion handler as the second parameter. The completionHandler()returns the URL of the Pega 7 Platform instance if you were successful logging in or an error code if you were unsuccessful.

The following Objective-C code demonstrates how to do this.

NSURLCredential *credential = [NSURLCredential credentialWithUser:@"jsmith" password:@"mypassword" persistence:NSURLCredentialPersistenceNone];
[authenticationService loginWithCredential:credential completionHandler:^(NSURL *portalURL, NSError *error){
  // add your code depending if were successful logging in or not
}

The error codes for the Authentication module on iOS are defined as follows:

CF_EXPORT NSString *const AHCPRPCAuthenticationErrorDomain;
typedef NS_ENUM(NSInteger, AHCPRPCAuthenticationError) {
  AHCPRPCAuthenticationErrorInternal = 1,
  AHCPRPCAuthenticationErrorIllegalArgument = 2,
  AHCPRPCAuthenticationErrorFailed = 3,
  AHCPRPCAuthenticationErrorServer = 4,
  AHCPRPCAuthenticationErrorNetwork = 5,
  AHCPRPCAuthenticationErrorClientVersionMismatch = 6
};

Logging out

To log out from the Pega 7 Platform instance from your iOS app, you must call the logout() method on the authentication object instance. This action also clears cookies for the current or previous Pega 7 Platform session.

[self.authenticationService logout];

Checking login status

To find out whether your iOS app is currently logged in to the Pega 7 Platform instance, you must call the isLoggedInWithCompletionHandler() method on the instance of the authentication object. It returns a Boolean value that indicates whether the app is currently logged in and also an error code if the login status checking was unsuccessful.

[self.authenticationService isLoggedInWithCompletionHandler:^(BOOL isLoggedIn, NSError *error){
  // add your code here
}];