Approov is an API security solution used to verify that requests received by your backend services originate from trusted versions of your mobile apps.
This repo implements the Approov server-side request verification code in PHP (framework agnostic), which performs the verification check before allowing valid traffic to be processed by the API endpoint.
You can learn more about Approov, the motives for adopting it, and more detail on how it works by following this link. In brief, Approov:
- Ensures that accesses to your API come from official versions of your apps; it blocks accesses from republished, modified, or tampered versions
- Protects the sensitive data behind your API; it prevents direct API abuse from bots or scripts scraping data and other malicious activity
- Secures the communication channel between your app and your API with Approov Dynamic Certificate Pinning. This has all the benefits of traditional pinning but without the drawbacks
- Removes the need for an API key in the mobile app
- Provides DoS protection against targeted attacks that aim to exhaust the API server resources to prevent real users from reaching the service or to at least degrade the user experience.
This is a brief overview of how the Approov cloud service and the PHP server fit together from a backend perspective. For a complete overview of how the mobile app and backend fit together with the Approov cloud service and the Approov SDK we recommend to read the Approov overview page on our website.
The Approov cloud service attests that a device is running a legitimate and tamper-free version of your mobile app.
- If the integrity check passes then a valid token is returned to the mobile app
- If the integrity check fails then a legitimate looking token will be returned
In either case, the app, unaware of the token's validity, adds it to every request it makes to the Approov protected API(s).
The PHP backend server ensures that the token supplied in the Approov-Token header is present and valid. The validation is done by using a shared secret known only to the Approov cloud service and the PHP backend server.
The request is handled such that:
- If the Approov Token is valid, the request is allowed to be processed by the API endpoint
- If the Approov Token is invalid, an HTTP 401 Unauthorized response is returned
You can choose to log JWT verification failures, but we left it out on purpose so that you can have the choice of how you prefer to do it and decide the right amount of information you want to log.
In order to correctly check for the expiration times of the Approov tokens is very important that the PHP backend server is synchronizing automatically the system clock over the network with an authoritative time source. In Linux this is usual done with a NTP server.
The quickstart code for the Approov PHP server is split into two implementations. The first gets you up and running with basic token checking. The second uses a more advanced Approov feature, token binding. Token binding may be used to link the Approov token with other properties of the request, such as user authentication (more details can be found here).
Both the quickstarts are built from the unprotected example server defined here, thus you can use Git to see the code differences between them.
Code difference between the Approov token check quickstart and the original unprotected server:
git diff --no-index src/unprotected-server/hello-server-unprotected.php src/approov-protected-server/token-check/hello-server-protected.php
You can do the same for the Approov token binding quickstart:
git diff --no-index src/unprotected-server/hello-server-unprotected.php src/approov-protected-server/token-binding-check/hello-server-protected.php
Or you can compare the code difference between the two quickstarts:
git diff --no-index src/approov-protected-server/token-check/hello-server-protected.php src/approov-protected-server/token-binding-check/hello-server-protected.php
The code examples for the Approov quickstarts are extracted from this simple Approov integration examples, that you can run from your computer to play around with the Approov integration and gain a better understanding of how simple and easy it is to integrate Approov in a PHP API server.
A ready-to-use Postman collection can be found here. It contains a comprehensive set of example requests to send to the PHP server for testing. The collection contains requests with valid and invalid Approov tokens, and with and without token binding.
An alternative to the Postman collection is to use cURL to make the API requests. Check some examples here.
The valid Approov tokens in the Postman collection and cURL requests examples were signed with a dummy secret that was generated with openssl rand -base64 64 | tr -d '\n'; echo, therefore not a production secret retrieved with approov secret -get base64, thus in order to use it you need to set the APPROOV_BASE64_SECRET, in the .env file for each Approov integration example, to the following value: h+CX0tOzdAAR9l15bWAqvq7w9olk66daIH+Xk+IAHhVVHszjDzeGobzNnqyRze3lw/WVyWrc2gZfh3XXfBOmww==.
If you wish to explore the Approov solution in more depth, then why not try one of the following links as a jumping off point: