IdentityServiceProvider

Since: to get more info on failures.

#include <bb/platform/identity/IdentityServiceProvider>

To link against this class, add the following line to your .pro file: LIBS += -lbbplatform

Use these APIs to provide seamless user authentication/authorization with off-device services.

Use the Identity Service provider class to incorporate user authentication and authorization, using one or more external identity providers, in your application.

Identity Service provider class

You can use the APIs in the Identity Service provider class to enable your users to access off-device services and content that require user authentication or authorization. Content and services include data storage and retrieval, and access to services with an external identity provider. You can also personalize the user experience by integrating users' personal information in your application.

An application needs separate instances of the IdentityServiceProvider class for each identity provider that it uses. Using the same instance of IdentityServiceProvider for different providers could lead to undefined behavior.

Your users can sign in with their identity provider, using their BlackBerry device, and access content or services that they have with that identity provider from within your application and elsewhere on their device.

Any authorization that your application requires can also be done using the login credentials associated with an identity provider. This approach frees your users from having to remember another login profile, and saves you from having to build user authentication into your application.

For example, if you registered your application with BlackBerry ID as your identity provider, your users could access BlackBerry ID controlled resources from within your application, without having to log in again. BlackBerry ID is one of the supported identity providers, and the list of identity providers is growing.

Identity providers can offer different features and levels of access. It's important to understand the features that are available from your identity provider because those features impact how you design your application. For example, one identity provider might provide off-device data storage while another might provide on-device data storage. Similarly, the personal information that you can retrieve with the requestProperties() function differ based on the information that each identity provider stores in their account system.

You will need to use this documentation in conjunction with the information from your identity provider about how they have implemented the Identity Service provider APIs on thier end. If you are using BlackBerry ID as the Identity Service provider for your application, you can find information specific to integrating with BlackBerry ID in the IdentityBlackBerryId header files.

Data storage and retrieval APIs
You can use the APIs in the Identity Service provider class to:
User authentication without prompting for credentials

With the user authentication APIs in this class, you can avoid implementing username and password management in your application. After your user signs in with the identity provider on their device, that user is automatically signed in to your application as well. This eliminates the need for users to create and remember a username and password for your application, and it also reduces the number of times that users need to log in, providing a more fluid user experience.

User authorization for access to off-device services

If your application interacts with one of your identity provider's applications or off-device services, and that application or service requires user authentication, you can use the Identity Service provider class to perform that authentication. User authentication/authorization is done using tokens, and does not require user input. This allows your application and the off-device service to interact seemlessly.

Using personal information in your application

Users must first allow your application to access their information. If allowed access, you can integrate the personal information associated with your users' accounts in your application. The personal information that is available to your application depends on what information is available from your identity provider's account system.

For example, if your application uses BlackBerry ID as an identity provider, your application can access the following pieces of a user's personal information:
  • first name

  • last name

  • screen name

  • username

Check with other identity providers to identify the personal information they make available.

Registering your application to use the IdentityServiceProvider

class.

To register your application so that it can use the IdentityServiceProvider class, either pass the name of the provider into the constructor, or call setProvider for an instance of a class. A separate instance of IdentityServiceProvider should be created for each provider that an application relies on.


Overview

Properties Index

intmaxDataNameLength [read-only]
intmaxPropertyCount [read-only]
intmaxPropertyNameLength [read-only]

Public Functions Index

IdentityServiceProvider (QObject *parent=0)
IdentityServiceProvider (const QString &providerName, QObject *parent=0)
virtual ~IdentityServiceProvider ()
Q_INVOKABLE intchallenge (int type, int flags) const
Q_INVOKABLE intclearToken (const QString &tokenType, const QString &appliesTo)
PRIVATE intcreateData (int type, int flags, const QString &name, const QByteArray &value)
PRIVATE Q_INVOKABLE intdeleteData (int type, int flags, const QString &name)
Q_INVOKABLE bb::platform::identity::IdentityServiceResult::Typeerror () const
Q_INVOKABLE boolisValid () const
Q_INVOKABLE intlistData (int type, int flags) const
intmaxDataNameLength () const
intmaxPropertyCount () const
intmaxPropertyNameLength () const
Q_INVOKABLE intrequestData (int type, int flags, const QString &name) const
Q_INVOKABLE intrequestProperties (int type, const QStringList &propertyList) const
Q_INVOKABLE intrequestToken (const QString &tokenType, const QString &appliesTo) const
intsetData (int type, int flags, const QString &name, const QByteArray &value)
Q_INVOKABLE intsetNotification (int type, int flags, const QString &name)
Q_INVOKABLE bb::platform::identity::IdentityServiceResult::TypesetProvider (const QString &providerName)

Signals Index

PRIVATE voidchallengeComplete (int requestId, int level)
voidchallengeFailed (int requestId, bb::platform::identity::IdentityServicePropertyResult::Type result, const QString &info)
PRIVATE voiddataCreated (int requestId)
voiddataCreateFailed (int requestId, bb::platform::identity::IdentityServicePropertyResult::Type result, const QString &info)
PRIVATE voiddataDeleted (int requestId)
voiddataDeleteFailed (int requestId, bb::platform::identity::IdentityServicePropertyResult::Type result, const QString &info)
voiddataListFailed (int requestId, bb::platform::identity::IdentityServicePropertyResult::Type result, const QString &info)
PRIVATE voiddataListRetrieved (int requestId, const QStringList &dataList)
PRIVATE voiddataRetrievalFailed (int requestId, bb::platform::identity::IdentityServicePropertyResult::Type result, const QString &info)
PRIVATE voiddataRetrieved (int requestId, const QByteArray &data)
PRIVATE voiddataSet (int requestId)
voiddataSetFailed (int requestId, bb::platform::identity::IdentityServicePropertyResult::Type result, const QString &info)
PRIVATE voidnotificationReceived (int type, const QString &notificationName, int notification)
PRIVATE voidpropertiesRetrieved (int requestId, const QMap< QString, QString > &userProperties)
PRIVATE voidpropertyRetrievalFailed (int requestId, bb::platform::identity::IdentityServicePropertyResult::Type result, const QString &info)
PRIVATE voidtokenCleared (int requestId)
voidtokenClearFailed (int requestId, bb::platform::identity::IdentityServiceTokenResult::Type result, const QString &info)
PRIVATE voidtokenRetrievalFailed (int requestId, bb::platform::identity::IdentityServiceTokenResult::Type result, const QString &info)
voidtokenRetrieved (int requestId, const QByteArray &token, const QMap< QString, QString > &parameters)

Properties

int maxDataNameLength[read-only]

The maximum string length of a single data name that can be passed in requestData(), setData(), createData() and deleteData() calls, excluding the terminating NULL.

int maxPropertyCount[read-only]

The maximum number of properties that can be included in a single requestProperties() call.

int maxPropertyNameLength[read-only]

The maximum string length of a single property name that can be passed in a single requestProperties() call, excluding the terminating NULL.

Public Functions

IdentityServiceProvider (

Constructs an empty IdentityServiceProvider instance.

Parameters
parent

The parent object. Setting parent to 0 constructs an IdentityServiceProvider instance with no parent.

IdentityServiceProvider (

Constructs an IdentityServiceProvider instance and registers the provider that was supplied.

Parameters
providerName

the name of the identityProvider

parent

The parent object. Setting parent to 0 constructs an IdentityServiceProvider instance with no parent.

virtual~IdentityServiceProvider ()

Destructor.

Q_INVOKABLE int challenge (
  • inttype,
  • intflags )

Issue a request to challenge for identity.

Parameters
type

The type of challenge requested. Each identity provider may have a unique set of types that it supports. See the identity provider's documentation for details on valid types and their behavior.

flags

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 behaviour.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See challengeFailed and IdentityServicePropertyResult.

Q_INVOKABLE int clearToken (

Issue a clear token request.

In cases where the token seems to be invalid or too close to expiry to be deemed useful, an application can clear the currently cached token in order to retrieve a newly generated token in the next requestToken() call. Upon completion of a successful clearToken call, the tokenCleared signal is emitted.

Parameters
tokenType

The token type which must be between 1 and 32 characters, inclusive.

appliesTo

The name of the application or service that the token applies to. It must be between 1 and 96 characters, inclusive.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See tokenClearFailed and IdentityServiceTokenResult.

PRIVATE int createData (

Issue a request to create data.

Upon completion of a successful createData call, the dataCreated signal is emitted.

Parameters
type

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

flags

Flags related to the request. Each provider may define specific flags.

name

The name of the data to store.

value

The content of the data to store.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See dataCreateFailed and IdentityServicePropertyResult.

PRIVATE Q_INVOKABLE int deleteData (
  • inttype,
  • intflags,
  • const QString &name )

Issue a request to delete data.

Upon completion of a successful deleteData call, the dataDeleted signal is emitted.

Parameters
type

The type of data 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.

name

The name of the data to delete

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See dataDeleteFailed and IdentityServicePropertyResult.

Q_INVOKABLE bb::platform::identity::IdentityServiceResult::Type error ()

Contains the last immediate error from request.

Return:

The result of the last failed API call.

Q_INVOKABLE bool isValid ()

Used to determine if the IdentityServiceProvider class is valid.

Return:

true if the IdentityServiceProvider has a valid provider; otherwise returns false.

Q_INVOKABLE int listData (
  • inttype,
  • intflags )

Issue a request for the list of stored data.

Upon completion of a successful listData call, the dataListRetrieved signal is emitted.

Parameters
type

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

flags

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.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See dataListFailed and IdentityServicePropertyResult.

int maxDataNameLength ()

The maximum string length of a single data name that can be passed in requestData(), setData(), createData() and deleteData() calls, excluding the terminating NULL.

Return:

The maximum string length.

int maxPropertyCount ()

The maximum number of properties that can be included in a single requestProperties() call.

Return:

The maximum number of properties.

int maxPropertyNameLength ()

The maximum string length of a single property name that can be passed in a single requestProperties() call, excluding the terminating NULL.

Return:

The maximum string length.

Q_INVOKABLE int requestData (
  • inttype,
  • intflags,
  • const QString &name )

Issue a request for data.

Upon completion of a successful requestData call, the dataRetrieved signal is emitted and contains the requested data.

Parameters
type

The storage type of the data entry. Each identity provider may have a unique set of types that it supports. See your identity provider's documentation for details on valid types.

flags

Flags related to the request. Each provider may define specific flags.

name

The name of the data to store.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See dataRetrievalFailed and IdentityServicePropertyResult.

Q_INVOKABLE int requestProperties (

Issue a request for user properties.

Upon completion of a successful getProperties call, the propertiesRetrieved signal is emitted and contains a QList of IdsProperties.

Parameters
type

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

A list of the requested properties, by property name.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See propertyRetrievalFailed and IdentityServicePropertyResult.

Q_INVOKABLE int requestToken (

Issue a request token call.

Upon completion of a successful requestToken call, the tokenRetrieved signal is emitted and contains an IdentityServiceToken.

Parameters
tokenType

The token type, which must be between 1 and 32 characters, inclusive.

appliesTo

The name of the application or service that the token applies to. It must be between 1 and 96 characters, inclusive.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures. Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See tokenRetrievalFailed and IdentityServiceTokenResult.

int setData (

Issue a request to set data.

Upon completion of a successful setData call, the dataSet signal is emitted.

Parameters
type

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

flags

Flags related to the request. Each provider may define specific flags.

name

The name of the data to store.

value

The content of the data to store.

Return:

A request Id, which will be 0 if the call fails immediately. Call error() to get more info on failures.

Immediate errors - See error() and IdentityServiceResult.

Asynchronous Error Handling - See dataSetFailed and IdentityServicePropertyResult.

Q_INVOKABLE int setNotification (
  • inttype,
  • intflags,
  • const QString &name )

Register to be notified when the named entry changes.

Parameters
type

The type of data referred to by name.

flags

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 behaviour.

name

The name of the entry to receive notifications for.

Return:

IdentityServiceResult. Success if successful. See IdentityServiceResult for details regarding errors.

Immediate errors - See error() and IdentityServiceResult.

Q_INVOKABLE bb::platform::identity::IdentityServiceResult::Type setProvider (

Sets the identity provider for an IdentityServiceProvider instance and registers the provider that was supplied.

Changing a provider once one has been set will result in undefined behavior and is discouraged unless registration fails. Typically, the provider should not change during the life of this object (i.e. it is usually set in the constructor in C++, or in the initialization in QML). In particular, changing the provider when requests are in progress may result in undefined behavior.
Parameters
providerName

The name of the identity provider.

Return:

IdentityServiceResult. Success if successful. See IdentityServiceResult for details regarding errors.

Signals

PRIVATE void challengeComplete (
  • intrequestId,
  • intlevel )

Emitted upon successful completion of a challenge call.

Parameters
requestId

The request id of the originating challenge call.

level

Indicates the level of assurance of the successful challenge completed. See the specific identity provider's documentation for additional information on the values that can be returned.

void challengeFailed (

Emitted upon failure of a challenge call.

Parameters
requestId

The request id of the originating challenge call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

PRIVATE void dataCreated (
  • intrequestId)

Emitted upon successful completion of a createData call.

Parameters
requestId

The request id of the originating createProperty call.

void dataCreateFailed (

Emitted upon failure of a createProperty call.

Parameters
requestId

The request id of the originating createProperty call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

PRIVATE void dataDeleted (
  • intrequestId)

Emitted upon successful completion of a deleteProperty call.

Parameters
requestId

The request id of the originating deleteProperty call.

void dataDeleteFailed (

Emitted upon failure of a deleteProperty call.

Parameters
requestId

The request id of the originating deleteProperty call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

void dataListFailed (

Emitted upon failure of a listData call.

Parameters
requestId

The request id of the originating listData call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

PRIVATE void dataListRetrieved (

Emitted upon successful completion of a listData call.

Parameters
requestId

The request id of the originating listData call.

dataList

The requested data.

PRIVATE void dataRetrievalFailed (

Emitted upon failure of a requestData call.

Parameters
requestId

The request id of the originating getProperties call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

PRIVATE void dataRetrieved (

Emitted upon successful completion of a requestData call.

Parameters
requestId

The request id of the originating getProperties call.

data

The requested data.

PRIVATE void dataSet (
  • intrequestId)

Emitted upon successful completion of a setProperty call.

Parameters
requestId

The request id of the originating setProperty call.

void dataSetFailed (

Emitted upon failure of a setProperty call.

Parameters
requestId

The request id of the originating setProperty call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

PRIVATE void notificationReceived (
  • inttype,
  • const QString &notificationName,
  • intnotification )

Emitted when a registered notification is received.

Parameters
type

The type of entry. Same as value used when registering the notifier.

notificationName

The name of the entry, which is the same as the value that was used when registering the notifier.

notification

Indicates the kind of change that occurred. See provider's documentation for the values it will return.

PRIVATE void propertiesRetrieved (

Emitted upon successful completion of a getProperties call.

Parameters
requestId

The request id of the originating getProperties call.

userProperties

A list containing the requested properties.

PRIVATE void propertyRetrievalFailed (

Emitted upon failure of a getProperties call.

Parameters
requestId

The request id of the originating getProperties call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

PRIVATE void tokenCleared (
  • intrequestId)

Emitted upon successful completion of a clearToken call.

Parameters
requestId

The request id of the originating clearToken call.

void tokenClearFailed (

Emitted upon failure of a clearToken call.

Parameters
requestId

The request id of the originating clearToken call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

PRIVATE void tokenRetrievalFailed (

Emitted upon failure of a requestToken call.

Parameters
requestId

The request id of the originating requestToken call.

result

Information regarding the failure.

info

Optional information with additional information regarding the request failure.

void tokenRetrieved (

Emitted upon successful completion of a requestToken call.

Parameters
requestId

The request id of the originating requestToken call.

token

The requested token.

parameters

The list of additional token parameters.

Last modified: 2014-09-30



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

comments powered by Disqus