Single-Source BlackBerry Dynamics User Credentials Profile Overview

User Credentials Profiles

The BlackBerry Dynamics runtime synchronizes User Credential Profile (UCP) configuration for app-based certificates from the enterprise management console.

Deprecated:

Since UEM 12.10, UCPs for app-based credentials are no longer supported. Native keystore UCPs are the recommended approach and enable the app to directly access user credentials within the device's key store without requiring importation of key material into the app.

Structure

BlackBerry Dynamics UCP configuration has the following structure.

User Credentials Profile
...
User Credentials Profile
|
|
+---- Credential
      ...
      Credential
      |
      |
      +---- User certificate
      |
      |
      +---- Auxiliary certificate
            ...
            Auxiliary certificate

The configuration can be traversed as follows.

• Call the CredentialsProfile.getMap class method to get the list of profiles that are assigned to the current end user. Each is represented by a CredentialsProfile instance.
• Call the getCredentials instance method to get the credentials within a particular profile. Each is represented by a Credential instance.
• Call the getUserCertificate and getAuxCertificates instance methods to get the certificates associated with a particular credential. Each is represented by a Certificate instance.

Import

The BlackBerry Dynamics runtime has a programming interface by which credentials can be imported by the application code. The interface is session-based.

Deprecated:

Since UEM 12.10, UCPs for app-based credentials are no longer supported. Native keystore UCPs are the recommended approach and enable the app to directly access user credentials within the device's key store without requiring importation of key material into the app.

• Start an import session by calling one of the import class methods in the Credential class.
• Continue the session, if required, by making subsequent import calls.
• Finish the session by calling the finalizeImport class method.

The import interface makes use of formats originally published as Public-Key Cryptography Standards (PKCS). These formats are identified by PKCS numbers.

See also

RFC 7292 PKCS #12: Personal Information Exchange Syntax on the ietf.org website.

Import Requirements

Successful use of the import interface depends on configuration at the enterprise. The end user must be activated against management console software that supports certificate import.

• The BlackBerry Unified Endpoint Manager (UEM) server version 12.7 and later support this feature.
• No version of the legacy Good Control server supports this feature.

See also

BlackBerry UEM Administration guide to application-based Public Key Infrastructure (PKI) connection on the help.blackberry.com website.

Profile State Changes and Import Requests

The state of a UCP, and the UCP configuration, can change. When this happens, the BlackBerry Dynamics runtime notifies the application code by dispatching a UCP event.

UCP events are also used to notify the application in the case that a requirement for credentials arises in another application, that doesn't have the capability to import credentials itself.

An application that has the certificate import capability should implement a UCP event observer, as follows.

To receive notifications, register a receiver class:

• Instantiate a native BroadcastReceiver object.
• Call the GDAndroid registerReceiver method.
  • Pass a reference to the object as the receiver parameter.
  • Pass an Intent Filter for GD_CREDENTIAL_PROFILE_STATE_CHANGE_ACTION as the filter parameter.

When a UCP state change occurs, the BlackBerry Dynamics runtime sends an Android Intent by local broadcast. The Intent will include a Bundle that specifies the details of the change. The CredentialsProfile class includes a number of helper methods for retrieving the details. The helpers are class methods that take an Intent as a parameter and return the detail value. For example, CredentialsProfile.getId(Instance) retrieves the UCP identifier. Note that there are also methods with the same names as the helpers that take no parameters, for example getId(), but these are just normal property value accessors that are called as instance methods.

This following code snippet illustrates registration of a UCP event receiver.

GDAndroid.getInstance().registerReceiver(new BroadcastReceiver() {
    // Override annotation should go here
    public void onReceive(Context context, Intent intent) {
        String identifier = CredentialsProfile.getId(intent);
        // ...
    }
}, new IntentFilter(CredentialsProfile.GD_CREDENTIAL_PROFILE_STATE_CHANGE_ACTION));