BlackBerry Dynamics utility for managing authentication tokens and identity. More...

Public Member Functions
void	GetBBDAuthToken (string challenge, string serverName)

string	GetDynamicsSharedUserID ()

void	GetEIDToken (string clientID, string scope, string resourceServer, bool refresh, BBDJWTokenCallback callback)
	Get JWT from BlackBerry Enterprise Identity (EID) server. More...

Events
EventHandler< BBDAuthTokenSuccessEventArgs >	BBDAuthTokenSuccess

EventHandler< BBDAuthTokenFailureEventArgs >	BBDAuthTokenFailure

Detailed Description

BlackBerry Dynamics utility for managing authentication tokens and identity.

BlackBerry Dynamics Authentication Token Mechanism

The BlackBerry Dynamics authentication token mechanism enables applications to utilize the user identification that takes place during BlackBerry Dynamics authorization processing. This enables an application server at the enterprise to authenticate the user without the need for entry of any additional credentials at the device or desktop.

See below for an overall description of the BlackBerry Dynamics authentication token mechanism. This class includes the programming interface for requesting tokens.

The BlackBerry Dynamics platform includes rigorous authentication of the end user. This is used when, for example, identifying whether the user is entitled to run the current application, and when applying security policies.

The BlackBerry Dynamics Authentication Token (BlackBerry Dynamics auth) mechanism enables applications to take advantage of the authentication processes of the platform.

BlackBerry Dynamics auth tokens can be requested by the application on the device or desktop. A token will only be issued if authorization processing has completed, and the end user's identity has been authenticated.

Once a token has been issued, the application can send the token to an application server at the back end. The token can then be checked by the application server, using a verification service provided by the BlackBerry Dynamics infrastructure.

The sequence of programming interfaces used in BlackBerry Dynamics auth is as follows.

The mobile application calls GetBBDAuthToken(string, string) to request a token.
If accepted, a token is issued and the BBDAuthTokenSuccess event is invoked and passed the new token.
The application sends the token to the application server, using an HTTP request, socket, or other method. In the same communication, the application sends the email address or other end user identifier for which it is activated as a BlackBerry Dynamics application.
The application server checks that the token is valid by calling the verification service in the Authentication Token Back-End API, hosted by an enterprise BlackBerry Dynamics server. (The server could be a BlackBerry Proxy or Good Proxy instance.)
If the token is valid, the response from the verification service includes the end user identifier. The application server can check that the value from the verification service is the same as that originally sent by the mobile application.

This sequence validates the end user's identity, and the application server can then grant access to resources and other permissions.

Calling the verification service doesn't cause the token to be consumed.

Note that a BlackBerry Dynamics application can obtain the identifier of the end user from the BBDAppConfigKeyUserId value in the collection returned by the IBBDXamarin.GetApplicationConfig function.

Challenge Strings

A challenge string can be included in a BlackBerry Dynamics auth token request. The same challenge string will then be provided to the application server, in the response from the verification service.

The challenge string could have a number of uses for application developers. A typical usage could be to tie an instance of authentication to a previous access request, as follows:

A mobile application attempts to access a resource on an application server.
The application server generates a random challenge string.
The application server responds to the mobile application with a denial of access message that includes the random challenge string.
The mobile application requests a BlackBerry Dynamics auth token, and passes the value from the denial of access message as the challenge string.
The mobile application again attempts to access the resource on the application server, but this time includes the BlackBerry Dynamics auth token in the request.
The application server sends the token to the verification service, which responds that the token is valid. The response includes the challenge string.
The application server checks that the challenge string from the verification service is the same as the random challenge string initially sent to the mobile application in the denial of access message.

In this process, a new random challenge string is generated on every resource access attempt. As a result, each BlackBerry Dynamics auth token can only be used one time. A more advanced algorithm might be to store the token and challenge string in the server, as a session identifier. To end a session, the server could delete the stored token and challenge string, effectively forcing the application to generate a new token, based on a new challenge string, when it next connected.

The verification service provides the challenge string to the application server in an HTTP header, which limits the character set that can be used safely. All letters and numerals in the ASCII range 32 to 126 can be used safely. Use of other characters isn't supported.

BlackBerry Dynamics Shared User Identifier

The BlackBerry Dynamics Shared User ID is a unique identifier for all containers which are provisioned for the same user on the same device.

Identifier characteristics

The identifier is available once a user has authorized / unlocked the container.
The identifier is the same for applications activated against the same user, on the same UEM domain and on the same device, even if authentication delegation (SSO) is enabled.
The identifier doesn't persist once the last Dynamics application is uninstalled from a device or the device is reset.
The identifier is only available for applications activated against a UEM. (Not standalone GC)

Shared Identifier limitations

Shared identifier will not be shared among applications from different keychain groups (iOS) or among different Work profiles on the same device (Android).

Member Function Documentation

◆ GetBBDAuthToken()

void BBDXamarinForms.Common.Interfaces.BBDUtility.IBBDUtility.GetBBDAuthToken	(	string	challenge,
		string	serverName
	)

Call this function to request a new BlackBerry Dynamics authentication token. Pass the challenge string and server name as parameters.

See under BlackBerry Dynamics Authentication Token Mechanism, above, for background on tokens and the challenge string.

This function requests a BlackBerry Dynamics authentication token from the BlackBerry Dynamics Runtime. The runtime might connect to the BlackBerry Dynamics infrastructure installed at the enterprise in order to service the request.

The request is asynchronous. If the request succeeds, the token will be passed in BBDAuthTokenSuccess event. If the attempt fails, an error will be passed in BBDAuthTokenFailure event instead.

Parameters

challenge	String containing the challenge string for the token. The challenge string can be empty.
serverName	String containing additional identification, by convention the fully qualified domain name of the application server for which a token is being requested. Whatever value is passed here will also be returned to the server as part of the token validation response.

◆ GetDynamicsSharedUserID()

string BBDXamarinForms.Common.Interfaces.BBDUtility.IBBDUtility.GetDynamicsSharedUserID ( )

Call this method to get a BlackBerry Dynamics shared user identifier.

See under BlackBerry Dynamics Shared User Identifier, above, for background on shared id usage and characteristics.

If calculation of shared id is not possible, empty string will be returned

Returns: Shared identifier string representation if id can be calculated, empty string otherwise

◆ GetEIDToken()

void BBDXamarinForms.Common.Interfaces.BBDUtility.IBBDUtility.GetEIDToken	(	string	clientID,
		string	scope,
		string	resourceServer,
		bool	refresh,
		BBDJWTokenCallback	callback
	)

Get JWT from BlackBerry Enterprise Identity (EID) server.

Call this method to request a BlackBerry Enterprise Identity JWT Bearer Token for authentication purposes. Pass a registered client ID string, scope string and closure reference (for calling back) as parameters. Tokens are cached until expired, but a new token from the server may be specified by setting the refresh flag true.

This method requests a BlackBerry Dynamics JWT from the BlackBerry Dynamics runtime. The runtime might connect to the BlackBerry Dynamics infrastructure installed at the enterprise in order to service the request.

The request is asynchronous.

Parameters

clientID	`String` containing the client ID.
scope	`String` containing the scope for the token.
resourceServer	`String` containing optional resource server specifier (not currently used)
refresh	A flag to force a new token to be fetched from the server.
callback	Reference to BBDJWTokenCallback.

Event Documentation

◆ BBDAuthTokenFailure

EventHandler<BBDAuthTokenFailureEventArgs> BBDXamarinForms.Common.Interfaces.BBDUtility.IBBDUtility.BBDAuthTokenFailure

Occurs when a request for a BlackBerry Dynamics authentication token has failed. Information about the error condition is passed in a parameter.

The request will have been made by calling the GetBBDAuthToken(string, string) function.

Invocation of this callback notifies the application that a token wasn't issued in response to the request.

Depending on the reason for failure, the function that is invoked could:

Retry, by requesting a token again.
Notify the user that this authentication mechanism isn't available.

◆ BBDAuthTokenSuccess

EventHandler<BBDAuthTokenSuccessEventArgs> BBDXamarinForms.Common.Interfaces.BBDUtility.IBBDUtility.BBDAuthTokenSuccess

Occurs when a new BlackBerry Dynamics authentication token has been generated. Token generation is always in response to a call to the GetBBDAuthToken(string, string) function.

The function that is invoked could initiate sending of the token to the application server, out of band. The application server will then be able to utilize the token to authenticate the end user.

Public Member Functions

Events