User Identity

The User Identity object contains information regarding the user's identity and accounts on a BlackBerry smartphone.

Identity Service SDK Overview - interfaces for using Identity Services from 3rd Party applications

What functionality does this Identity Service SDK provide to apps?

This SDK provides a series of functions that enable an application to choose an identity provider(s) for their application, and to request authentication tokens from that provider, as well as information about the user.

At present, the only Identity Provider available is BlackBerry ID. As more identity providers become available, this SDK will provide access to those providers.

Why integrate with Identity Service?

If your app needs to interact with an off-device service that requires user authentication, you can integrate with Identity Service to provide seamless access to the off-device service. The interaction from the app to the off-device service is 'seamless' because the user is not prompted within the app for the username and password required by the off-device service. Instead, BlackBerry ID can pass back a 'token' that authenticates the user's identity, and that token can be read and understood by the off-service device, thus allowing the user access to that off-device content WITHOUT requiring user interaction for authentication.

Fictitious Example: Imagine an app called 'MyPics' that has a user's photo content stored off-device, and the content is accessible from the web and from BlackBerry devices. If 'MyPics' is integrated with BlackBerry ID (i.e. we've created a token specifically for them), the app can request a token from BlackBerry ID to confirm the user's identity. The app can send that token to the off-device content service for 'MyPics', as a way of 'signing in' that user to their MyPics account WITHOUT requiring the user to enter a username and password within the 'MyPics' app. The result is a seamless user experience for the app; the user will get their photos on the device without having to sign in to the 'MyPics' service. Since they are already signed in to their device with their BlackBerry ID, and since the app is integrated with BlackBerry ID to use tokens, it all happens without any user annoyance of being prompted to 'sign in' to MyPics.

Even if your app doesn't need to communicate with off-device services using tokens, there are other useful APIs in this SDK that provide access the user's account information (first name, last name, screen name, or username).

The next section provides a more detailed technical overview of the APIs that provide this functionality.

Identity Service SDK functionality - API overview

This Identity Service WebWorks SDK provides an interface for applications to make use of BlackBerry ID functionality from within their app.

The APIs provided in this SDK enable apps to do the following: - retrieve the account information of the user who is signed in with their BlackBerry ID on the BB10 device. The API getProperties() can be used to retrieve the user's first name, last name, username, and screenname.

- retrieve tokens that prove the user's identity for off-device services (known as 'relying parties', because they are relying on BlackBerry ID to confirm the user's identity), so that the user can have seamless access to that off-device service without being required to enter their username and password. These tokens are used by the off-device service (relying party) to confirm the identity of the user. NOTE: The APIs getToken() and clearToken() can only be used if the relying party has gone through integration process with RIM to have tokens defined for that relying party.

- for background services where it doesn't make sense to show any screens to the user (i.e. background services that do not have any UI), suppress the ability for the Identity Service to pop up an authentication/password confirmation dialog box. The API setOption() is provided to ensure that the Identity Service does not present a pop up screen for authentication/password verification within background services where that wouldn't make sense.

Important: There is never a need for an application to present a "sign in" screen to the user. All the IDS APIs listed above will check to see if their is a BlackBerry ID associated with the device, and if there isn't one, they will pop an authentication (sign in) screen on the device (unless the calling app runs in the background and has 'set_GUI_allowed = False' to specifically prevent this from happening.)

About Callback functions

Several IDS APIs have the following 2 parameters: - Success callback function - Failure callback function

The Identity Service responds asynchronously to API calls made by an application. Upon detection of a response, the IDS library will parse the response (which will either be success or failure), and invoke the corresponding callback function that the app has provided for the success or failure case.

So the callback functions are a mechanism for IDS library to pass the parsed response from the daemon back to the calling application. The callback functions cannot be NULL; the app must specify what to do in both the success and failure scenarios.

Integrating an application with IDS APIs

The calling app uses the function registerProvider() which will connect the app to an Identity Service. This step must be done before the app calls any of the IDS APIs described above (getToken(), clearToken(), etc). After the app makes an API call to one of the IDS APIs listed above (i.e. getToken), the IDS library will asynchronously process that request, and call the success/failure callback provided.

{
"result": true
}

{
"result":"50009",
"errorDescription":"The appliesTo value is not valid"
}

<script type="text/javascript">
	function clearTokenSuccess(clearTokenResult) {
		alert("Token cleared: " + clearTokenResult.cleared);
	}
			
	function clearTokenFailure(result) {
		alert("Failed to clear token - result is: " + result.result + " with description: " + result.errorDescription);
	}

	blackberry.user.identity.registerProvider("ids:rim:bbid");
	blackberry.user.identity.clearToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", clearTokenSuccess, clearTokenFailure);
</script>

{[
		{"uri":"urn:bbid:firstname":"value":"john"},
		{"uri":"urn:bbid:lastname":"value":"doe"}
}

{
"result":"50004",
"errorDescription":"The user could not be authenticated."
}

<script type="text/javascript">
	function getPropertiesSuccess(properties) {
		alert("Get properties returned the following user properties:");
		for( prop in properties ) {
			alert("Property: " + properties[prop].uri + " value: " + properties[prop].value);
		}
	}

	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", "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, getPropertiesFailure);
</script>

{
"token": "ghdaj23i8rghaepeghk;a",
"params": ["name":"TOKEN_SECRET","value":"oguireqhge"]
}

{
"result":"50009",
"errorDescription":"The appliesTo value is not valid"
}

<script type="text/javascript">
	function getTokenSuccess(tokenResult) {
		alert("Received token: " + tokenResult.token);
		for( param in tokenResult.tokenParams ) {
			alert("Token param: " + tokenResult.tokenParams[param].name + " and value: " + tokenResult.tokenParams[param].value);
		}
	}
			
	function getTokenFailure(result) {
		alert("Failed to retrieve token - result is: " + result.result + " with description: " + result.errorDescription);
	}

	blackberry.user.identity.registerProvider("ids:rim:bbid");
	blackberry.user.identity.getToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", getTokenSuccess, getTokenFailure);
</script>

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

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

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