User Identity

Identity Service library SDK - The Identity Service library offers a framework for data storage and retrieval, access to the user's personal information stored in the identity provider's account system, and user authentication/authorization to access the identity provider's apps and services.

Installation:

To use this API in your project, add the user identity plugin:

webworks plugin add com.blackberry.user.identity

Identity Service library

Developers can make use of the Identity Service (IDS) library APIs to enhance their app in several ways:
  • Data storage and retrieval
  • User authentication and authorization to access apps and off-device services offered by the identity provider (without prompting for credentials)
  • Access to the user's personal information stored in the identity provider's account system

These capabilities are described further in the sections below, and the specific implementation will vary for each identity provider. For example, the data storage and retrieval APIs might provide off-device data storage, or on-device data storage - that could differ between one identity provider and another. Similarly, the personal information that can be retrieved with the getProperties() API call will differ based on what information each identity provider stores in their account system.

As such, this document gives an overview of the Identity Service library APIs that are available, and this information must be used in conjunction with the identity provider's specific Identity Service API overview to confirm the specifics of their implementation of each of these APIs.

Data storage and retrieval APIs

apps can make use of APIs in the IDS library to store and retrieve data.

APIs are provided for:
  • initial storage of the data (createData())
  • retrieving the data (getData())
  • updating the data (setData())
  • deleting the data (deleteData())
  • listing the stored data (listData())

User authentication without prompting for credentials

Developers can use the Identity Services user authentication APIs in this library to avoid the need to implement username and password management for their app. With these APIs, once the user is signed in using their account with the identity provider on the device, the user is automatically signed in to the app as well.
  • Users won't need to create or remember a username and password for the app.
  • Users won't need to specifically log in to the app, thus improving the ease of use of the app.

User authorization to access apps and off-device services offered by the identity provider

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 the Identity Service 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 to the user's personal information associated with their account

The user's personal information that is available to the app will depend on what information is available from the identity provider's account system.

For example, if the app uses BlackBerry ID as the identity provider, the app can access the following personal information (provided that the user gives the app their consent):
  • First name
  • Last name
  • Screen name
  • username

For other identity providers, the personal information available will depend on what that provider stores in their identity account system.

About Callback functions

Many of the IDS APIs have the following parameters:
  • Success callback function
  • Failure callback function

When your app sends API calls using the IDS APIs, the identity provider service responds asynchronously. When an app receives a response, the corresponding callback function that your app had provided for the success or failure case is executed.

The identity provider service uses callback functions to pass the parsed response back to your app. Callback functions cannot be NULL. Your app must specify what to do in both the success and failure scenarios.

Registering your app to use the IDS APIs

To register your app so that it can use the IDS APIs, call registerProvider() from your app for at least one identity provider.

After your app sends a request, the identity provider service will process the request asynchronously, and call the corresponding success/failure callback function.

For example, your app can call getProperties() and pass a success callback of myAppSuccessCallback and a failure callback of myAppFailureCallback. When a response is ready from the identity provider, the success or failure callback will execute based on the results of the call.

getProperties()

Issue a request for a property.

Synopsis:

void blackberry.user.identity.getProperties(provider, type, propertyList, successCallback, failureCallback)

Parameters:

provider {String}

The identity provider to send this request to.

type {int}

The type of properties contained in the propertyList parameter. Each provider may have a unique set of types that it is able to handle. See the documentation for the provider for details on valid values.

propertyList {String}

A comma-separated string listing each of the properties requested.

successCallback {Function}

Function which is invoked upon successful operation of this method.

result {JSON}
A JSON object in the form below:
[
    {"uri":"urn:bbid:firstname","value":"john"},
    {"uri":"urn:bbid:lastname","value":"doe"}
]
failureCallback {Function}

Function which is invoked when this method fails. This callback contains an errorCode parameter to specify the failure condition.

result {JSON}
A JSON object containing details of the failure in the form below:
{
    "requestId" : 1,
    "result" : "50004",
    "failureInfo" : "The user could not be authenticated."
}
Error Handling:

Requests that do not complete successfully will result in the failure callback being called with one of the following result codes:

  • IDS_DEFAULT_ERROR: An internal error has occurred attempting to process the request.
  • IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to process the request.
  • IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token access is unavailable while locked.
  • IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be authenticated.
  • IDS_TOO_MANY_NAMES_PASSED: Too many properties were requested. See IDS_MAX_PROPERTY_COUNT.
  • IDS_NAME_TOO_LONG: The length of a property name in the list exceeds the maximum name length IDS_MAX_PROPERTY_NAME_LEN.
  • IDS_PROPERTY_NOT_AUTHORIZED: The application does not have access to one of the requested properties.
  • IDS_PROPERTY_DOES_NOT_EXIST: Property does not exist.
  • IDS_BAD_PROPERTY_NAME: Invalid property name.
  • IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter.
  • IDS_NON_EXISTING_PROPERTY: Property does not exist.
  • IDS_PROFILE_SERVER_ERROR: Server error.
  • IDS_PROPERTY_VALUE_TOO_LARGE: Property value is too large.
  • IDS_GET_FAIL: Get failed.

Example:

<script type="text/javascript">
    function getPropertiesSuccess(properties) {
        alert("Get properties returned the following user properties:" + 
            JSON.stringify(properties));        
    }

    function getPropertiesFailure(result) {
        alert("Failed to retrieve user properties: " + result.result + 
            " details: " + result.failureInfo);
    }

    blackberry.user.identity.registerProvider("ids:rim:bbid");
    blackberry.user.identity.getProperties("ids:rim:bbid", 0, 
        "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, 
        getPropertiesFailure);
</script>

getVersion()

The getVersion() function retrieves the version of the IDS library that your app is using.

Synopsis:

String blackberry.user.identity.getVersion()

Returns:

{String}

A string containing the version number.

Example:

<script type="text/javascript">
    alert("Identity Service version is:" + 
        blackberry.user.identity.getVersion());
</script>

registerProvider()

Apps use this function to register which identity provider(s) that they want to use. Once the app has initialized the library, it can register for each of the identity providers it is interested in.

Synopsis:

Object blackberry.user.identity.registerProvider(registerProvider)

Parameters:

registerProvider {String}

The name of the identity provider that the app wants to use for retrieving user identity information (only BlackBerry ID is supported currently).

Returns:

{Object}

A JSON object containing a result and possibly an error number.

Example:

<script type="text/javascript">
    var registerResult = 
        blackberry.user.identity.registerProvider("ids:rim:bbid");
    if( registerResult.failureInfo ) {
    	alert("IDS register provider error: " + registerResult.result + 
        " errno: " + registerResult.errno);
    }
</script>

setOption()

This function configures an option in the Identity Services Library.

Setting an option in the Identity Services Library

These options allow an app to modify the default behavior of the IDS library as well as configure the way the library and app integrate together.

Available options are:
  • Set GUI Allowed (option = 0, value = true/false)
    • Option to set the GUI allowed flag. When set to true (the default) and user input is required, the Identity Service performs the user interaction on behalf of the calling app. When set to false and user input is required, the API will return an error. If no user interaction is required to complete the API, this setting has no effect.
  • Set Group ID (option = 1, value = groupId)
    • Set the group ID of the calling app for UI dialogs. String version of UI group ID. This information is required in cases where the Identity Service requires user input from the user and must open an interface in the context of the calling app.
  • Set Verbosity (option = 2, value = {"Silent", "Normal", "Verbose")
    • Set the library logging verbosity level. Useful during app development to allow developers to be able to increase logging for diagnostics. Note that IDS logs are generated on stderr, and so should be captured in the app's log file.

Synopsis:

Object blackberry.user.identity.setOption(option, value)

Parameters:

option {Number}

The option to be modified.

value {String}

The new string value to set.

Returns:

{Object}
A JSON object containing the result and possibly an error number.

Example:

<script type="text/javascript">
    var setOptionResult = blackberry.user.identity.setOption(0, true);
    if( setOptionResult.failureInfo ) {
        alert("IDS set option error: " + setOptionResult.result + 
            " errno: " + setOptionResult.errno);
    }
</script>

setData()

Issue a request to set data.

Synopsis:

void blackberry.user.identity.setData(provider, type, flags, dataName, dataValue, successCallback,  failureCallback)

Parameters:

provider {String}

The identity provider to send this request to.

type {Number}

The type of data. Each provider may have a unique set of types that it is able to handle. See the documentation for the provider for details on valid values.

flags {Number}

Special flags for the operation. Each provider may have a unique set of flags that it supports. See the documentation for the provider for details on valid values and their behavior for this operation.

dataName {String}
The data identifier.
dataValue {String}
The content of the data.
successCallback {Function}

Function which is invoked upon successful operation of this method.

failureCallback {Function}

Function which is invoked when this method fails. This callback contains an errorCode parameter to specify the failure condition.

result {JSON}
A JSON object containing details of the failure in the form below:
{
    "requestId" : 1,
    "result" : "50004",
    "failureInfo" : "The user could not be authenticated."
}
Error Handling:

Requests that do not complete successfully will result in the failure callback being called with one of the following result codes:

  • IDS_DEFAULT_ERROR: An internal error has occurred attempting to process the request
  • IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to process the request.
  • IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token access is unavailable while locked.
  • IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be authenticated
  • IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter.
  • IDS_DOES_NOT_EXIST: Entry with the given name does not exist.
  • IDS_NOT_ALLOWED: App is not allowed to perform this operation.
  • IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to communicate with its service to perform operation.
  • USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length allowed by the provider

Example:

<script type="text/javascript">
    function setDataSuccess() {
        alert("Set property was successful");
    }

    function setDataFailure(result) {
        alert("Failed to set data: " + result.result + " details: " + 
           result.failureInfo);
    }

    blackberry.user.identity.registerProvider("ids:rim:profile");
    blackberry.user.identity.setData("ids:rim:profile", 1, 
        "usershandle", "johndoe123", setDataSuccess, setDataFailure);

</script>

registerNotifier()

Register a callback function to be called when the named entry changes.

Synopsis:

void blackberry.user.identity.registerNotifier(idsProvider, type, name, onChangeCallback)

Parameters:

idsProvider {String}

The identity provider to send this request to.

type {Number}

The type of data referred to by name.

name {String}

The name of the entry to receive notifications for.

onChangeCallback {Function}

The function that is invoked when a change is detected.

Example:

<script type="text/javascript">
    function onChangeCb(type, name, notification) {
        alert("Notification received: " + name + " with notification: " 
            + notification);
    }

    blackberry.user.identity.registerProvider("ids:rim:bbid");
    blackberry.user.identity.registerNotifier("ids:rim:bbid", 0, 
        "propertyName", onChangeCb);
</script>

deleteData()

Issue a request to delete data.

Synopsis:

void blackberry.user.identity.deleteData(idsProvider, type, flags, dataName, successCallback, failureCallback)

Parameters:

idsProvider {String}

The identity provider to send this request to.

type {Number}

The type of data. Each provider may have a unique set of types that it is able to handle. See the documentation for the provider for details on valid values.

flags {Number}

Special flags for the operation. Each provider may have a unique set of flags that it supports. See the documentation for the provider for details on valid values and their behavior for this operation.

dataName {String}
The property identifier.
successCallback {Function}

Function which is invoked upon successful operation of this method.

failureCallback {Function}

Function which is invoked when this method fails. This callback contains an errorCode parameter to specify the failure condition.

result {JSON}
A JSON object containing details of the failure in the form below:
{
    "requestId" : 1,
    "result" : "50004",
    "failureInfo" : "The user could not be authenticated."
}
Error Handling:

Requests that do not complete successfully will result in the failure callback being called with one of the following result codes:

  • IDS_DEFAULT_ERROR: An internal error has occurred attempting to process the request.
  • IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to process the request.
  • IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token access is unavailable while locked.
  • IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be authenticated.
  • IDS_NOT_ALLOWED: The app does not have access to delete the requested value.
  • IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter.
  • IDS_DOES_NOT_EXIST: Name specified does not exist.
  • IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to communicate with its service to perform operation.
  • USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length allowed by the provider

Example:

<script type="text/javascript">
    function deleteDataSuccess() {
        alert("Delete data was successful");
    }

    function deleteDataFailure(result) {
        alert("Failed to delete data: " + result.result + " details: " 
            + result.failureInfo);
    }

    blackberry.user.identity.registerProvider("ids:rim:profile");
    blackberry.user.identity.deleteData("ids:rim:profile", 1, 0, 
        "usershandle", deleteDataSuccess, deleteDataFailure);
</script>

createData()

Issue a request to create data.

Synopsis:

void blackberry.user.identity.createData(idsProvider, type, flags, dataName, dataValue, successCallback,  failureCallback)

Parameters:

idsProvider {String}

The identity provider to send this request to.

type {Number}

The type of data. Each provider may have a unique set of types that it is able to handle. See the documentation for the provider for details on valid values.

flags {Number}

Special flags for the operation. Each provider may have a unique set of flags that it supports. See the documentation for the provider for details on valid values and their behavior for this operation.

dataName {String}
The property identifier.
dataValue {String}
The content of the property.
successCallback {Function}

Function which is invoked upon successful operation of this method.

failureCallback {Function}

Function which is invoked when this method fails. This callback contains an errorCode parameter to specify the failure condition.

result {JSON}
A JSON object containing details of the failure in the form below:
{
    "requestId" : 1,
    "result" : "50004",
    "failureInfo" : "The user could not be authenticated."
}
Error Handling:

Requests that do not complete successfully will result in the failure callback being called with one of the following result codes:

  • IDS_DEFAULT_ERROR: An internal error has occurred attempting to process the request.
  • IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to process the request.
  • IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token access is unavailable while locked.
  • IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be authenticated.
  • IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter.
  • IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to communicate with its service to perform operation.
  • IDS_ALREADY_EXISTS: Entry with name already exists.
  • IDS_NOT_ALLOWED: App is not allowed to perform this operation.
  • USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length allowed by the provider

Example:

<script type="text/javascript">
    function createDataSuccess() {
        alert("Create Data was successful");
    }

    function createDataFailure(result) {
        alert("Failed to create data: " + result.result + " details: " 
            + result.failureInfo);
    }

    blackberry.user.identity.registerProvider("ids:rim:profile");
    blackberry.user.identity.createData("ids:rim:profile", 1, 0, 
        "usershandle", "johndoe123", createDataSuccess, createDataFailure);
</script>

challenge()

Issue a request to challenge for identity.

Synopsis:

void blackberry.user.identity.challenge(idsProvider, type, flags, dataName, successCallback, failureCallback)

Parameters:

idsProvider {String}

The identity provider to send this request to.

type {Number}

The type of data. Each provider may have a unique set of types that it is able to handle. See the documentation for the provider for details on valid values.

flags {Number}

Special flags for the operation. Each provider may have a unique set of flags that it supports. See the documentation for the provider for details on valid values and their behavior for this operation.

successCallback {Function}

Function which is invoked upon successful operation of this method.

failureCallback {Function}

Function which is invoked when this method fails. This callback contains an errorCode parameter to specify the failure condition.

result {JSON}
A JSON object containing details of the failure in the form below:
{
    "requestId" : 1,
    "result" : "50004",
    "failureInfo" : "The user could not be authenticated."
}
Error Handling:

Requests that do not complete successfully will result in the failure callback being called with one of the following result codes:

  • IDS_DEFAULT_ERROR: An internal error has occurred attempting to process the request.
  • IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to process the request.
  • IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, access is unavailable while locked.
  • IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be authenticated.

Example:

<script type="text/javascript">
    function challengeSuccess(level) {
        alert("Challenge was successful: " + level);
    }

    function challengeFailure(result) {
        alert("Challenge failed: " + result.result + " details: " 
            + result.failureInfo);
    }

    blackberry.user.identity.registerProvider("ids:rim:bbid");
    blackberry.user.identity.challenge("ids:rim:bbid", 0, 0, 
        challengeSuccess, challengeFailure);
</script>

Last modified: 2014-05-23



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus