Troubleshooting section and attack details

casestudies-src/README.md

@@ -17,13 +17,15 @@
 docker-compose -f docker-compose.oauth.yml up --build
 ```
 A proxy server is listening on port `8080`. 
-This proxy is the only way to connect to the case study virtual network: the artificial RP is reachable through the proxy at `https://integrator.com`.
+This proxy is the only way to connect to the case study virtual network: 
+the artificial RP is reachable through the proxy at `https://integrator.com`.  
+A CA needs to be installed on the browser for the proxy to work correctly: you can download the certificate by visiting (through the proxy) the http://mitm.it website and installing it in the browser settings.
 
 The `docker-compose` command sets up a testing environment composed of four proxies:
 - a **reverse proxy** in front of the artificial RP. Web interface on port `8082`.
 - a **proxy** between the artificial RP and the IdPs (back channels). Web interface on port `8083`.
 - a **reverse proxy** in front of the artificial IdP. Web interface on port `8084`.
-- a **proxy** through which the virtual network is accessible (listening on port `8080`). Web interface on port `8081`. 
+- a **proxy** through which the virtual network is accessible (listening on port `8080`). Web interface on port `8081`.
 
 The artificial IdP "AS" is already configured and can be tested with the following user account:
 - `[email protected]:qwerty` (username:password)
@@ -33,14 +35,32 @@ The artificial IdP "AS" is already configured and can be tested with the followi
 
 The `http://attacker.com` website is accessible through the proxy on port `8080`.
 This malicious website integrates the AS IdP using the honest `client_id` and a malicious `redirect_uri` and can be used to mount the *Unauthorized login by auth. code redirection* attack. In particular, the attack is executed as follows
-1. The victim is tricked into clicking on the "Log in with AS" button at `attacker.com`
-2. The victim is redirected to the `/get-code.php` page that saves the code and show an error.
-3. The attacker can replay the obtained code (in `attacker.com/log.txt`) to the artificial RP to log in as the victim.
+1. The victim is tricked into clicking on the "Log in with AS" button at `attacker.com`.
+2. The victim is redirected to the `/get-code.php` page, that saves the victim auth. code and show an error.
+3. The attacker can replay the obtained code (in `attacker.com/log.txt`) to the artificial RP to log in as the victim:
+   1. The attacker visits `https://integrator.com/login`, clicks on "Log in with AS" and obtains a valid `state` parameters by extracting it from the auth-server.com URL `https://auth-server.com/oauth2/auth?response_type=code&client_id=67538654696&scope=email&redirect_uri=https%3A%2F%2Fintegrator.com%2Fas-verify&state=<STATE>`.
+   2. The attacker visits the callback page of integrator.com `https://integrator.com/as-verify?code=<CODE>&state=<STATE>` where,
+      - `<STATE>`: is the `state` parameter obtained at step 3.1
+      - `<CODE>`: is the victim auth. code that is stored in `attacker.com/log.txt`.
+   3. The attacker is now logged into integrator.com as the victim.
 
 ### Monitors
 
-1. The service worker monitor on the artificial RP is enabled by default and can be disabled by removing the `sw_monitor` folder in `/casestudies-src/artificial_rp/estensions/`. The monitor is currently configured for the AS (artificial IdP) integration: the configuration can be changed by editing the [sw.js](https://github.com/6Lp5GZYvrcWGwb20/bulwark_experiments/blob/master/casestudies-src/artificial_rp/extensions/sw_monitor/sw.js#L2) file.
-2. The proxy monitor on the artificial IdP can be enabled by decommenting [line 47](https://github.com/6Lp5GZYvrcWGwb20/bulwark_experiments/blob/master/casestudies-src/docker-compose.oauth.yml#L47) of the `docker-compose.oauth.yml` file.
+1. The service worker monitor on the artificial RP is enabled by default and can be disabled by removing the `sw_monitor` folder in `/casestudies-src/artificial_rp/estensions/`. The monitor is currently configured for the AS (artificial IdP) integration: the configuration can be changed by editing the [sw.js](https://github.com/secgroup/bulwark-experiments/blob/master/casestudies-src/artificial_rp/extensions/sw_monitor/sw.js#L2) file.
+2. The proxy monitor on the artificial IdP can be enabled by decommenting [line 47](https://github.com/secgroup/bulwark-experiments/blob/master/casestudies-src/docker-compose.oauth.yml#L47) of the `docker-compose.oauth.yml` file.
+
+
+### Troubleshooting
+
+- **I'm not able to visit `https://integrator.com` or `https://attacker.com`**.  
+  Make sure you set-up your browser to use the HTTP/HTTPS proxy that runs on
+  - Host: `localhost`
+  - Port: `8080`
+- **The certificate for `integrator.com`, `facebook.com`, ... is invalid!**  
+  Install on your browser the certificate authority (CA) that you can download by visiting http://mitm.it (after configuring the proxy).
+  The CA is generated on your local machine the first time you run docker-compose.
+- **I installed the CA, but the certificate of `auth-server.com` is still invalid.**  
+  This is an issue with recent versions of firefox. You can just add the exception for that website.
 
 ## PayPal
 
@@ -82,4 +102,4 @@ The website is now configured and you can test the integration using the `user1@
 
 ### Monitors
 
-1. The proxy monitor can be enabled by decommenting [line 32](https://github.com/6Lp5GZYvrcWGwb20/bulwark_experiments/blob/master/casestudies-src/docker-compose.paypal.yml#L32) **and** [line 48](https://github.com/6Lp5GZYvrcWGwb20/bulwark_experiments/blob/master/casestudies-src/docker-compose.paypal.yml#L48) of the `docker-compose.paypal.yml` file.
+1. The proxy monitor can be enabled by decommenting [line 32](https://github.com/secgroup/bulwark-experiments/blob/master/casestudies-src/docker-compose.paypal.yml#L32) **and** [line 48](https://github.com/secgroup/bulwark-experiments/blob/master/casestudies-src/docker-compose.paypal.yml#L48) of the `docker-compose.paypal.yml` file.