Secure Mode helps to make sure that conversations between you and your users are kept private, and that one user can't impersonate another. In Secure Mode, Intercom will sign all requests going to the Intercom servers with tokens. It requires your mobile application to have its own server which authenticates the app's users, and which can store a secret.
Here's how to make it work.
We recommend you enable Secure Mode right from the start, when you first integrate Intercom into your Android app. Of course, you can still enable Secure Mode later, but you will have to ensure that Intercom won't break for existing clients. As we will describe below, once you activate Secure Mode for an app, the server has to reject all requests (from clients running an older version of your app) that are not secure.
Don't worry–even once you've released the secure mode enabled version of your app to the app store, you decide when to enable Secure Mode. Typically, after you publish your secure mode enabled app version on the Play Store you would monitor how many users have upgraded to this new version and only once you reach a high level of adoption would you enforce Secure Mode for your app.
- When your users log into your Android app, the app authenticates them with your app server. It does so securely with TLS (SSL pinning may also be used here).
- Your app server uses the Intercom API Secret to create a HMAC digest from some user data (for instance the user's email address or unique user id) and returns both values (user data and HMAC digest) to your Android app.
- Your Android app passes the digest and user data to the Intercom for Android library.
- The Intercom API server uses its copy of the API secret to verify the HMAC digest for every request that comes from the Android library so we can be sure that it was authorized by your app server.
Step by Step Configuration
Please note that Secure Mode needs to be activated and configured separately for your test version and production Intercom apps.
Getting the API Secret
Get the Secure Mode Secret Key from the Android Integrations page found in your Intercom app's settings and store it in a secure place on your app server (do NOT put it into the mobile app - because that would defeat the purpose of making it secure!).
Toggle the Setup Secure Mode switch to Enabled and your Secure Mode Secret will appear.
Warning for users who have already published a mobile app using the Android integration without Secure Mode: selecting Secure Mode in this dialog means that from now on the API server will reject all requests that are not secure - effectively cutting off your existing apps until they support Secure Mode. Remember, after testing, you can always turn off this option and non-secure requests will be allowed again.
Returning User Data and HMAC Digest from your App Server's Authentication Call
Your app server authentication code needs to be modified so that is uses the Intercom API Secret to create a HMAC digest (hash based message authentication code) from some user data which should be the user id or email address. Then it returns both values (user data and HMAC digest) to your Android app. Note that secure mode does not apply to unidentified users, for whom you do not have a user id or email address.
The HMAC is computed as a SHA-256 digest as follows (ruby code snippet):
OpenSSL::HMAC.hexdigest('sha256', api_key.secret, data)
Setting the Security Options when you Initialize Intercom
From the Intercom App Settings (section API keys) get the API Key and your App Id. When your Android app initializes Intercom if the user is identified (i.e., you have a user id or email address), pass in the these values along with a dictionary of the HMAC digest and the user data:
The Intercom API Auth Server uses its copy of the API Secret to recreate the HMAC digest from the user data. If it matches with the supplied HMAC digest, we can be sure that this request is coming from your app server and the API Auth Server issues an access token to the Android SDK.
If the HMAC fails to verify, the API Auth Server responds with a 401.
- You must use the exact Secret Key that we provide you within the code. Making up your own won't work. Note: Don't confuse this with your app_id.
- The same user data you are using on the server side to calculate the HMAC digest must be passed into the Android SDK.
- Do not forget that Secure Mode needs to be activated (and configured) separately in your development/test and production apps.
- Please note that for the Android integration, the API Key always starts with "android_sdk-..:". If this is not the case, use this link to upgrade your app https://app.intercom.io/inapps_update. Note: this will have to be done separately for your Test and Production Intercom app.