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.

Architecture Overview - Identity Management

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.

Authentication Flow

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.

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.

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.