BlackBerry Spark Communications Platform Guide

Identity Management

The BlackBerry Spark Communications Platform does not manage user identities or contact relationships for applications. The user accounts in Spark represent users in the BlackBerry Infrastructure only. Spark leverages OAuth and OpenID Connect so it can easily authenticate and associate your users with their Spark accounts.

Architecture Overview - Identity Management

How It Works

To sign in to the application, the user must authenticate with the identity provider. Next, the application must obtain an OAuth access token or an OpenID Connect ID token from the identity provider and pass it to the Spark SDK along with the user ID. The BlackBerry Infrastructure uses the token to authenticate the user with your identity provider. The Spark client and BlackBerry Infrastructure can then communicate using an internal token. The process repeats when the internal token expires.

The following diagram illustrates the authentication flow in greater detail.

Authentication Flow

Spark supports both OAuth access tokens and OpenID Connect JWT tokens to authenticate the user with your identity provider. The information required for Spark to perform the validation is provided when you register a domain for your application.

OAuth 2.0

For OAuth access tokens, the BlackBerry Infrastructure must first access the Token Info service to validate the client_id of the access token. The BlackBerry Infrastructure can then access the User Info service to validate the user ID.

Token Info Endpoint

The BlackBerry Infrastructure validates that the access tokens provided by the application are generated by the application's OAuth provider specifically for the application. This is done by invoking the OAuth provider's Token Info Web service endpoint to retrieve the client_id of the access token and matching it with the client_id configured for the application.

BlackBerry recommends following the RFC 7662 Oauth 2.0 Token Introspection when implementing the Token Info Web service. Additionally, the BlackBerry Infrastructure can integrate with a token services that accepts HTTP GET with an access token parameter and returns the client ID in a JSON response.

In addition to the service URL, the following configuration items on the Token Info service are used by the BlackBerry Infrastructure to invoke the service and process the response.

User Info Endpoint

The BlackBerry Infrastructure validates that the access token provided by the application belongs to the user. This is done by invoking the User Info Web service endpoint to retrieve the user ID of the access token and matching it with the user ID provided by the application.

BlackBerry recommends following the OpenID Connect Specification for UserInfo Endpoint when implementing the User Info Web service. The BlackBerry Infrastructure will use the HTTP GET method when issuing the UserInfo Request.

In addition to the service URL, the User ID field: must also be specified when you configure the User Info service. The User ID field: is the name of the field that contains the user ID in the JSON response. If the JSON response is composite, a field path in the format "<parent_field>.<child_field>.<user_id_field>" can be used.

The Spark example applications demonstrate how to connect to Spark servers using Google Sign-In.

OpenID Connect

Spark accepts both JWT based ID tokens and access tokens issued by an OpenID Connect identity provider. Access tokens are recommended if the application can be registered as an OAuth resource with explicit scopes the user can grant access to.

The BlackBerry Infrastructure validates the signature of the JWT tokens with the public key published by the identity provider. Furthermore, the usage of the token is validated by its audience, issuer and scopes.

To use JWT tokens, the following configuration is required when registering the domain for your application.

Example Identity Management Integrations

The Spark example applications include reference implementations of identity management via Google Sign-In and Azure Active Directory authentication.