CA Mobile Authenticator SDKs for iOS
The following iOS SDKs can help you create your own app for receiving push notification for secondary authentication.
aa821test
The following iOS SDKs can help you create your own app for receiving push notification for secondary authentication.
AuthenticatorDelegate
Description
This is the protocol defined for the application that consumes the CA Mobile Authenticator SDK on iOS platform. This protocol defines the delegation methods which needs to be implemented by the application. API Signature
- (id) init
:(id<AuthenticatorDelegate>)authDelegate;Input Parameters
authDelegate
Defines the instance of AuthenticatorDelegate.
CA Mobile Authenticator makes calls to delegate APIs to get the device token from mobile application while registering device and fetching accounts from DB. This device token needs to be uploaded to server for sending push notification to user device.
Remarks
When AuthenticatorDelegate instance is not set for the CAAuthenticator object, the APIs raise exception with AUTH_STATUS_ERR_INVALID_AUTH_DELEGATE error code. For example, CAAuthenticator *authObj = [[CAAuthenticator alloc] init:self];
Return Valuesid
Indicates the initialized object.
authenticateUser
Description
This method is used to authenticate the user when push notification is received on the device. This method sends the user authentication request to the server when push notification is received on the registered device. To receive push notification and sending user authentication request, user must register device first by calling registerDevice() API.
Application Signature
- (AuthStatusCode) authenticateUser:(NSString*)authData authReponse:(AuthReponse)authResponse propdic:(NSDictionary *)props;
Input Parameters
authData
Specifies the authentication data received in push notification data body which CA Mobile Authenticator SDK can consume to send the authentication request to server
authResponse
Indicates enum value for user response. APPROVE value for approving authentication and DENY for denying a transaction
Return Values
AuthStatusCode
Returns the status code returned by the API.Example
NSString* notificationAuthData = "\"data\" : { \"userId\" : \"User Identifier\", \"OrgId\" : \"AA Org for which authentication request is initiated\", \"hostName\" : \"Host to which authentication request will be forwarded\", \"txnId\" : \"transaction Id generated by AFM for authentication purpose\", \"authUrl\" : \"authentication url where SDK needs to send authentication request\", \"serverData\" : \"Encrypted data which contains - Server OTP\", \"authInterval\" : time_in_seconds }" AuthStatusCode status = [authenticatorObj registerDeviceForAccount:@"user1" authData:notificationAuthData props:nil]; */
getDeviceToken
Description
This delegate method is called back in CA Mobile Authenticator SDK to fetch the device token from push notification servcie provider used by the mobile application. The CA Mobile Authenticator SDK makes use of the token returned from this delegate method for performing registration or updation or deletion of the user device from CA Adv Auth Server. This method should always return latest device token.
API Signature
- (NSString *) getDeviceToken;
Return Values
Account*
Returns the AC Authenticator Account object.
registerDevice
Description
This method can be used to register a device(on which application is installed) for the given user. This method will send the device registration request to server which will associate the requesting device to use. Before creating user-device association, server will authenticate the user by verifying OTP value sent to server and then register the device for given user.
API Signature
- (Account *) registerDevice:(NSString *)userId provisioningUrl:(NSString *)provisioningUrl activationCode:(NSString *)activationCode propdic:(NSDictionary *)props;
Input Parameters
userId
Specifies user identifier for which device needs to be registered.
provisioningUrl
Specifies the URL used for connecting to the provisoning server using http method.
activationCode
Specifies the activationCode is provisioning authorization/activation code.
props
Specifies the props is a dictionary of properties to be used for sending additional device information to server.
Return Value
Account*
Returns the AC Authenticator Account object. didFinishDeviceRegistration
This delegate method is called back in CA Mobile Authenticator SDK when device registration is completed by the CA Mobile Authenticator SDK.
Application Signature
- (void) didFinishDeviceRegistration:(AuthStatusCode)status args:(NSMutableDictionary *)dic;
Input Parametersstatus code
Specifies the status code for the device registration request.dic
Specifies the dictionary object with key value pairs for registration request.
didFinishUserAuthentication
This delegate method is called back in CA Mobile Authenticator SDK when user authentication request is completed by CA Mobile Authenticator SDK
Application Signature
- (void) didFinishUserAuthentication:(AuthStatusCode)status args:(NSMutableDictionary *)dic;
Input Parameters
status code
Specifies the status code for the device registration request.dic
Specifies the dictionary object with key value pairs for registration request.
Return Value
status code
Returns the status code for the device authentication request
didFailWithError
Description
This delegate method is called back in CA Mobile Authenticator SDK when device registration request or user authentication request is failed.
Application Signature
- (void) didFailWithError:(AuthStatusCode)status args:(NSMutableDictionary *)dic;
Input Parameters
Specifies the status code for the device registration request.status code
dic
Return Values
status code
Returns the status code for the device authentication request.
getVersion
Description
This method returns the version of the library.
API Signature
- (NSString *) getVersion;
getAccount
Description
This method finds the account information for the given key.
API Signature
- (Account *) getAccount:(NSString *)key;
Input Parameters
key
Specifies a unique key to identify the record which is obtained from Account class.
Exceptions
When the account does not exist in database or an error occurs while reading the database, the following exception is thrown:
AuthenticatorException
Return Values
Acc
Returns CA Mobile Authenticator Account objectdeleteAccount
Description
This method deletes the account from the device. For example: [authObj deleteAccount:acc.key];
API Signature
- (void) deleteAccount:(NSString *)key;
Input Parameters
key
Specifies a unique key to identify the record which is obtained from Account class. Exceptions
When the account does not exist in database or an error occurs while reading the database, the following exception is thrown:
AuthenticatorException
saveAccount
Description
This method saves the account onto device storage. For example: [authObj saveAccount:account1];
API Signature
- (void) saveAccount:(Account *)account;
Input Parameters
Account*
Specifies the AC Authenticator Account object.Exceptions
When the account does not exist in database or an error occurs while reading the database, the following exception is thrown:
AuthenticatorException
getAllAccounts
Description
This method returns all accounts found on the device's storage system.
API Signature
- (NSMutableArray *) getAllAccounts;
Return Values
account array
Returns an array of CA Mobile Authenticator Account objects
Exceptions
When the account does not exist in database or an error occurs while reading the database, the following exception is thrown:
AuthenticatorException
initWithStorageType
Description
This method must be used to initialize the class with custom storage class. When this method is not invoked, CA Mobile Authenticator SDK uses the built-in sqllite database storage.
API Signature
- (id) initWithStorageType:(Store *)storage authDelegate:(id<AuthenticatorDelegate>)delegate;
Input Parameters
storage
Specifies a custom Storage implementation
delegate
Specifies the instance of AuthenticatorDelegate.
Return Valueid
Indicates the initialized object
Remarks
- CA Mobile Authenticator makes calls to delegate APIs to get the device token from mobile application while registering device and fetching accounts from DB. This device token needs to be uploaded to server for sending push notification to user device.
- When AuthenticatorDelegate instance is not set for the CA Mobile Authenticator APIs, the APIs raise exception with AUTH_STATUS_ERR_INVALID_AUTH_DELEGATE error code. For example,Store *custstorage = [[Store alloc] init];CAAuthenticator *authObj = [[CAAuthenticator alloc] initWithStorageType:custstorage ];
Errors and Exceptions
For more information on Errors and Exceptions, see the following list:
aa821test
saveAccount AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_STORE_WRITE" when SDK is unable to save the account to the inbuilt DB store. deleteAccount AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_BAD_ACCOUNT" if accountId is nil or empty or account is not found with specified accountId Throws AuthenticatorException named "AUTH_STATUS_ERR_STORE_READ" when SDK is unable to read the account from the inbuilt DB store. getAccount AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_BAD_ACCOUNT" if accountId is nil or empty or account is not found with specified accountId Throws AuthenticatorException named "AUTH_STATUS_ERR_STORE_READ" when SDK is unable to read the account from the inbuilt DB store. getAllAccounts AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_BAD_ACCOUNT" if any error occurs while fetching account from DB store Throws AuthenticatorException named "AUTH_STATUS_ERR_STORE_READ" when SDK is unable to read the account from the inbuilt DB store. registerDevice AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_INVALID_AUTH_DELEGATE" if AuthenticatorDelegate object is not set or set "nil" while calling registerDevice API on CAMobileAuthenticator class object. AuthStatusCode Returns AuthStatusCode with value AUTH_STATUS_ERR_INVALID_DEVICE_TOKEN error code if getDeviceToken API called on AuthenticatorDelegate returns "nil" or empty value when called by the SDK. AuthStatusCode Returns AuthStatusCode with value AUTH_STATUS_SENT_DEVICE_REGISTRATION_REQUEST status code if request for device registration is sent to server successfully. AuthStatusCode Returns AUTH_STATUS_FAILED if device registration is failed due to unknown error authenticateUser AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_INVALID_AUTH_DELEGATE" if AuthenticatorDelegate object is not set or set "nil" while calling authenticateUser API on CAMobileAuthenticator class object. AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_INVALID_AUTH_DATA" if authData received by authenticateUser is not in proper JSON format AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_INVALID_AUTH_DATA" if authData JSON format does not contain manadatory fields - "userId", "orgId", "hostName", "txnId" and "serverData". AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_BAD_USER_ID" if authData JSON format does not contain valid "userId" value "userId" value is empty or nil. AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_BAD_NS" if authData JSON format does not contain valid "orgId" value "orgId" value is empty or nil. AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_INVALID_TXN_ID" if authData JSON format does not contain valid "hostName" value "hostName" value is empty or nil. AuthenticatorException Throws AuthenticatorException named "AUTH_STATUS_ERR_BAD_ACCOUNT" if client is unable to fetch the unique account determined by the "userId", "orgId" and "hostName" AuthenticatorException Throws AuthenticatorException with system exception message which contains details because of which client failed to send the authentication request to Server.