Identity Management

The BBM Enterprise SDK does not manage user identities or contact relationships for applications. The user accounts in the BBM Enterprise SDK represent users in the SDK only. The SDK leverages OAuth and OpenID Connect so it can easily authenticate and associate users to their BBM Enterprise SDK accounts.

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 BBM Enterprise SDK along with the user ID. The BBM Enterprise infrastructure uses the token to authenticate the user with your identity provider. The BBM Enterprise SDK client and 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.

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

OAuth 2.0

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

Token Info Endpoint

The BBM Enterprise 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 BBM Enterprise 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 BBM Enterprise infrastructure to invoke the service and process the response.

Client ID(s): The client_id(s) of an application registered in the application's OAuth provider.
HTTP method: The HTTP method to use to invoke the service, GET or POST. If using the GET method, the access token is passed as an URL parameter "access_token". If using the POST method, the access token is passed as an HTTP body parameter "token".
User ID field: 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.
Client ID field: The name of the field that contains the client_id in the JSON response. If the JSON response is composite, a field path in the format "<parent_field>.<child_field>.<client_id_field>" can be used.
Basic Auth User Name: The user name for HTTP basic authentication if required.
Basic Auth Password: The password for HTTP basic authentication if required.

User Info Endpoint

The BBM Enterprise 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 BBM Enterprise 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 BBM Enterprise SDK Sample applications demonstrate how to connect to BBM Enterprise Servers using Google Sign-In.

OpenID Connect

The BBM Enterprise SDK 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 BBM Enterprise 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.

JWKS URI: The URI of the JWT token signature public keys from the identity provider.
Issuer Claim Name: The name of the claim for the token issuer. For example, "iss".
Issuer: The issuer of the claim accepted to access.
User ID Claim Name: The name of the claim for the user ID. For example, "sub". The claim value is used by the BBM Enterprise SDK as the user ID and it needs to match the user ID provided by the application.
Expiration Claim Name: The name of the claim for the expiration time. For example, "exp".
Client ID Claim Name: The name of the claim that carries the client ID(s) the token is issued for. For example, "aud".
Client IDs: The list of client ID values that are accepted by the BBM Enterprise infrastructure. A token is accepted when one of the client IDs from the token belongs to the configured client IDs.
Scope Claim Name: The name of the claim for the access scope. For example, "scope" or "scp".
Scopes: The list of scope values that are accepted by the BBM Enterprise infrastructure.

Example Identity Management Integrations

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