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.

For development and testing, Spark Communications Services also supports disabling user authentication completely when running in the sandbox.

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.

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.

BlackBerry recommends configuring a domain in the sandbox with user authentication disabled when you are first exploring and developing with the SDK. You can easily switch to a real identity provider later in development because your application uses the same SDK APIs even when operating without user authentication.

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.

When user authentication is disabled, anybody that knows your sandbox domain ID can access any identity in your sandbox domain because no token validation is performed. BlackBerry recommends against sending or storing important data in domains with user authentication disabled. They are intended for development and testing only.

Unsigned JWT Token Fields

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

The Support libraries for most variants of the SDK come with code that generates these tokens for you.

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.

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

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.

BlackBerry recommends that you use RFC 7662 OAuth 2.0 Token Introspection when selecting or implementing your Token Info service. The BlackBerry Infrastructure can integrate with an identity provider service that accepts an HTTP GET request with an access token parameter and returns the client ID in a JSON response.

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.

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

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.