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

title	The `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.
message	The 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.
timeout	timeout 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.
gracePeriod	The 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.
enforce	boolean 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.
requirePassword	boolean 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

intent Intent 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

intent Intent 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

intent Intent 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.

Description

Authentication Manager Usage

Programming Interface and Notifications

Code Snippets

Request reauthentication

Static Public Member Functions

Static Public Attributes

Member Function Documentation

◆ reauthenticate() [1/3]

◆ reauthenticate() [2/3]

◆ reauthenticate() [3/3]

◆ getReauthenticationToken()

◆ getReauthenticationResult()

◆ getReauthenticationAuthType()

Member Data Documentation

◆ GD_RE_AUTHENTICATION_EVENT