iOS SDK - Authentication Module

Use the endpoints of this module to provide secure access to the owner of a registered mobile wallet through a variety of identification verification techniques.

Initialize Authentication Facade

Prior to invoking any authentication module endpoints:

  1. Create a new request object for the relevant coordinator.
  2. Implement the delegate for the coordinator to handle responses.
self.authenticationCoordinator = [[PDAthenticationCoordinator alloc] init];
self.authenticationCoordinator setDelegate:self];

loginByUsernamePassword

Authenticates the user's identity through username and password credentials.

Element Value
Method Signature -(void) loginByUsernamePassword: (NSString *)username password: (NSString *)paramPassword;

username - The username value entered in the login form.
paramPassword - The password value entered in the login form.
Success 1 -(void)authenticationDidSucceed ();

Configure this delegate to return simple acknowledgment of authentication success.
Success 2 -(void)authenticationDidSucceed: withAdditionalAttributes: (NSDictionary *)additionalAttributes;

Configure this overloaded delegate to return additional data related to the wallet (such as lastPasswordUpdate) in order to customize the user experience, for example, Password is about to expire!

additionalAttributes - A set of key value properties for the platform to populate in the success delegate response.
Success 3 -(void)mfaQuestionDidPrompt: (PDMFAToken*)mfaQuestionToken;

Secures multi-factor authentication (MFA) because the device is not registered with the authenticated account.
mfaQuestionToken - A randomly selected secret question that the user previously answered. Prompt the user to enter the answer to the question, then invoke the registerWithMFA method.
Failure authenticationDidFail:(PDPaydiantError*) authenticationError;

The login attempt failed.
authenticationInvocationDidFail:(PDPaydiantError *) authenticationError;
The call did not reach the authentication service.

Configure user error messages for this call with the key kUserErrorLoginWithUsernamePasswordDomain.

Error Description
401 The login credentials are not correct.
412 The device is not linked to the user registration and requires secondary authentication. This status code is not an error, but is returned with the mfaQuestionDidPrompt delegate.
418 Email verification is not complete.
500 An unknown error occurred internally in the server.
508 The password has expired and must be updated, per the issuer's specification.
511 Application instance verification is not complete.

loginByPIN

Authenticates the user's identity through a personal identification number (PIN).

Element Value
Method Signature -(void) loginByPIN: (NSString *)pin;

pin - The PIN value entered in the login form.
Success 1 -(void)authenticationDidSucceed ();

Configure this delegate to return simple acknowledgment of authentication success.
Success 2 -(void)authenticationDidSucceed: withAdditionalAttributes: (NSDictionary *)additionalAttributes;

Configure this overloaded delegate to return additional data related to the wallet (such as lastLogin) in order to customize the user experience (for example, "Welcome back!").
additionalAttributes - A set of key value properties for the platform to populate in the success delegate response.
Failure authenticationDidFail: (PDPaydiantError*)authenticationError;
The login attempt failed.

authenticationInvocationDidFail:(PDPaydiantError *)authenticationError;
The call did not reach the authentication service.

Configure user error messages for this call with the key kUserErrorLoginWithPinDomain.

Error Description
401 The login credentials are not correct.
418 Email verification is not complete.
500 An unknown error occurred internally in the server.
508 The password has expired and must be updated, per the issuer's specification.
511 Application instance verification is not complete.

loginByNonce

Allows a third-party to authenticate a user by issuing a one-time token that can be used to validate a user's access permission without having to prompt the user for login credentials input.

Element Value
Method Signature -(void) loginByNonce: (PDLoginByNonceRequest*)request;

request - Passes a nonce authentication token value obtained from a third party such as an external identity provider or device level authentication, as well as any other properties relevant to external authentication.
Success 1 -(void)authenticationDidSucceed (PDLoginResponse*)loginResponse;

Configure this delegate to return simple acknowledgment of authentication success.
loginResponse - An instance that confirms the third party validation of the user and passes any additional data parameters specified in the request.
Success 2 -(void)mfaQuestionDidPrompt: (PDMFAToken*)mfaQuestionToken;

Invoked when multi-factor authentication (MFA) is enabled by the issuer for first-time authentication of unregistered devices.
mfaQuestionToken - A randomly selected secret question that the user previously answered. Prompt the user to enter the answer to the question, then invoke the registerWithMFA method.
Failure authenticationDidFail: (PDPaydiantError*)authenticationError;

The login attempt failed.
authenticationInvocationDidFail:(PDPaydiantError *) authenticationError;
The call did not reach the authentication service.

Configure user error messages for this call with the key kUserErrorLoginWithNonceDomain.

Error Description
401 The login credentials are not correct.
412 The device is not linked to the user registration and requires secondary authentication. This status code is not an error, but is returned with the mfaQuestionDidPrompt delegate.
418 Email verification is not complete.
421 Wallet is deactivated due to consecutive failed login attempts.
423 Device is deactivated due to consecutive failed login attempts.
500 An unknown error occurred internally in the server.
503 The device is suspended.
511 Application instance verification is not complete.

loginByFederatedIdentity

Authenticates a user using federated credentials that are managed by an external identity provider (IDP), such as the Issuer's user repository or a social network repository.

Element Value
Method Signature -(void) loginByFederatedIdentity: (PDLoginByFederatedIdentityRequest*)request;

request- Passes the user's input credentials, as well as an IDP authorization code (obtained by the app via direct call to the IDP, not through the Paydiant SDK) and any other properties required for federation by the IDP.
Success 1 -(void)authenticationDidSucceed (PDLoginResponse*)loginResponse;

Configure this delegate to return simple acknowledgment of authentication success.
loginResponse - An instance that confirms the IDP validation of the user and passes any additional data parameters specified in the request.
Success 2 -(void)mfaQuestionDidPrompt: (PDMFAToken*)mfaQuestionToken;

Invoked when multi-factor (MFA) authentication is enabled by the issuer for first-time authentication of unregistered devices.
mfaQuestionToken - a randomly selected secret question that the user previously answered. Prompt the user to enter the answer to the question, then invoke the registerWithMFA method.
Failure authenticationDidFail:(PDPaydiantError*)authenticationError;
The login attempt failed.

authenticationInvocationDidFail:(PDPaydiantError *)authenticationError;
The call did not reach the authentication service.

Configure user error messages for this call with the key kUserErrorLoginWithFederatedIdentityDomain.

Error Description
401 The login credentials are not correct.
412 The device is not linked to the user registration and requires secondary authentication. This status code is not an error, but is returned with the mfaQuestionDidPrompt delegate.
418 Email verification is not complete.
421 Wallet is deactivated due to consecutive failed login attempts.
423 Device is deactivated due to consecutive failed login attempts.
500 An unknown error occurred internally in the server.
503 The device is suspended.
511 Application instance verification is not complete.

isAuthorizationTokenExist

Checks the device status to determine whether the wallet user has consented to enabling long-lived authentication sessions, which allow the app to remain continuously logged in without requiring re-authentication. This type of authentication is mostly used in conjunction with device-level authorization, such as Touch ID.

Note: Long-lived authentication is not permitted for SSO or Federated Identity managed authentication. Paydiant must be the user profile system of record to implement log-lived sessions.

Element Value
Method Signature -(BOOL)isAuthroizationTokenExist
Returns TRUE - A long-running session is active.
FALSE - Long-running session is disabled, possibly due to token expiration or user refusal.

generateDeviceAuthenticationTokenForUsername

Generates a device-specific authentication token that enables authentication without user login for the duration of a long-running session.

Note: Paydiant does not enable or implement Touch ID or any other device-level user authentication. Since a long-lived session provides access to the app based solely on device recognition, it is up to the developer to ensure that user authentication is secured before passing the authorization token.

Element Value
Method Signature -(void) generateDeviceAuthenticationTokenForUsername: (PDGenerateDeviceAuthenticationRequest*)request;

request - Passes the user-input username and password credentials.
Success (^GenerateDeviceAuthenticationTokenForUsernameCompletionBlock) (void);

Generates the Device Authentication token, which is managed within the SDK's fingerprint profile for the device. The token is retrieved as needed for login and is never passed to the device; therefore, no payload is returned to the app.
Failure (^GenerateDeviceAuthenticationTokenForUsernameFailureBlock)(PDPaydiantError*authenticationError);

Configure user error messages for this call with the key kUserErrorGenerateDeviceAuthenticationTokenDomain.

Error Description
400 BAD_REQUEST
432 - Device authentication is not supported for this app.
401 (UNAUTHORIZED)
419 - User authentication failed.
500 INTERNAL_SERVER_ERROR

loginWithDeviceAuthenticationToken

Accesses the wallet app using a stored long-running authentication token.

Important: This method does not enforce user authentication, so Paydiant requires using it only in conjunction with device-level authentication such as Touch ID.

Element Value
Method Signature -(void) loginWithDeviceAuthenticationToken;

This method does not take any parameters from the app. The SDK retrieves and passes the stored token upon invocation.
Success (^LoginWithDeviceAuthenticationTokenCompletionBlock) (void);

Returns no payload, but signals successful authentication.
Failure (^LoginWithDeviceAuthenticationTokenFailureBlock)(PDPaydiantError*authenticationError);

Configure user error messages for this call with the key kUserErrorLoginWithDeviceAuthenticationTokenDomain.

Error Description
401 UNAUTHORIZED - The device authentication token has expired. Generate a new token to establish a new long-lived session.
412 DESTINATION_LOCKED - The wallet account has been deactivated.
423 LOCKED - The device has been deactivated.
500 INTERNAL_SERVER_ERROR
1003 No authentication token exists for the device.

expireDeviceAuthenticationToken

Ends a long-running authentication session and reverts to one of the standard login methods if, for example, the user disables device-level authentication. If device authentication is then re-enabled, generate a new token.

Element Value
Method Signature -(void) expireDeviceAuthenticationToken;
Success (^expireDeviceAuthenticationTokenCompletionBlock)(void);
Failure (^expireDeviceAuthenticationTokenFailureBlock)(PDPaydiantError*authenticationError);

Configure user error messages for this call with the key kUserErrorExpireDeviceAuthenticationTokenDomain.

Error Description
400 BAD_REQUEST
403 - The token is already expired.
500 INTERNAL_SERVER_ERROR
1003 No authentication token exists for the device.

logout

Terminates a user's active session with the app and locks the functional aspects of the app until authentication is re-verified.

Note: Ensure that any sensitive data retrieved by the app is cleared from the app's memory cache when the logout method is invoked.

Element Value
Method Signature -(void) logout;
Success (void)finishedLogout;
Failure authenticationDidFail:(PDPaydiantError*)authenticationError;
The logout attempt failed.

authenticationInvocationDidFail:(PDPaydiantError *)authenticationError;
The call did not reach the authentication service.

Configure user error messages for this call with the key kUserErrorLogoutDomain.

Error Description
403 The user is not currently logged in.

registerWithMFA

Submits secondary authentication "secret question" credentials in order to link a device with an existing mobile wallet profile.

Note: If the Issuer has enabled push notifications, be sure to prompt the user for permission at this time. See Push Notifications Module and Security Requirements for details.

Element Value
Method Signature -(void) registerWithMFA: (PDMFAToken*)mfaToken;

mfaToken - Represents a single multi-factor question and its corresponding answer. The question was populated in the authentication delegate response; populate the answer with the user's input response to the question.
Success 1 -(void)authenticationDidSucceed ();

Configure this delegate to return simple acknowledgment of authentication success.
Success 2 -(void)authenticationDidSucceed: withAdditionalAttributes: (NSDictionary *)additionalAttributes;

Configure this overloaded delegate to return additional data related to the wallet (such as lastPasswordUpdate) in order to customize the user experience (for example, "Password is about to expire!").

additionalAttributes - A set of key/value properties for the platform to populate in the success delegate response.
Failure authenticationDidFail:(PDPaydiantError*)authenticationError;

The login attempt failed.
authenticationInvocationDidFail:(PDPaydiantError *)authenticationError;
The call did not reach the authentication service.

Configure user error messages for this call with the applicable login key, either: kUserErrorLoginWithNonceDomain, kUserErrorLoginWithUsernamePasswordDomain, or kUserErrorLoginWithFederatedIdentityDomain.

Error Description
401 The login credentials are not correct.
500 An unknown error occurred internally in the server.
Feedback

Have feedback?

Let us know.