• BlackBerry Dynamics
  • Runtime library for iOS applications
  • 12.0.1.79
GDAuthenticationManager Class Reference

#import <BlackBerryDynamics/GD/GDAuthenticationManager.h>

Inheritance diagram for GDAuthenticationManager:

Description

Manage user authentication and require the user to authenticate.

Authentication Manager Usage

The Authentication Manager Interface enables an application to request a user to reauthenticate. When called a user will be prompted to authenticate using whatever authentication method is specified by policy. For example, biometrics or security password. If the policy doesn't require a password, then a prompt will be displayed with an 'Authorize' button for the user to acknowledge.

There are two scenarios for using the interface.

Authorize an action

Before permitting a destructive or sensitive action, it may be necessary to confirm such a request is being initiated by an authorized user of the application. For example, during a request to delete all documents or share a file with an external recipient the application may want to first prompt the user to enter their security password. Alternatively, if a user is taking an action on a different device or website, it may be necessary to confirm the authenticity of the request by prompting the user to authorize the action on their BlackBerry Dynamics application, essentially a two-factor authentication (2FA). In this scenario the user is able to cancel the request and continue using the application.

Force reauthentication

The application may want to trigger the runtime state to become locked, perhaps due to a threat which has been detected or an anomaly in user behaviour. To continue using the application the user must authenticate.

Programming Interface and Notifications

To notify the application, the runtime posts an NSNotification.

Code Snippets

The following code snippets illustrate some common tasks.

Request reauthentication

NSNotificationCenter * __weak center = [NSNotificationCenter defaultCenter];
id __block observerToken = [center addObserverForName:GDReAuthenticationResultNotification
object:nil
queue:[NSOperationQueue mainQueue]
usingBlock:^(NSNotification *notification) {
NSLog(@"Received the reauthentication notification!");
NSString *receivedToken = [GDAuthenticationManager getReauthenticationToken:notification];
GDReAuthResult result = [GDAuthenticationManager getReauthenticationResult:notification];
GDReAuthType type = [GDAuthenticationManager getReauthenticationType:notification];
if (result == GDReAuthResultSuccess)
{
NSLog(@"Reauthentication successful, proceed doing your work.");
// do some user action
}
else
{
NSLog(@"Reauthentication Rejected");
}
[center removeObserver:observerToken];
}];
NSString *token = [GDAuthenticationManager reauthenticate:@"Title" message:@"Message" timeoutInSeconds:20 gracePeriodInSeconds:120 enforce:YES requirePassword:YES];

Class Methods

(NSString *) + reauthenticate:message:timeoutInSeconds:gracePeriodInSeconds:enforce:requirePassword:
 Requests user reauthentication. More...
 
(NSString *) + reauthenticate:message:timeoutInSeconds:
 Requests user reauthentication. More...
 
(NSString *) + reauthenticate:message:timeoutInSeconds:gracePeriodInSeconds:
 Requests user reauthentication. More...
 
(NSString *) + getReauthenticationToken:
 Gets token from reauthentication notification. More...
 
(GDReAuthResult+ getReauthenticationResult:
 Gets authentication result from reauthentication notification. More...
 
(GDReAuthType+ getReauthenticationType:
 Gets authentication type from reauthentication notification. More...
 

Method Documentation

◆ reauthenticate:message:timeoutInSeconds:gracePeriodInSeconds:enforce:requirePassword:

+ (NSString *) reauthenticate: (NSString *)  title
message: (NSString *)  message
timeoutInSeconds: (NSUInteger)  timeout
gracePeriodInSeconds: (NSUInteger)  gracePeriod
enforce: (BOOL)  enforce
requirePassword: (BOOL)  requirePassword 

With this call, the user will be prompted to enter credentials into the Blackberry Dynamics Reauthentication screen. This call is non-blocking and will synchronously return the token to associate an event with a specific call. Result of the reauthentication will be received asynchronously with NSNotification.

Parameters
titleThe NSString value used as the title of the BlackBerry Dynamics Reauthentication Screen shown to user. Title text should be less than 30 characters and be the name of the application or system triggering the request.
messageThe message body NSString shown to the user which should be less than 200 characters. The message should explain why the user is being asked to reauthenticate. However it should not make reference to how the user would authenticate as this communication is handled by the runtime.
timeouttimeout value in seconds. The length of time the prompt to authorize is shown to the user. If the user doesn't authorize the request within the timeout a failure callback is sent with the result code GDReAuthResultErrorExpired. The timeout value should be between 0 and 600 seconds. Defining 0 seconds means no timeout is set and the user may choose to either respond to the authentication prompt in their own time or cancel the dialog. Setting a value between 1 - 29 seconds is not recommend as this may not give sufficient time for the user to provider their biometrics or enter their password. If no value is specified a default of 30 seconds is assumed. This value is ignored if enforce is set to true.
gracePeriodThe time in seconds to immediately return with success and without showing the Blackberry Dynamics Reauthentication Screen if the user has recently authenticated within the specified period. If grace period is not specified then it is assumed to be zero.
enforceboolean value to require the application to immediately enter the locked authorization state and present the user with the specified message to authenticate. The user cannot cancel and must authenticate before they can use the application again. If the policy doesn't require a password then enforce is the same as not enforcing i.e. user just acknowledges. If enforce mode is applied, the timeout value is ignored. If enforce is not specified then it is assumed to be false.
requirePasswordboolean value which requires the user to authenticate with a password rather than biometrics. Only applicable when enforce is true. If gracePeriod is set then the runtime shall only return success if the user authenticated using a password within the grace period. i.e. if they authenticated last with biometrics then the prompt to reauthenticate will still be shown. If requirePassword is not specified then it is assumed to be false.
Returns
NSString value token which enables the caller to associate an event with a specific call to the interface (as interface will synchronously return with a unique token for that call)

◆ reauthenticate:message:timeoutInSeconds:

+ (NSString *) reauthenticate: (NSString *)  title
message: (NSString *)  message
timeoutInSeconds: (NSUInteger)  timeout 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ reauthenticate:message:timeoutInSeconds:gracePeriodInSeconds:

+ (NSString *) reauthenticate: (NSString *)  title
message: (NSString *)  message
timeoutInSeconds: (NSUInteger)  timeout
gracePeriodInSeconds: (NSUInteger)  gracePeriod 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ getReauthenticationToken:

+ (NSString *) getReauthenticationToken: (NSNotification *)  notification

This function is a helper that returns the reuthentication token from NSNotification.

Parameters
notificationNSNotification instance which has been received after subscribing on notification with name GDReAuthenticationResultNotification.
Returns
NSString token value for the type of event being notified.

◆ getReauthenticationResult:

+ (GDReAuthResult) getReauthenticationResult: (NSNotification *)  notification

This function is a helper that returns the reauthentication result from NSNotification.

Parameters
notificationNSNotification instance which has been received after subscribing to notification with name GDReAuthenticationResultNotification.
Returns
GDReAuthResult value for the type of event being notified.

◆ getReauthenticationType:

+ (GDReAuthType) getReauthenticationType: (NSNotification *)  notification

This function is a helper that returns the reauthentication type from NSNotification.

Parameters
notificationNSNotification instance which has been received after subscribing to notification with name GDReAuthenticationResultNotification.
Returns
GDReAuthType value for the type of event being notified.

The documentation for this class was generated from the following file:
GDReAuthResultSuccess
@ GDReAuthResultSuccess
Definition: GDAuthenticationManager.h:30
GDReAuthenticationResultNotification
NSString *const _Nonnull GDReAuthenticationResultNotification
NSNotification name for GDAuthenticationManager notifications.
GDReAuthResult
GDReAuthResult
BlackBerry reauthentication result type.
Definition: GDAuthenticationManager.h:27
GDAuthenticationManager
Definition: GDAuthenticationManager.h:88
GDReAuthType
GDReAuthType
BlackBerry reauthentication result type.
Definition: GDAuthenticationManager.h:56