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 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.
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.
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.
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.
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.
Make sure that the Enable User Authentication toggle switch is on.
Select the OpenID Connect tab and fill in the form as explained below.
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.