BlackBerry Spark Communications Services Guide

Identity Providers

BlackBerry Spark Communications Services does not manage user accounts or contact relationships for applications. The identities within Spark Communications Services represent users in the BlackBerry Infrastructure only. You bring your own identity provider, such as Google Sign-In, Azure Active Directory, or another OAuth 2.0 or OpenID Connect identity provider so that your application can easily authenticate and associate your users with the BlackBerry Infrastructure.

How Identity Providers Fit In

How It Works

When the Spark Communications Services SDK connects to the BlackBerry Infrastructure, it must provide an access token that is used to identify, authenticate, and authorize your application. Your application is responsible for providing this access tokens to the SDK. This token represents one of your users or an automated service. Your application gets an access token from an identity provider that supports either OAuth 2.0 or OpenID Connect.

Typically, your user first authenticates with your chosen identity provider inside your application. Next, your application obtains an OAuth 2.0 or OpenID Connect access token from your identity provider and provides it and the user's ID to the SDK. The BlackBerry Infrastructure validates the identity provider's token to authenticate your user with your identity provider and authorize your application to access the service on behalf of their identity. The SDK is then granted an internal token that it uses to communicate with the BlackBerry Infrastructure. When the internal token expires, your application obtains a new access token from your identity provider and the process repeats.

The following diagram illustrates the authentication flow in greater detail.

Authentication Flow

Specifying your Identity Provider

Spark Communications Services supports three forms of authentication. You provide the information required for the BlackBerry Infrastructure to perform access token validation when you configure your application's domain.

Identity Provider Description
OAuth 2.0

Spark Communications Services supports identity providers that use OAuth 2.0 Opaque Tokens.

You can configure OAuth 2.0 by following the steps below.

OpenID Connect

Spark Communications Services supports identity providers that use OpenID Connect using JSON Web Tokens (JWT).

You can configure OpenID Connect by following the steps below.

No User Authentication

Spark Communications Services supports sandbox domains that have user authentication disabled. When connecting to such a domain, you do not need to configure a real identity provider and your application does not have to communicate with one. Production domains cannot have user authentication disabled.

You can disable user authentication by following the steps on the Download & Configure page.

Using No Authentication

You can configure your sandbox domain to have user authentication disabled by following the steps on the Download & Configure page. Your application must still provide user IDs and tokens to SDK APIs, but instead of getting them from a real identity provider, your application makes up its own user IDs and generates its own unsigned JWT tokens.

In a domain with user authentication disabled, you can use any mechanism that you like for generating and keeping track of user ID values. For working with and exploring the example applications you could use users' email addresses to identify them, or even their first names, or strings like user1. A real identity provider usually assigns opaque random-looking user ID values that it looked up based on your user's email addresses and passwords, but when developing or testing in a domain without user authentication, you use whatever IDs are convenient.

Unsigned JWT Token Fields

When user authentication is disabled, you must provide the SDK with unsigned JWT tokens.

The unsigned JWT tokens expected by the SDK must have the following fields.

Header Fields

Field Type Description
alg string The token's header algorithm must be set to none.

Payload Fields

Field Type Description
sub string This field must contain the user ID and must match the value that your application provides to the SDK along side this access token.
jti string This field contains a token ID and can be randomly generated. BlackBerry recommends a length of at least 18 characters from an alphabet at least as large as the Base64 alphabet.
iat number The token's timestamp should be the time at which is was generated, expressed as a number of seconds since 1970 UTC.
exp number The token's expiry time should be the time at which it is no longer valid, expressed as a number of seconds since 1970 UTC. Any reasonably long expiry duration will do, such as 24 hours. Use a shorter duration if you want to exercise your application's access token refresh mechanism.

Using OAuth 2.0

Your application can use an OAuth 2.0 identity provider by configuring your domain appropriately on your application's BlackBerry Online Account page.

Make sure that the Enable User Authentication toggle switch is on.

Enable User Authentication

Select the OAuth 2.0 tab and fill in the form as explained in the following sections.

OAuth 2.0 Form

Token Info Endpoint

The BlackBerry Infrastructure validates that the access tokens provided by your application were generated by your application's OAuth 2.0 provider specifically for your application. It does this by invoking the OAuth 2.0 provider's Token Info service endpoint to retrieve the client_id of the access token and matching it with the client_id configured for the application.

The following values must be configured in the Token Info section of the OAuth 2.0 configuration form.

Field Description
URL The URL of the Token Info service. The BlackBerry Infrastructure will contact this URL using the other configured values.
HTTP Method The HTTP method used to contact the Token Info service. This must be GET or POST. If you select the GET method, then the access token is passed as an URL parameter named access_token. If you select the POST method, then the access token is passed as an HTTP body parameter named token.
HTTP Authentication The user name and password that the BlackBerry Infrastructure must include in the request using HTTP Basic Authentication, if required
JSON Field Name: User ID The name of the JSON field that contains the user ID in the JSON response. If the JSON response is composite, a field path in the format parentField.childField.userIdField can be used.
JSON Field Name: App Client ID The name of the JSON field that contains the client_id in the JSON response. If the JSON response is composite, a field path in the format parentField.childField.appUserIdField can be used.

User Info Endpoint

The BlackBerry Infrastructure validates that the access token provided by your application belongs to the user by contacting the User Info service endpoint to retrieve the user ID of the access token and matching it with the user ID provided by your application.

The following values must be configured in the User Info Endpoint Info section of the OAuth 2.0 configuration form.

Field Description
URL The URL of the User Info service. The BlackBerry Infrastructure will contact this URL using the other configured values.
User ID Field Name The name of the JSON field that contains the user ID in the JSON response. If the JSON response is composite, a field path in the format parentField.childField.userIdField can be used.

Authorized Clients

The following values must be configured in the Authorized Clients section of the OAuth 2.0 configuration form.

Field Description
OAuth Client IDs You must list the client_id values of each application that should be granted access to this domain.

Using OpenID Connect

Spark Communications Services accepts both JWT-based ID tokens and access tokens issued by an OpenID Connect identity provider. BlackBerry recommends using access tokens if the application can be registered as an OAuth 2.0 resource with explicit scopes that 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. Token usage is further validated by its audience, issuer, and scopes.

Your application can use an OpenID Connect identity provider by configuring your domain appropriately on your application's BlackBerry Online Account page.

Make sure that the Enable User Authentication toggle switch is on.

Enable User Authentication

Select the OpenID Connect tab and fill in the form as explained below.

OpenID Connect Form

The following values must be configured in the OpenID Connect configuration form.

Field Description
JWKS URI The URI of the JWT token signature public keys from the identity provider.
Issuer This must be set to an Issuer value that the BlackBerry Infrastructure should accept. Tokens given to the SDK must have this value in their JWT Issuer field.
JWT Field Name: User ID The name of the JWT field that carries the user ID. For example, sub. The claim value is used by the BlackBerry Infrastructure as the user ID and it needs to match the user ID provided by the application.
JWT Field Name: Expiry The name of the JWT field that carries the expiration time. For example, exp.
JWT Field Name: Client ID The name of the JWT field that carries the client ID(s) that the token is issued for. For example, aud.
JWT Field Name: Scope The name of the JWT field that carries the access scope. For example, scope or scp.
JWT Field Name: Issuer The name of the JWT field that carries the token issuer. For example, iss.
Scopes This must be set to a list of Scope values, separated by white space, that the BlackBerry Infrastructure should accept. Tokens given to the SDK must have one of these values in their JWT Scope field.
Client IDs This must be set to a list of Client ID values, separated by white space, the BlackBerry Infrastructure should accept. Tokens given to the SDK must have one of these values in their JWT Client ID field.

Examples

The Support libraries that come with the SDK contain code that you can use to to help your application use Google Sign-In or Azure Active Directory as an identity provider.