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 iOS 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 App 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 iOS 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 iOS app.
- Your iOS app passes the digest and user data to the Intercom for iOS library.
- The Intercom API server uses its copy of the API secret to verify the HMAC digest for every request that comes from the iOS 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 API Secret from the iOS integrations page 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!). (Please note that for versions 2.x of Intercom for iOS, the API Key always start with “ios_sdk-..:".)
Toggle the switch to the "On" position and the secret key will appear
Warning for users who have already published a mobile app using the iOS integration without Secure Mode: selecting Secure Mode in this dialog means that from now on Intercom's API 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 it uses the Intercom API Secret to create a HMAC digest (hash based message authentication code) from some user data which should be user id or email address. Then it returns both values (user data and HMAC digest) to your iOS 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. If your user is identified (i.e., you have a user id or email address), call the following method after you have initialized Intercom or at a place where it is convenient for you to do so:
[Intercom setHMAC: 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 iOS 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 iOS library.
- Do not forget that Secure Mode needs to be activated (and configured) separately in your development/test and production apps.
- Please note that for versions 2.x and above of the iOS integration, the API Key always starts with “ios_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.