You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: EXAMPLES.md
+18-2Lines changed: 18 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,22 @@ or get a bash shell inside the container:
91
91
sudo docker-compose run --rm --service-ports approov-token-binding-check zsh
92
92
```
93
93
94
-
## Support
94
+
## Issues
95
95
96
-
If you find any issue while following this quickstart then just open an issue on this repo with the steps to reproduce it and we will help you to solve them.
96
+
If you find any issue while following our instructions then just report it [here](https://github.com/approov/quickstart-python-django-token-check/issues), with the steps to reproduce it, and we will sort it out and/or guide you to the correct path.
97
+
98
+
99
+
## Useful Links
100
+
101
+
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:
[Approov](https://approov.io) is an API security solution used to verify that requests received by your backend services originate from trusted versions of your mobile apps.
4
+
5
+
6
+
## Why?
7
+
8
+
You can learn more about Approov, the motives for adopting it, and more detail on how it works by following this [link](https://approov.io/product). In brief, Approov:
9
+
10
+
* Ensures that accesses to your API come from official versions of your apps; it blocks accesses from republished, modified, or tampered versions
11
+
* Protects the sensitive data behind your API; it prevents direct API abuse from bots or scripts scraping data and other malicious activity
12
+
* Secures the communication channel between your app and your API with [Approov Dynamic Certificate Pinning](https://approov.io/docs/latest/approov-usage-documentation/#approov-dynamic-pinning). This has all the benefits of traditional pinning but without the drawbacks
13
+
* Removes the need for an API key in the mobile app
14
+
* 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.
15
+
16
+
17
+
## How it works?
18
+
19
+
This is a brief overview of how the Approov cloud service and the backend 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](https://approov.io/product) page on our website.
20
+
21
+
### Approov Cloud Service
22
+
23
+
The Approov cloud service attests that a device is running a legitimate and tamper-free version of your mobile app.
24
+
25
+
* If the integrity check passes then a valid token is returned to the mobile app
26
+
* If the integrity check fails then a legitimate looking token will be returned
27
+
28
+
In either case, the app, unaware of the token's validity, adds it to every request it makes to the Approov protected API(s).
29
+
30
+
### The Backend Server
31
+
32
+
The 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 backend server.
33
+
34
+
The request is handled such that:
35
+
36
+
* If the Approov Token is valid, the request is allowed to be processed by the API endpoint
37
+
* If the Approov Token is invalid, an HTTP 401 Unauthorized response is returned
38
+
39
+
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.
40
+
41
+
42
+
## Useful Links
43
+
44
+
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:
[Approov](https://approov.io) is an API security solution used to verify that requests received by your backend services originate from trusted versions of your mobile apps.
4
+
5
+
6
+
## The Quickstarts
7
+
8
+
The quickstart code for the Approov backend 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](https://approov.io/docs/latest/approov-usage-documentation/#token-binding)).
*[Approov token check with token binding quickstart](/docs/APPROOV_TOKEN_BINDING_QUICKSTART.md)
11
+
12
+
Both the quickstarts are built from the unprotected example server defined [here](/src/unprotected-server/hello), thus you can use Git to see the code differences between them.
13
+
14
+
Code difference between the Approov token check quickstart and the original unprotected server:
If you find any issue while following our instructions then just report it [here](https://github.com/approov/quickstart-python-django-token-check/issues), with the steps to reproduce it, and we will sort it out and/or guide you to the correct path.
35
+
36
+
37
+
## Useful Links
38
+
39
+
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:
Copy file name to clipboardExpand all lines: README.md
+86-56Lines changed: 86 additions & 56 deletions
Original file line number
Diff line number
Diff line change
@@ -7,109 +7,139 @@ This repo implements the Approov server-side request verification code in Python
7
7
This is an Approov integration quickstart example for the Python Django framework. If you are looking for another Python integration you can check our list of [quickstarts](https://approov.io/docs/latest/approov-integration-examples/backend-api/), and if you don't find what you are looking for, then please let us know [here](https://approov.io/contact). Meanwhile, you can always use the framework agnostic [quickstart example](https://github.com/approov/quickstart-python-token-check) for Python, and you may find that's easily adaptable to your framework of choice.
8
8
9
9
10
-
## TOC - Table of Contents
10
+
## Approov Integration Quickstart
11
11
12
-
*[Why?](#why)
13
-
*[How it Works?](#how-it-works)
14
-
*[Quickstarts](#approov-integration-quickstarts)
15
-
*[Examples](#approov-integration-examples)
16
-
*[Useful Links](#useful-links)
12
+
The quickstart was tested with the following Operating Systems:
17
13
14
+
* Ubuntu 20.04
15
+
* MacOS Big Sur
16
+
* Windows 10 WSL2 - Ubuntu 20.04
18
17
19
-
## Why?
18
+
First, setup the [Appoov CLI](https://approov.io/docs/latest/approov-installation/index.html#initializing-the-approov-cli).
20
19
21
-
You can learn more about Approov, the motives for adopting it, and more detail on how it works by following this [link](https://approov.io/product). In brief, Approov:
20
+
Now, register the API domain for which Approov will issues tokens:
22
21
23
-
* Ensures that accesses to your API come from official versions of your apps; it blocks accesses from republished, modified, or tampered versions
24
-
* Protects the sensitive data behind your API; it prevents direct API abuse from bots or scripts scraping data and other malicious activity
25
-
* Secures the communication channel between your app and your API with [Approov Dynamic Certificate Pinning](https://approov.io/docs/latest/approov-usage-documentation/#approov-dynamic-pinning). This has all the benefits of traditional pinning but without the drawbacks
26
-
* Removes the need for an API key in the mobile app
27
-
* 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.
22
+
```bash
23
+
approov api -add api.example.com
24
+
```
28
25
29
-
[TOC](#toc---table-of-contents)
26
+
Next, enable your Approov `admin` role with:
30
27
28
+
```bash
29
+
eval`approov role admin`
30
+
```
31
31
32
-
## How it works?
32
+
Now, get your Approov Secret with the [Appoov CLI](https://approov.io/docs/latest/approov-installation/index.html#initializing-the-approov-cli):
33
33
34
-
This is a brief overview of how the Approov cloud service and the Python Django API 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](https://approov.io/product) page on our website.
34
+
```bash
35
+
approov secret -get base64
36
+
```
35
37
36
-
### Approov Cloud Service
38
+
Next, add the [Approov secret](https://approov.io/docs/latest/approov-usage-documentation/#account-secret-key-export) to your project `.env` file:
37
39
38
-
The Approov cloud service attests that a device is running a legitimate and tamper-free version of your mobile app.
40
+
```env
41
+
APPROOV_BASE64_SECRET=approov_base64_secret_here
42
+
```
39
43
40
-
* If the integrity check passes then a valid token is returned to the mobile app
41
-
* If the integrity check fails then a legitimate looking token will be returned
44
+
Now, add to your `requirements.txt` file the [JWT dependency](https://github.com/jpadilla/pyjwt/):
42
45
43
-
In either case, the app, unaware of the token's validity, adds it to every request it makes to the Approov protected API(s).
46
+
```bash
47
+
PyJWT==1.7.1 # update the version to the latest one
48
+
```
44
49
45
-
### Python Django API Server
50
+
Next, you need to install the dependencies:
46
51
47
-
The Python Django API 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 Python Django API server.
52
+
```bash
53
+
pip3 install -r requirements.txt
54
+
```
48
55
49
-
The request is handled such that:
56
+
Now, add the [approov_middleware.py](/src/approov-protected-server/token-check/hello/approov_middleware.py) class to your project:
50
57
51
-
* If the Approov Token is valid, the request is allowed to be processed by the API endpoint
52
-
* If the Approov Token is invalid, an HTTP 401 Unauthorized response is returned
58
+
```python
59
+
from django.http import JsonResponse
60
+
from os import getenv
61
+
from dotenv import load_dotenv, find_dotenv
62
+
import base64
63
+
import jwt # https://github.com/jpadilla/pyjwt/
53
64
54
-
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 Python Django API server is synchronizing automatically the system clock over the network with an authoritative time source. In Linux this is usually done with a NTP server.
70
+
load_dotenv(find_dotenv(), override=True)
59
71
60
-
[TOC](#toc---table-of-contents)
72
+
# Token secret value obtained with the Approov CLI tool:
The quickstart code for the Approov Python Django API 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](https://approov.io/docs/latest/approov-usage-documentation/#token-binding)).
The code examples for the Approov quickstarts are extracted from this simple [Approov integration examples](/src/approov-protected-server), 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 Python Django API server.
110
+
```
83
111
84
-
### Testing with Postman
112
+
Finally, to activate the [Approov Middleware](/src/approov-protected-server/token-check/hello/approov_middleware.py) you just need to include it in the middleware list of your [Django settings](/src/approov-protected-server/token-check/hello/settings.py) as the first one in the list:
85
113
86
-
A ready-to-use Postman collection can be found [here](https://raw.githubusercontent.com/approov/postman-collections/master/quickstarts/hello-world/hello-world.postman_collection.json). It contains a comprehensive set of example requests to send to the Python Django API server for testing. The collection contains requests with valid and invalid Approov tokens, and with and without token binding.
> **NOTE:** The Approov middleware is included as the first one in the list because you don't want to waste your server resources in processing requests that don't have a valid Approov token. This approach will help your server to handle more load under a Denial of Service(DoS) attack.
89
123
90
-
An alternative to the Postman collection is to use cURL to make the API requests. Check some examples [here](https://github.com/approov/postman-collections/blob/master/quickstarts/hello-world/hello-world.postman_curl_requests_examples.md).
124
+
Not enough details in the bare bones quickstart? No worries, check the [detailed quickstarts](QUICKSTARTS.md) that contain a more comprehensive set of instructions, including how to test the Approov integration.
91
125
92
-
### The Dummy Secret
93
126
94
-
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](/src/approov-protected-server), to the following value: `h+CX0tOzdAAR9l15bWAqvq7w9olk66daIH+Xk+IAHhVVHszjDzeGobzNnqyRze3lw/WVyWrc2gZfh3XXfBOmww==`.
127
+
## Issues
95
128
96
-
[TOC](#toc---table-of-contents)
129
+
If you find any issue while following our instructions then just report it [here](https://github.com/approov/quickstart-python-django-token-check/issues), with the steps to reproduce it, and we will sort it out and/or guide you to the correct path.
97
130
98
131
99
132
## Useful Links
100
133
101
134
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:
0 commit comments