• BlackBerry Dynamics
  • Runtime library for Android applications
  • 9.2.0.99
AuthenticationManager Class Reference

BlackBerry Dynamics Authentication Manager. More...

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 sends an Intent, by local broadcast. The attributes of the Intent and its Bundle will specify the reauthentication token and the details of the requests like result, error code and the type of the authentication which was used by the user.

Code Snippets

The following code snippets illustrate some common tasks.

Request reauthentication

The following snippet shows how to register Broadcast receiver to receive Reauthentication callback:

System.out.println("Request reauthentication");
BroadcastReceiver reauthReceiver = new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
String reauthToken = AuthenticationManager.getReauthenticationToken(intent);
ReAuthResult reauthResult = AuthenticationManager.getReauthenticationResult(intent);
ReAuthType reAuthType = AuthenticationManager.getReauthenticationAuthType(intent);
Log.i(TAG, "onReceive: token: " + reauthToken);
Log.i(TAG, "onReceive: result: " + reauthResult);
Log.i(TAG, "onReceive: type: " + reAuthType);
}
};
GDAndroid.getInstance().registerReceiver(reauthReceiver,
new IntentFilter(AuthenticationManager.GD_RE_AUTHENTICATION_EVENT));
String token = AuthenticationManager.reauthenticate("Title", "Message", 20, 120, true, false);

Static Public Member Functions

static String reauthenticate (String title, String message, int timeout, int gracePeriod, boolean enforce, boolean requirePassword)
 Request user reauthentication. More...
 
static String reauthenticate (String title, String message, int timeout, int gracePeriod)
 Request user reauthentication. More...
 
static String reauthenticate (String title, String message, int timeout)
 Request user reauthentication. More...
 
static String getReauthenticationToken (Intent intent)
 Get token from reauthentication notification. More...
 
static ReAuthResult getReauthenticationResult (Intent intent)
 Get authentication result from reauthentication notification. More...
 
static ReAuthType getReauthenticationAuthType (Intent intent)
 Get authentication type which was used for reauthentication prompt. More...
 

Static Public Attributes

static final String GD_RE_AUTHENTICATION_EVENT = "com.good.gd.GD_RE_AUTHENTICATION_EVENT"
 Intent Filter key for changes to BlackBerry Dynamics reauthentication result. More...
 

Member Function Documentation

◆ reauthenticate() [1/3]

static String reauthenticate ( String  title,
String  message,
int  timeout,
int  gracePeriod,
boolean  enforce,
boolean  requirePassword 
)
static

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 Dynamics Local broadcast notification intent, which was previously registered.

Parameters
titleThe String 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 String 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
String 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() [2/3]

static String reauthenticate ( String  title,
String  message,
int  timeout,
int  gracePeriod 
)
static

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

◆ reauthenticate() [3/3]

static String reauthenticate ( String  title,
String  message,
int  timeout 
)
static

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

◆ getReauthenticationToken()

static String getReauthenticationToken ( Intent  intent)
static

This method is a helper that returns the reauthentication token from Broadcast Notification Intent which can be used to associate with the initial request.

Parameters
intentIntent that was sent by local broadcast for a AuthenticationManager reauthenticate notification.
Returns
String containing the AuthenticationManager token.

See GD_RE_AUTHENTICATION_EVENT for details on how to register and receive Broadcast Notification Intent

◆ getReauthenticationResult()

static ReAuthResult getReauthenticationResult ( Intent  intent)
static

This method is a helper that returns the reauthentication result from Broadcast Notification Intent.

Parameters
intentIntent that was sent by local broadcast for a AuthenticationManager reauthenticate notification.
Returns
ReAuthResult value for the type of event being notified. See ReAuthResult enumeration.

See GD_RE_AUTHENTICATION_EVENT for details on how to register and receive Broadcast Notification Intent

◆ getReauthenticationAuthType()

static ReAuthType getReauthenticationAuthType ( Intent  intent)
static

This method is a helper that returns the reauthentication type from Broadcast Notification Intent

In case of successful reauthentication, returns Auth type user has used to complete authentication prompt, otherwise this will be the default value

Parameters
intentIntent that was sent by local broadcast for a AuthenticationManager reauthenticate notification.
Returns
ReAuthType value for the type of event being notified. See ReAuthType enumeration.

See GD_RE_AUTHENTICATION_EVENT for details on how to register and receive Broadcast Notification Intent

Member Data Documentation

◆ GD_RE_AUTHENTICATION_EVENT

final String GD_RE_AUTHENTICATION_EVENT = "com.good.gd.GD_RE_AUTHENTICATION_EVENT"
static

Use this value as the Intent Filter key to register a broadcast receiver that will be notified when there is a reauthentication result available.

Broadcast Notification Intent will be received on the Main application thread, so this should be considered in the concurrent environment.

See the GDAndroid.registerReceiver method of how to use this Intent Filter key. See the AuthenticationManager class reference for more details.