The Pega Mashup SDK includes a Swift and Objective-C API Authentication module that allows you to do the following in a native iOS mobile app:

• Obtain the authentication object
• Log in
• Log out
• Check login status
• Authenticate with a POST request

Obtain the authentication object

To log in, log out, or check its current login status, you must create an instance of the PMPegaAuthenticator object by providing the Pega 7 Platform server URL.

To create an instance of the PMPegaAuthenticator object in Swift, add the following lines of code:

import PMAuthentication; 
var url = NSURL(string: "http://host:port/path"); 
var authenticator = PMPegaAuthenticator(serverURL: url);

To create an instance of the PMPegaAuthenticator object in Objective-C, add the following lines of code:

@import PMAuthentication; 
NSURL *url = [NSURL URLWithString:@"http://host:port/path"]; 
PMPegaAuthenticator *authenticator = [[PMPegaAuthenticator alloc] initWithServerURL:url];

Log in

To log in to the Pega 7 Platform instance, you must call the loginWithUsername() method on the instance of the PMPegaAuthenticator object. You pass to it the user name and password as the first two parameters. The completion handler is also passed as the third parameter. If you successfully log in to the Pega 7 Platform instance using the loginWithUsername() method, the completionHandler() returns the URL of the Pega 7 Platform server. Otherwise, it returns an error.

The following Swift code demonstrates how to log in to the Pega 7 Platform instance:

authenticator.logInWithUsername(user, password: pass) { (json, error) in 
  // add your code here 
}

The following Objective-C code demonstrates how to log in to the Pega 7 Platform instance:

[authenticator logInWithUsername:@"jdoe" password:@"secret" 
  completionHandler:^(NSDictionary<NSString *,id> * json, NSError * error) { 
  //add your code here 
}];

The completion handler object is run with no return value and takes the following parameters:

• response object – Consists of a dictionary object that contains access group name, base URL, and other properties. It is set to null if an error occurred.
• error object – Indicates the reason why the request failed, or is set to null if the request was successful.

The error codes for the Authentication module when you call the loginWithUsername() method on iOS are defined as follows:

• PMAuthenticationErrorInvalidCredentials – A Pega authenticator error that relates to invalid credentials.
• PMAuthenticationErrorInternal – A Pega authenticator internal error.
• PMAuthenticationErrorInvalidInputData – An error that relates to a missing or an invalid user name or password.
• PMAuthenticationErrorNetwork – A Pega authenticator error that relates to a network connectivity problem.
• PMAuthenticationErrorUnexpectedServerResponse – A Pega authenticator error that relates to an unrecognized server response.
• PMAuthenticationErrorWrongClientVersion – A Pega authenticator error that relates to a container version being out of the allowed range.

Log out

To log out from the Pega 7 Platform instance from your iOS mobile app, you must call the logOffWithCompletionHandler() method on the instance of the PMPegaAuthenticator object. By calling this method, the cookies for the current or previous Pega 7 Platform session are also cleared. The completionHandler() method returns an error if the call to the method was unsuccessful.

The following Swift code demonstrates how to log out from the Pega 7 Platform instance:

authenticator.logOffWithCompletionHandler() { (error) in 
  // add your code here 
}

The following Objective-C code demonstrates how to log out from the Pega 7 Platform instance:

[authenticator logOffWithCompletionHandler:^(NSError * error) { 
  // add your code here 
}];

The completion handler object is run with no return value and takes the error object as a parameter, which indicates why the request failed, or it is null if the request was successful.

Check login status

To find out whether you are currently logged in to the Pega 7 Platform instance, you must call the isLoggedInWithCompletionHandler() method on the instance of the PMPegaAuthenticator object. In case of network connectivity issues, the API returns an error because it is not possible to determine the login status.

The following Swift code demonstrates how to check whether you are currently logged in to the Pega 7 Platform instance:

authenticator.isLoggedInWithCompletionHandler() { (isSuccess, json, error) in 
  // add your code here 
}

The following Objective-C code demonstrates how to check whether you are currently logged in to the Pega 7 Platform instance:

[authenticator isLoggedInWithCompletionHandler:^(BOOL success, NSDictionary<NSString *,id> * json, NSError * error) { 
  // add your code here 
}];

The completion handler object is run with no return value and takes the following parameters:

• success object – Consists of a Boolean type. If it is set to true, it indicates that the authenticator holds a valid session with the Pega 7 Platform server. If it is set to false, it indicates that it was either impossible to determine the login status or the session has expired.
• response object – Holds a value that is not null, only if the first argument is set to true. It specifies the dictionary object which contains an access group name, base URL, and other properties.
• error object – Holds a value that is not null, only if the first parameter is set to false. It indicates the reason why the request has failed.

Authenticate with a POST request

If you need to authenticate with a POST request, you must first send a POST authentication request using NSURLSession.sharedSession(), or create your own session for as long as NSHTTPCookieStorage.sharedHTTPCookieStorage() is used​. When you receive the response, run the SnapStart action that uses the cookies set in the previous step. 

The following Swift code demonstrates how to authenticate with a POST request:

let url = NSURL(string: "http://host:port/path")! 
let request = NSMutableURLRequest(URL: url) 
request.HTTPMethod = "POST" 
request.HTTPBody = "key1=value1&key2=value2".dataUsingEncoding(NSUTF8StringEncoding) 
NSURLSession.sharedSession().dataTaskWithRequest(request, completionHandler: { (_, _, error) in 
  guard error == nil else { 
    print("Error occured \(error)") 
    return 
  } 
  let snapStart = PMSnapStartViewController() 
  snapStart.webViewName = "newCase" 
  snapStart.delegate = self 
  let action = PMCreateCaseAction(portalURL: url, flowType: "foo", insClass: "bar") 
  snapStart.performAction(action) 
  self.presentViewController(snapStart, animated: true, completion: nil) 
}).resume()

The following Objective-C code demonstrates how to authenticate with a POST request:

NSURL *url = [NSURL URLWithString:@"http://host:port/path"]; 
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url]; 
request.HTTPMethod = @"POST"; 
request.HTTPBody = [@"key1=value1&key2=value2" dataUsingEncoding:NSUTF8StringEncoding]; 
[[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) { 
  if (error) { 
    NSLog(@"Error occured %@", error); 
    return; 
  } 
  PMSnapStartViewController *snapStart = [[PMSnapStartViewController alloc] init]; 
  snapStart.webViewName = @"newCase"; 
  snapStart.delegate = self; 
  PMCreateCaseAction *action = [[PMCreateCaseAction alloc] initWithPortalURL:url flowType:@"foo" insClass:@"bar"]; 
  [snapStart performAction:action]; 
  [self presentViewController:snapStart animated:YES completion:nil]; 
}] resume];