BlackBerry Spark Communications Services Guide

Azure Active Directory as your Identity Provider

BlackBerry Spark Communications Services can authenticate a user with Azure Active Directory. If your users already sign in to your application using Azure Active Directory, you can easily configure the SDK to use it as your application's identity provider.

Authenticating

Azure Active Directory supports JSON Web Tokens (JWT). Your application needs to pass the JWT access token along with the user ID to the SDK so that the user is authenticated against your Azure Active Directory. Your application can parse the JWT access token returned from the Azure authentication service to get the Active Directory user ID and other information.

In Microsoft Azure, each access token must be used for a specific resource. The scope parameter sent in the authentication request can contain multiple permissions, but all the permissions must be for the same resource.

Configuring Azure

First, register a Web API with a Scope defining the permission to use Spark Communications Services. This allows the BlackBerry Infrastructure to validate the access token that your application receives from the Azure Active Directory authentication service.

Add your Application

From the Azure Application Registration Portal, add a new application.

After you've created your application in Azure, make note of the Application Id. It will be needed for the other steps.

Find Azure Application ID

Add the Web API Platform

Add the Web API platform to your application's Azure configuration.

First, click Add Platform button.

Add the Web API Platform in Azure: Step 1

Select Web API.

Add the Web API Platform in Azure: Step 2

Configure the Web API

After adding the Web API platform to your application, a new section will be displayed in your application's Azure configuration page.

Azure Web API Platform Configuration

Leave the default Application ID URI, which should have been automatically filled in with api:// followed by your Application ID.

Add a Scope

Click the Add Scope button to add an authorization scope that will be used by the BlackBerry Infrastructure to verify the Azure access tokens that your application passes to it. A Create Scope window will appear.

Add a Scope

Set the scope name in the first field to Messaging.All. Provide the required description strings and click Ok.

Authorize your Application

In the Pre-authorized applications section of the Web API configuration, add the Application ID for your application and then select the new Scope that you added.

Pre-authorize your Azure Application

Configure your Target Platform

The next step depends on whether you are developing for a mobile operating system or the web.

First, click Add Platform button.

Add the Native Platform in Azure: Step 1

Select Native Application.

Add the Native Platform in Azure: Step 2

After adding the Web platform to your application, a new section will be displayed in your application's Azure configuration.

Native Platform

Add a new custom redirect URI and set its value to the concatenation of msal, your Application ID, and ://auth. Your application will need to process a callback from this URI to receive the authentication result.

First, click Add Platform button.

Add the Web Platform in Azure: Step 1

Select Web.

Add the Web Platform in Azure: Step 2

After adding the Web platform to your application, a new section will be displayed in your application's Azure configuration page.

Configure the Web Platform in Azure

Ensure that the Allow Implicit Flow check box is checked.

Enter the path to the redirect page that your application will send as the redirect_uri parameter to the Azure authorization server.

Configure your Domain

On your BlackBerry Online Account page, select your application to manage its configuration and then open the Communications Services tab and select Microsoft Azure AD in the Getting Started box.

Azure Portal

In the OpenID Connect tab below, some of the fields will be automatically filled in for you. Fill in the remaining fields as follows.

Azure Fields

Set the Issuer field to the concatenation of https://login.microsoftonline.com/, your Azure Active Directory Directory ID, and /v2.0. You can find your Directory ID by visiting the Azure Portal, selecting Azure Active Directory, and then visiting the Properties page.

Find Azure Directory ID

In the Client IDs field, add your application's Azure Application ID. You can find your Application ID by visiting the Azure Application Registration Portal.

Find Azure Application ID

Click the Create Domain button. Click the Edit button to modify the domain and choose the OpenID Connect tab.

In the Scopes list, add Messaging.All, which is the same scope name that you added to your application's Azure Web API configuration in the steps above.

Azure Scopes

Examples

The SDK example applications can be set up to use Azure Active Directory as your identity provider.