Get Started with BlackBerry Dynamics SDK for Cordova and iOS

Architecture Overview

The BlackBerry Dynamics SDK provides a powerful set of tools to ISV and enterprise developers. It allows developers to focus on building commercial and business apps rather than learning how to secure, deploy, and manage those apps. The BlackBerry Dynamics Platform includes:

• Lifecycle management

• Security and compliance policies

• Secure connectivity to enterprise services

• Secure storage

• Secure inter-app communication

• Application configuration and application specific policies

The simplest way to understand the BlackBerry Dynamics platform is to think of it as three key components: the BlackBerry Dynamics SDK and BlackBerry servers (BlackBerry UEM) connected by BlackBerry Cloud Infrastructre (or Network Operatioons Centre). BlackBerry Dynamics provides the services and architecture to build, securely deploy, and manage apps. BlackBerry UEM includes the BlackBerry Dynamics Secure Mobility Platform and delivers the Enterprise Mobility Management (EMM) solution to securely manage devices.

With the acquisition of Good Technology by BlackBerry, BlackBerry has created a unified product with best-in-class Bring Your Own Device (BYOD), EMM, and Mobile Device Management (MDM) capabilities.

 BlackBerry Dynamics Secure Mobility Platform

The BlackBerry Dynamics (BD) platform consists of BD Runtime, the BD Network Operation Center (NOC), and BD servers.

The BD Runtime is included in every BD mobile app. The runtime has an API that gives the app access to activation, user authentication, secure storage, communication behind the firewall, and much more, all while enforcing security policies on behalf of the organization. To work with the BD Runtime, you need to download the BlackBerry Dynamics SDK for the target platform (iOS, Android, Cordova, React Native).

By including the BlackBerry Dynamics SDK in your app, you will have access to app policies, inter-app communication, secure storage, shared services, authentication delegation, single sign-on (KCD), user and app config information, and much more.

 BlackBerry UEM

BlackBerry UEM is the server component that brings everything together. It merges the best-in-class BYOD functionality of BlackBerry Dynamics with the best-in-class EMM (including MDM) solution. Administrators use UEM to manage users, groups, policies, apps, app configurations, and more.

The BlackBerry Cloud Infrastructure (or NOC) enables secure communication between your BD Runtime app and the BlackBerry Proxy. The BlackBerry Cloud also verifies the validity of user and access keys before data touches your enterprise, in addition to supporting the secure push infrastructure from server-side apps to BD Runtime apps.

UEM includes the BlackBerry Proxy servers as part of the EMM solution. They provide various services to users, devices and apps.

For app developers, you get:

• Security and compliance policies

• Secure connectivity to enterprise services

• App configuration

• App policies

• Secure storage on-device

• Wipe and lock functionality

• Secure inter-app communication

• Application lifecycle management 

BlackBerry Enterprise Mobility Server (BEMS)

The BlackBerry Dynamics platform offers enterprise mBaaS (Mobile Backend as a Service) capabilities. Many of these mBaaS services are implemented in the BlackBerry Enterprise Mobility Server (BEMS). BEMS provides programmatic connectivity through standardized APIs to enterprise systems including Microsoft SharePoint, Microsoft Teams, Microsoft Exchange, Cisco Jabber, Active Directory and more. BEMS provides APIs to invoke services such as push notifications, directory lookups, key value store, document access, IM, and presence. Developers can add these services to apps without having extensive knowledge of how to configure or connect to specific back-end systems of records.

These high quality enterprise back-end services are leveraged by BlackBerry Work, BlackBerry Connect, and other BlackBerry Secured apps. ISV and custom BlackBerry Secured apps can also make use of these services.

A Closer Look at the BlackBerry Dynamics SDKs

The BlackBerry Dynamics Platform provides a range of SDKs and plug-ins, allowing developers to work in familiar environments to build native, hybrid, and web apps. Once apps are built, developers can assume the role of an IT admin to quickly validate the management and distribution of their apps through the BlackBerry Dynamics Platform.

The BlackBerry Dynamics SDK is available natively to major platforms and development technologies including iOS and Android.

In addition, BlackBerry supports cross-platform development frameworks via dedicated BlackBerry Dynamics SDKs for Cordova and React Native.

Security Services

Security Services allow you to address security concerns about making sensitive company information available on mobile devices. You can ensure that the content that is stored on devices, exchanged with resources behind the corporate firewall, or shared between BlackBerry-secured apps is always encrypted. Since the platform uses government-grade device-independent crypto libraries, content is always encrypted. The BlackBerry Dynamics SDK includes support for the following security services:

• Identity & Authorization APIs

• Secure Storage APIs

• Secure Communications APIs

• Secure Inter-App Data Exchange APIs

Mobile Services

Mobile Services allow you to create engaging apps that will improve user productivity. You can reduce development time by using existing services -- no more building everything from scratch! And because the BlackBerry Dynamics Platform is the foundation for all services, government-grade encryption ensures end-to-end security. The BlackBerry Dynamics SDK includes support for the following mobile services:

• Presence Service

• Send Email Service

• Transfer Files Service

• Push Service

• Directory Lookup Service

• Docs Service

• Launch Service

Platform Services

Platform Services make it easy to integrate apps with enterprise infrastructure (e.g., Active Directory, SharePoint, Exchange, Office 365, Lync). Focus on creating innovative apps without worrying about programming for the back-end, server maintenance, or deploying complex infrastructure. Single sign-on, horizontal scaling, HA/DR, VPN-less access to the intranet -- simply building on the current version of the BlackBerry Dynamics Platform enables it all. The BlackBerry Dynamics SDK includes support for the following mobile services:

• Identity & Access Management

• Single Sign-on Authentication

• Reliable App Deployment at Scale

• Secure Access to Corporate Data

• App-Level Controls for IT

Software requirements

See Requirements and support for platform-specific features in the BlackBerry Dynamics SDK Development Guide.

Install the BlackBerry Dynamics SDK for Cordova

1. Visit BlackBerry Developer Downloads to download the BlackBerry Dynamics SDK for Cordova.

2. Extract the BlackBerry Dynamics SDK for Cordova package to the desired project directory.

3. When you add the BlackBerry Dynamics Base plug-in to your project, the BlackBerry Dynamics SDK for iOS is automatically downloaded using CocoaPods. For additional information, see the BlackBerry Dynamics SDK Development Guide.

4. Install Xcode.

5. Install Node.js.

After the installation completes, the npm command is available in your terminal shell.

• In the config.xml file, set the following to enable the enterprise discovery scheme that is required for key BlackBerry Dynamics features:

<preference name=“BBD_Enterprise_Discovery” value=“true” />

• To enable enterprise simulation mode, in the config.xml file, set the following:

<preference name=“GDEnterpriseSimulationMode” value=“true” />

We’ll be using the standard Cordova CLI to execute all commands.

1. Open your favorite Terminal program.

2. Create a new Cordova project.

$ cordova create HelloBBD com.company.appname

3. Change to the project folder.

$ cd HelloBBD

4. Add platforms.

$ cordova platform add ios

5. Add BlackBerry Dynamics plug-ins. At a minimum, you must add the base plug-in if you want to secure your application with BlackBerry Dynamics.

$ cordova plugin add <path-to-bbd-cordova-plugins>/cordova-plugin-bbd-all

6. Optionally, install the ios-deploy package if you want to install iOS apps from the Cordova command-line.

$ sudo npm install –g ios-deploy

• If your macOS is v10.11 or greater, you will likely need to run the following command instead:

$ sudo npm install –g ios-deploy --unsafe-perm=true

7. Build the application in Terminal (or Xcode).

$ cordova build ios

You can now deploy and test your app, and can explore development with additional BlackBerry Dynamics APIs.

Enterprise Simulation Mode

To run and test any BlackBerry Dynamics app, a BlackBerry UEM server is needed but, with considerable limitations, Enterprise Simulation Mode can be used to test an app without a connection to a BlackBerry UEM server

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If the app requires a connection behind the firewall then a BlackBerry UEM server is needed.

Important: the Enterprise Simulation Mode is not intended for a production environment and it is limited to run on an iOS simulator only.

 Although Enterprise Simulation Mode is not suitable for the production deployment of an app, it is useful during development, and for verifying proper execution and behavior when migrating existing apps to BlackBerry Dynamics.

In simulation mode, a valid activation key is not required to open the app because there is no direct communication with BlackBerry Dynamics servers. Communication with the BlackBerry Dynamics NOC, however, continues to take place.

 To enable Enterprise Simulation Mode for a BlackBerry Dynamics app, add the following to the root config.xml file and rebuild the project:
 

<preference name=“GDEnterpriseSimulationMode” value=“true” />

To disable it, change the value to false or remove the preference altogether.

When a BlackBerry Dynamics app is running for the first time on a target, it needs to be activated with the BlackBerry Dynamics server. In Enterprise Simulation Mode, any email address and any 15-character access key are valid to complete the activation process. After the app is activated, the app will prompt the user to create a password.

The Password Requirements link at the bottom of the screen provides guidance on the required password complexity. When not running in Enterprise Simulation Mode the password complexity is controlled via policies managed by your IT admin through the UEM management console.

Enterprise Simulation Mode presents the following differences from standard enterprise execution:

• [Simulated] will appear in the BlackBerry Dynamics Runtime user interface

• Any email address and activation key will be accepted for enterprise activation

• No information is actually sent to enterprise servers, including the email address and activation key

• The provisioning and policy setup flow is simulated in the UI

• A hard-coded set of security and compliance policies are in effect; authentication is not delegated

• When run on a real device, not an emulator, the app will be wiped

• Attempts to change the mode from GDEnterprise to GDEnterpriseSimulation for an app that is already installed on a device will result in the app being wiped

• No lost-password recovery is available

• Inter-container Communication (ICC) cannot be used, which means that the BlackBerry Dynamics Services API cannot be used

Otherwise, the secure storage, secure communication, and push channel APIs are all available in Enterprise Simulation Mode.

The communication APIs will not be able to connect to any enterprise app servers through the UEM server, although direct connections to enterprise app servers can still be made, if, for example, the iOS Simulator is running on a machine that is on the enterprise network or VPN.

Using BlackBerry UEM server

A BlackBerry UEM or BlackBerry UEM Cloud instance is required to perform testing on an actual smartphone or tablet.

Follow the required steps to configure a BlackBerry Secured app for testing in UEM. If you do not yet have a UEM instance in place, you can configure one with a free developer trial license. Click here to generate a trial license and start configuring your server.

Once the servers are in place, continue with the following steps.

1) Configure the app on BlackBerry UEM or BlackBerry UEM Cloud

The first thing to do is to define the app in the BlackBerry UEM 

1. Log in to the BlackBerry UEM management console.

2. Click Apps > New App > Internal BlackBerry Dynamics app entitlements > Next.

3. Specify the BlackBerry Dynamics Entitlement ID and BlackBerry Dynamics Entitlement Version that was set in the Info.plist file. For example, com.mycompany.testApp and 1.0.0.0.

4. Click Add.

Your application will be included in the list of available apps. If you need to provide additional configuration parameters for your app, such as whitelisting servers or configuring an app policy, select your app from the list and configure it as necessary.

Recommendation: Add the Bundle ID to the app’s configuration. This allows the use of Easy Activation, which avoids the requirement of entering an access key when first starting the app. This is also required if your app uses any BlackBerry AppKinetics services.

To add these values:

1. Click the app.

2. On the iOS tab, enter the appropriate value

3. Click Save.

2) Disable Anti-Debug detection

BlackBerry UEM has the capability to prevent debug versions of BlackBerry Dynamics apps from being run. To allow for app development, this must be disabled in the Compliance profile assigned to the user used for testing.

To disable the policy, follow the steps below:

1. Log in to the UEM management console.

2. On the left menu, click Policies and profiles > Compliance.

3. Open the compliance profile assigned to the test user.

4. On the iOS tab, if Jailbroken OS is checked, ensure that Enable anti-debugging for BlackBerry Dynamics apps is not selected.

3) Entitle app users

After an app is registered in a BlackBerry UEM server, users must be entitled to install and use the app. Individual users or user groups can be entitled to an app. For production deployment, it’s recommended to use user groups. When developing or testing, individual users can be used.

To entitle an app to an individual user, follow the steps below:

1. Log in to the UEM management console.

2. Search for and select a user account.

3. In the Apps section in the user profile, click +.

4. Search for and select your app.

5. Click Next.

6. Leave the Disposition as optional (installation will not be forced) and click Assign.

7. Depending on your authentication delegate configuration, you may need to generate an Activation Password that will be used when the app is run for the first time after installation.

To generate a new Activation Password:

1. In the user's profile, under the Summary tab, click Set activation password.

2. In the Activation option drop-down list, click Default device activation.

3. In the Activation password drop-down list, click Set device activation password.

4. In the Device activation password text field enter the password to be used when the app is run for the first time after installation.

5. For development purposes, it can be useful to extend the Activation period expiration to the maximum allowed (30 days)

6. Click Submit.

7. The user receives an email with the credentials and a QR code that can be used to activate the app when it's first run after installation.
   The email sent to the user can be seen also from the UEM console by clicking on the link "View activation email"

8. Install the app to the intended target using the preferred deployment method (including via Xcode).

9. When prompted select an activation type between the ones available 

   • Use "enter credentials" to use email and activation password directly.

   • Use "Scan QR code" if the app is running on a device with a camera and the QR code from the activation email is available to scan even from a screen.

You can continue to explore the available plugins that expose different APIs and read developer resources. Learn about some of the common plugins below.

You may want to learn more about the BlackBerry DynamicsCordova  Plugins and how they work with your project. If you’ve built projects with Cordova plugins in the past, using the BlackBerry Dynamics plugins will be familiar to you.

Some features will automatically be available to your project after adding the cordova-plugin-bbd-base plugin such as XMLHttpRequest, fetch etc.

To see the full details of BlackBerry Dynamics Cordova APIs, see the  BlackBerry Dynamics SDK for Cordova API Reference.

The SDK package includes sample applications that show best practices when using the BlackBerry Dynamics Cordova Plugins.

Generally, it’s recommended to use the cordova-plugin-bbd-all plugin to enable access to all BlackBerry Dynamics APIs. If more granular control is required, you can also install only the bare minimum of required plugins for your app.

File System

cordova-plugin-bbd-file plugin enables you to manage the FileSystem residing within the BlackBerry Dynamics secure container using a similar JavaScript API to the original File plugin.

cordova-plugin-bbd-file-transfer plugin enables you to securely upload and download files within the BlackBerry Dynamics secure container using a similar JavaScript API to the original FileTransfer plugin.

cordova-plugin-bbd-media-capture plugin enables you to capture audio, video and images using the device's microphone or camera and store them within the BlackBerry Dynamics secure container using a similar JavaScript API to the original MediaCapture plugin.

cordova-plugin-bbd-storage plugin is an interface representing a secure localStorage.

Networking

When making HTTPS requests through an HTTP proxy, SSL/TLS certificate verification must be disabled. Certificate verification while using an HTTP proxy is not supported. BlackBerry Dynamics HTTP data communication does not go via the proxy specified in the device's native settings, if any.

The BlackBerry Dynamics Runtime supports Basic Access, Digest Access, NTLM, and Kerberos for authentication with HTTP servers. Except for Kerberos, all these mechanisms are also supported for authentication with HTTP proxies. The BD Runtime supports Kerberos version 5 authentication.

By default, HTTP cookies received through Good Dynamics secure communication are handled automatically.
 

Default networking

This plugin overrides the default APIs XMLHttpRequest and fetch() to retrieve the necessary objects automatically upon installation of the cordova-plugin-bbd-base plugin. Calls made via XHR or fetch will automatically route through the BlackBerry Dynamics Proxy.
 

HttpRequest

cordova-plugin-bbd-httprequest plugin is used to send HTTP requests over the internet. It also encapsulates the HTTP response returned from an HttpRequest's send function.
 

WebSocket

cordova-plugin-bbd-websocket plugin implements the secure WebSocket APIs based on standard WebSocket specification (see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
 

InAppBrowser

cordova-plugin-bbd-inappbrowser plugin enables you to securely load helpful articles, videos, and web resources inside of your app without leaving your app. It is a fork of cordova-plugin-inappbrowser.
 

TokenHelper

cordova-plugin-bbd-tokenhelper plugin is used to request token from server side and process callback on the response.
 

Socket

cordova-plugin-bbd-socket plugin provides access to the secure Socket communications API.

SQLite

cordova-plugin-bbd-sqlite-storage plugin enables you to securely create and manage an SQLite database within the BlackBerry Dynamics secure container using a similar JavaScript SQLite API to the original plugin.

ICC

cordova-plugin-bbd-appkinetics plugin provides the functionality of AppKinetics - the ability to securely communicate between Dynamics applications.

cordova-plugin-bbd-interappcommunication plugin is used to return information about a service provider application(s) of app-based services.

cordova-plugin-bbd-mailto plugin provides functionality to securely compose emails with attachments.

Launcher

cordova-plugin-bbd-launcher plugin is used to show the BlackBerry Dynamics Launcher in your application.

Other plugins

cordova-plugin-bbd-application plugin provides access to information that is globally available to any BlackBerry Dynamics Application.

cordova-plugin-bbd-push plugin encapsulates the response returned from the GDPush class.

cordova-plugin-bbd-specificpolicies plugin is used to read application-specific policy from UEM console and return it in JSON format.

cordova-plugin-bbd-serversideservices plugin provides the ability to use BBD Server Based Services. It returns all the needed information about the service in JSON format.

Secure Copy, Paste and AutoFill Operations

The BlackBerry Dynamics runtime may secure or block text in transit to or from the clipboard, depending on the policies for data leakage prevention (DLP) policy configured in BlackBerry UEM.

The runtime secures text by encrypting it when it is cut or copied to the device clipboard, and then decrypting it when it is pasted from the clipboard.

These operations are handled automatically by the BlackBerry Dynamics Runtime. No coding changes are required to support this feature.