BlackBerry ID provider (ids_blackberry_id.h)

BlackBerry ID is one of the identity providers that you can integrate in your application.

Using the BlackBerry ID service as an identity provider, you can enhance your app in several ways:

User authentication without prompting for credentials

Benefits of implementing BlackBerry ID user authentication:
  • Eliminate the need to build your own username and password management.
  • Automatically sign users in to your app after they sign in with their BlackBerry ID account on their devices. This makes your app easier to use.
  • Eliminate the need for users to create and remember a username and password for your app.

User authorization to access other BlackBerry apps and off-device services

If your app interacts with an off-device service that requires user authentication (for example, a website that requires the user to sign in with a username and password), you can use BlackBerry ID APIs to perform the off-device authentication/authorization using tokens, instead of prompting the user for credentials. Your app and the off-device service interact seamlessly.

Access personal information associated with BlackBerry ID accounts

You can personalize the user experience of your app by incorporating your users' personal information in your app. Users must allow your app to access the information associated with their BlackBerry ID accounts before you can access it. The application must have the read_personally_identifiable_information permission included in their BAR application descriptor file. The information that is available includes:
  • first name
  • last name
  • screen name
  • username (an email address)

The ids_get_properties function can be used to retrieve personal information stored in the BlackBerry ID account system, with BBID_PROPERTY_CORE passed as the type parameter (see code samples below).

Sample code for using BlackBerry ID as the identity provider for your app

In order to use BlackBerry ID as the identity provider for your app, you need to use the IDS APIs defined in the ids.h library.

Setting up your app to use BlackBerry ID as an identity provider:
  • Step 1 - Initialize the IDS library for use by your app. You only need to do this once.
  • Step 2 - Register with the Identity Service to use BlackBerry ID as an identity provider.
  • Step 3 - Add a file descriptor (FD) handler to handle communication with the IDS library.

Once these steps have completed successfully, the app can use the IDS APIs to store and retrieve data off the device, retrieve the user's personal information associated with their BlackBerry ID account, and use tokens for authentication and authorization.

This code sample shows how to initialize the IDS library:

// Make sure to include the following header files in your application
#include <errno.h>
#include <bps/bps.h>
#include <ids.h>
#include <ids_blackberry_id.h>

// Step 1 - Initialize IDS.

ids_result_t result = ids_initialize();
if( result != IDS_SUCCESS ) {
    displayText( "Failure to initialize. errno: %d", errno );
    return;
}

// Step 2 - Register to use BlackBerry ID as an identity provider.

static ids_provider_t* ids_provider;
static int ids_fd = -1;

result = ids_register_provider( BLACKBERRY_ID_PROVIDER,
                                &ids_provider, 
                                &ids_fd );

if( result != IDS_SUCCESS ) {
    displayText( "Failure to register. errno: %d", errno );
    return;
}

// Step 3 - Add an FD handler for the IDS library communications.

 if( bps_add_fd( ids_fd, BPS_IO_INPUT, &ids_io_handler,
                 NULL ) != BPS_SUCCESS ) {
    displayText( "Failure to monitor fd. errno: %d", errno );
    return;
 }

After these three steps are complete and return successfully, your app is ready to use the IDS APIs to access functionality for BlackBerry ID as an identity provider.

Here's a code sample for how to access a user's email address, stored in the "username" field.

const char* properties[] = { IDS_BBID_PROP_USERNAME };
// Other valid values include IDS_BBID_PROP_SCREENNAME, 
// IDS_BBID_PROP_FIRSTNAME, IDS_BBID_PROP_LASTNAME,
// and IDS_BBID_PROP_UID

result = ids_get_properties( ids_provider, BBID_PROPERTY_CORE, 1,
                             properties, handle_properties,
                             ids_call_failed, "get properties",
                             &request_id );
if( result != IDS_SUCCESS ) {
    displayText( "Failure to getProperty. errno: %d", errno );
    return;
}
Parent topic: Identity Service Library