BlackBerry Dynamics SDK for Cordova

35 Pages·2017·0.32 MB·English

Development Guide
BlackBerry Dynamics SDK for Cordova
Published: 2017-10-18
SWD-20171204152634181
Contents
About this guide............................................................................................................... 5
BlackBerry Dynamics background....................................................................................6
BlackBerry Dynamics API reference..................................................................................................................................6
US FIPS 140-2 compliance...............................................................................................................................................6
Easy Activation.................................................................................................................................................................7
Securing cut-copy-paste on devices (Data Leakage Prevention, or DLP).............................................................................7
Shared Services Framework..............................................................................................................................................8
Support for fingerprint authentication................................................................................................................................8
Support for client certificates............................................................................................................................................8
Support for "No Password" security policy.........................................................................................................................9
Support for Ionic/AngularJS version 1 and Ionic/AngularJS version 2 on iOS......................................................................10
Support for Ionic and AngularJS version 1 on Android......................................................................................................10
Support for Ionic and AngularJS version 2 on Android......................................................................................................11
Bypassing the App Lock screen.......................................................................................................................................11
Locales...........................................................................................................................................................................11
Requirements.................................................................................................................13
BlackBerry Dynamics software versions..........................................................................................................................13
Compatibility with earlier releases............................................................................................................................13
Unsupported BlackBerry Dynamics features............................................................................................................13
Software requirements....................................................................................................................................................14
Recommended development environment: macOS, not Windows 10........................................................................15
Character encoding for build files: UTF-8.................................................................................................................15
BlackBerry Dynamics entitlement ID and version.............................................................................................................15
Distinction from and use with native language identifiers..........................................................................................17
Including BlackBerry Dynamics entitlement version metadata for the Shared Service Framework.............................18
Setting preferences in config.xml for BlackBerry Dynamics......................................................................................19
Deprecated classes and methods...................................................................................................................................20
Steps to get started with the BlackBerry Dynamics SDK for Cordova................................21
Getting started step-by-step............................................................................................................................................21
Install the BlackBerry Dynamics SDK for Cordova ...........................................................................................................21
Install BlackBerry Dynamics SDK for Android or BlackBerry Dynamics SDK for iOS...................................................22
Directory structure and description of installed plugins.............................................................................................22
Working with the plugins.................................................................................................24
Checking versions of installed plugins..............................................................................................................................26
About the security of Cordova localStorage......................................................................................................................26
Sample apps.................................................................................................................. 28
Testing and troubleshooting............................................................................................29
Automated test support library for iOS.............................................................................................................................29
Logging and diagnostics..................................................................................................................................................29
Log message categories...........................................................................................................................................29
Configure detailed logging for the Xcode console......................................................................................................30
Configure selective logging for the Xcode console.....................................................................................................30
Configure logging in Good Control............................................................................................................................30
GDLogManager class for log uploading.....................................................................................................................31
Readying your app for deployment: server setup............................................................. 32
Legal notice....................................................................................................................33
About this guide
About this guide
1
This guide is an introduction to the BlackBerry Dynamics software development kit (SDK) for Cordova. The guide focuses on
how to install the BlackBerry Dynamics SDK for Cordova, how to use the provided plugins, and introduces the sample apps that
are packaged with the SDK.
This guide is intended for software developers who already have an understanding of developing software with Cordova. For
detailed, guided steps to install SDK, see Getting Started.
This guide is not a tutorial on programming with Cordova. It assumes that you have working knowledge of the language and
concepts. The guide also assumes that you have installed the supported version of Cordova. For information about how to
install, see the instructions from Apache Project at https://cordova.apache.org/docs/en/latest/ or the Node.js site at https://
www.npmjs.com/package/cordova
5
BlackBerry Dynamics background
BlackBerry Dynamics background
2
The following sections provide some background information that can help you understand the features of the BlackBerry
Dynamics SDK.
The way that these features are implemented in your environment will depend on how your administrator has configured your
organization's servers, your network, and other infrastructure.
BlackBerry Dynamics API reference
The BlackBerry Dynamics SDK API reference describes the available interfaces, classes, methods, and much more.
You can access the API reference:
• Online at https://community.blackberry.com/view-doc.jspa?fileName=index.html&docType=android.
• In the installed directories for the BlackBerry Dynamics SDK.
You can access the API reference:
• Online at https://community.blackberry.com/view-doc.jspa?fileName=index.html.
• In the installed directories for the BlackBerry Dynamics SDK. In Xcode, the BlackBerry Dynamics SDK Reference can
be viewed from the Organizer window in the Documentation section in Xcode.
You can access the API reference at https://developer.blackberry.com/files/BlackBerry-Dynamics-for-Cordova/index.html.
US FIPS 140-2 compliance
BlackBerry Dynamics apps must be built to be compliant with U.S. Federal Information Processing Standards (FIPS) 140-2. The
BlackBerry Dynamics SDK distribution contains FIPS canisters and tools and by default enforces FIPS compliance.
On Android, FIPS compliance is automatic; no special build steps are required.
There are two sides to enabling FIPS: the app itself and the policy server, either Good Control or BlackBerry UEM.
The app
When an app starts, it must start in FIPS-compliant mode. The BlackBerry Dynamics SDK determines whether a service is
running in FIPS mode when the app communicates with the server to receive policies. All apps must be written for FIPS
compliance.
6
BlackBerry Dynamics background
The policy server
For pointers to more details on FIPS policies, see the documentation for servers described in Readying your app for deployment:
server setup.
What FIPS compliance enforces
Enabling FIPS compliance enforces the following constraints:
• MD4 and MD5 are prohibited by FIPS, which means that access to NTLM- or NTLM2-protected web pages and files is
blocked.
• Wrapped apps are blocked.
• In secure socket key exchanges with ephemeral keys, with servers that are not configured to use Diffie-Hellman keys
of sufficient length, BlackBerry Dynamics retries with static RSA cipher suites.
Easy Activation
The Easy Activation feature simplifies the provisioning process by allowing a BlackBerry Dynamics app to hand off activation to
an app that is already installed on the device and can act as the activation delegate. The user has to retrieve and manually enter
an access key only the first time they install a BlackBerry Dynamics app.
For more information about enabling Easy Activation, see the Easy Activation Feature Overview.
Securing cut-copy-paste on devices (Data
Leakage Prevention, or DLP)
You can use the BlackBerry Dynamics SDK to protect certain data copied and pasted between apps on your users' devices.
For , you don't need to do any additional programming to support secure cut and paste.
Server administrators must enable the Data Leakage Prevention policies in the management console.
To enable sharing among a group of apps, the apps must be provisioned from the same BlackBerry Control service for each
user.
If the Data Leakage Prevention settings are enabled in your environment, you can work around them when you need to debug
your app. For more information, see https://community.blackberry.com/view-doc.jspa?
fileName=screencapturecontrol.html&docType=android.
7
BlackBerry Dynamics background
Shared Services Framework
BlackBerry Dynamics-enabled apps can communicate with each other using the Shared Services Framework. There are two
kinds of shared services:
• Server-side services
• Client-side services
The BlackBerry Dynamics SDK contains sample apps that show how these services work.
For a conceptual background, see BlackBerry Dynamics Services Framework.
Support for fingerprint authentication
BlackBerry Dynamics's support for fingerprint recognition is a supplement to standard BlackBerry Dynamics secure user
authentication, not a replacement for it. BlackBerry Dynamics includes the following kinds of policies related to fi ngerprint
authenticaton. These settings are configured by way of policies in the server.
• Allow or disallow fingerprint authentication for BlackBerry Dynamics-based apps in general.
• If fingerprint authentication is allowed in general, you can also allow or disallow it for BlackBerry Dynamics apps
immediately after app coldstart. If you do not allow it after app coldstart, the user must enter the password for the app.
• Require the end user to enter a password after a specified interval.
Note: For app developers, no additional programming work is necessary for fingerprint authentication, except for Samsung
Pass, some linking directives are needed. See Info: Add Samsung Pass to your BlackBerry Dynamics app.
For more information see BlackBerry Dynamics and Fingerprint Authentication
Support for client certificates
BlackBerry Dynamics supports many popular uses of client-side Public Key Infrastructure (PKI) certificates to secure apps and
communications:
• General requirements for working with PKI certs
• Description of client certificate sharing among BlackBerry Dynamics apps on a device
• Kerberos PKINIT: client certificates in the Kerberos authentication model. (This is not Kerberos Constrained
Delegation, or KCD).
8
BlackBerry Dynamics background
Support for "No Password" security policy
The BlackBerry Dynamics Runtime now supports the security policy for not requiring the end user to set an app password.
Security consideration
• Consider the security ramifications in your environment carefully. Enabling "no password" is only one of the design
options available. Others include authentication delegation, enabling "no password" on certain devices only, device
management, and more. You should consider enabling "no password" for select groups of users whose devices are
under tight control via device management profiles or other controls.
• Do not enable "no password" and authentication delegation in the same policy set.
• Enabling "no password" does not permit authentication in the background, because there is no authentication.
Software prerequisites
1. Standalone Good Control 3.0.50.70 or later or BlackBerry UEM 12.7 or later
2. The "No Password" policy must be enabled and applied to the desired users or app group.
User-visible changes and behavior
With a BlackBerry Dynamics app that is protected by a security policy that requires a password, if the administrator changes the
security policy to "Do not require a user password":
• The user is shown an informational screen stating that a password is no longer required for the app.
• The user is then in "No Password mode" and is never prompted for password again.
If the user is in "No Password mode" and the administrator changes the security policy to require a password:
• The user is prompted to set a password.
• The user is shown an informational screen stating that a password is now required for the app.
Optional APIs for Android for "No Password" policy
You can call the GDAndroid.getInstance().canAuthorizeAutonomously method to find out if an app is protected
by the security policy to require a password.
Call GDAndroid.serviceInit( ) to start the authorization process when your app has received a GCM message or
background broadcast/explicit intent.
The sample app GDInteraction illustrates the use of these methods.
For syntax and details, see the SDK programming reference.
9
BlackBerry Dynamics background
Optional APIs for iOS for "No Password" policy
You can query the state of the policy with [GDiOS sharedInstance].canAuthorizeAutonomously.
If your app has received an APNS message or a Background Fetch period, or has been launched in the background, you can call
the [GDiOS sharedInstance].authorizeAutonomously method to start the authorization process.
The SecureStore sample app illustrates the use of these methods.
For syntax and details, see the SDK programming reference.
Support for Ionic/AngularJS version 1 and Ionic/
AngularJS version 2 on iOS
On iOS, the BlackBerry Dynamics SDK for Cordova supports all features of AngularJS versions 1.x.x and versions 2.x.x. Ionic
with these versions of AngularJS built in are also supported.
Support for Ionic and AngularJS version 1 on
Android
Except as noted below, the BlackBerry Dynamics SDK for Cordova supports all features of AngularJS version 1.x.x on Android.
Ionic with these versions of AngularJS built in are also supported.
Not supported on Android: Ionic and AngularJS version 1 loading local resources
Loading local bundled resources from the android_assets folder is not supported for Angular v1.x on Android.
Not supported on Android: Ionic and AngularJS version 1 $http method PATCH
The $http HTTP method PATCH is not supported. Using $http.patch returns a 400 Bad Request.
Not supported on Android:Ionic and AngularJS version 1 synchronous requests
Synchronous HTTP requests via XMLHttpRequest are not supported. Instead, they are treated as asynchronous.
Not supported on Android: Ionic and AngularJS version 1 file upload with FormData()
A file upload with FormData() is not supported. Instead, use BlackBerry Dynamics FileTransfer plugin for file upload and
download. For more information on cordova-plugin-bbd-filetransfer, see Directory structure and description of installed
plugins.
10