Customer Authentication

What is Customer Authentication?

Customer Authentication is an optional feature introduced in iOS & Android SDK 4.0 that allows multiple customers to use your app on a single device while keeping their data separate and secure. Once enabled, customers will see their own personal Message Center, and their data will be encrypted while in the SDK and in flight. If you choose not to use Customer Authentication, the existing behavior, where all Apptentive information is shared among all potential users of the device, will remain in place.

To use Customer Authentication, you must:

  • Have an authentication system you control that allows multiple people to log into your app.
  • Generate JWT tokens in that authentication system and return them to the app.
  • Update your app code to call the appropriate Apptentive login method with the generated JWT.

Below we will walk through the requirements for the JWT token and sample code of the work required in addition to integrating the SDK.

If you do not plan to use the new Customer Authentication feature, this work is not required.

Authentication Flow

  1. Customer enters login information in your app’s login form.
  2. Your server processes that authentication information and finds the person has supplied valid auth information. It generates a JWT for that user and returns it to the device.
  3. You must pass the JWT to the platform-specific “login” method to create/fetch the logged in Apptentive Conversation.
  4. The Apptentive SDK sends the JWT to our server, if valid, it unlocks the encrypted Conversation on the device.
  5. The callback you passed into the Apptentive login API method is called with the status of the login.

The JWT Token

To authenticate requests made to the Apptentive API, SDK 4.0 and above send JWT tokens with each request. For anonymous conversations (ones that have never been logged into), Apptentive will generate the token, but for logged in conversations the token must be generated by your server as part of your user authentication process.

Libraries

jwt.io has an extensive list of libraries that can be used to work with these tokens.

Requirements

To generate a JWT token, there are three required pieces:

  • Payload
    • See the required fields below.
  • Signing secret
  • Signing algorithm
    • Apptentive expects tokens to be signed with the HS512 algorithm.

Field Descriptions

The payload of a JWT is an arbitrary hash of keys (“claims” in JWT parlance) and values; however, Apptentive does require a few claims to generate a valid token.

  • iat – (“issued at”) REQUIRED
    • The UTC timestamp when the token was generated
  • exp – (“expiration”) OPTIONAL
    • The UTC timestamp to invalidate the token
    • Set this to be slightly longer than your authentication service’s session length
    • Apptentive enforces a maximum token length of 30 days
  • sub – (“subject”) REQUIRED
    • A unique, immutable identifier for the user used for database lookup
      • This value must not change, otherwise Apptentive will treat it as a new Conversation and the customer will lose their message history.
    • Uniqueness for this field is scoped to each App in Apptentive

 

In Ruby, the hash payload would look like this:

{
  iat: 1501548760,
  exp: 1501807985,
  sub: "unique_immutable_value_for_user123121"
}

Generating a JWT

payload = {
  iat: 1501548760,
  exp: 1501807985,
  sub: "unique_immutable_value_for_user123121"
}
token = JWT.encode(payload, apptentive_provided_secret, "HS512")

The resulting token will be 3 base64-encoded sections separated by periods looking something like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1bmlxdWVfaW1tdXRhYmxlX3ZhbHVlX2Zvcl91c2VyMTIzMTIxIiwiaWF0IjoxMjMxMjMxMjMxLCJleHAiOjEyMzEyMzEyMzJ9.1xUmdJqFygoDI-1N2gJzICvC-qdaWUATBBUM35dxrPM

Example Code

Two very basic apps (written in Ruby and Java) are provided in the git repository below to show an example of an API you might create to authenticate a user and generate a JWT token. Note that the details of user authentication and unique user token generation are skimmed over and your team must implement them.

https://github.com/apptentive/apptentive-sdk-auth-example

Updated on August 8, 2017

Was this article helpful?

Related Articles