Skip to main content

Token Binding

This section covers the optional token binding feature in Approov.

tip

If you are able to use one of our Mobile App Quickstarts then these typically include support for token binding, by specifying a particular http header that holds the source data for the hash. Similarly, the Backend API Quickstarts are able to extract the same information from the header and verify that the correct token binding is included in the Approov token.

Token Binding Concept​

Token binding extends the security of the Approov token through a strength in depth approach. The mechanism ties an arbitrary string to an Approov token by including its hash in one of the claims. The facility is intended for long lived data, such as an OAuth token or a user session identifier, that can be used to uniquely identify a user. The data is supplied to the Approov SDK as an ASCII encoded string. The SDK takes the string and calculates its SHA256 hash. This is then provided inside the Approov token in the pay claim as a base64 encoded string.

If the binding data changes then this invalidates all currently cached Approov tokens and new ones are requested on the next fetch. Thus it is important not to use rapidly changing data for binding. Ideally long lived user session tokens should be used that will likely not change during normal app usage.

note

Note that the hashing of the data sent in the pay claim is always done in the SDK itself. Only the SHA256 hash of the data is sent to the Approov cloud service, so there is no need to be concerned about additional Personal Identifiable Information (PII) being sent to the Approov cloud service.

Setting the Binding​

The data value may be explicitly set using the setDataHashInToken method in the SDK or frontend quickstart. Normally though the Mobile App Quickstarts will set the value automatically based on values provided in a binding header. If necessary, most integrations also provide a method to set the value explicitly.

When the data value is set the SHA256 hash of it is calculated and compared against any current value that is held. If the value is different, then any cached Approov token is cleared. Any subsequent Approov fetch call will obtain a new Approov token. The maximum rate at which new tokens can be fetched may be rate limited to prevent excessive usage if the binding data is modified and fetching performed in a tight loop.

The data binding is held in the pay claim of the generated Approov token. The same value is retained in all subsequently generated Approov tokens until it is changed with another setDataHashInToken call.

warning

Note that once a pay claim has been added it is not possible to remove its inclusion in the running app, only change its value.

Generating Example Token with Binding​

The example token generation also supports the ability to generate a token with a pay claim. This can be used to test backend integrations that must perform the same hashing calculation to compare the claim. For example we can use:

approov token -genExample your.domain -setDataHashInToken custom-data

You can decode the generated Approov token string as follows:

approov token -check eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJl…

This shows the pay claim hash derived from the string custom-data:

payload: {
  "did": "ExampleApproovTokenDID==",
  "exp": 1558640470,
  "ip": "1.2.3.4",
  "pay": "tih+xRFV8PMsDhKthuFdvqWtQpKdT+K8X5W3258EJnU="
}