Updated readme.md for review - totaljs#43

aubergine10 · aubergine10 · commit 3ec8ae40bfaf · 2016-05-16T20:38:10.000+01:00
Added note on caching credentials to avoid excessive db lookups, also
added note on req.uri.auth
diff --git a/authorization-www-basic/readme.md b/authorization-www-basic/readme.md
@@ -9,6 +9,8 @@ Features covered by this example:
 
 See the `/controllers/default.js` for sample code.
 
+> **Note:** BAA doesn't attempt to encrypt credentials and as such should only be used on HTTPS connections.
+
 ### Reading credentials
 
 To read credentials, use the `.baa()` method in a route handler function:
@@ -39,7 +41,7 @@ function authorization() {
   // ...
 
   if (auth.empty) { // ask user to login
-    this.baa('Log in, bro.'); // or whatever prompt you want the user to see
+    this.baa('Admin Login Required.'); // or whatever prompt you want the user to see
     return;
   }
 
@@ -50,10 +52,10 @@ function authorization() {
 This sends a response back to the browser which has a `WWW-Authenticate` HTTP header like this:
 
 ```
-WWW-Authenticate: Basic realm="Log in, bro."
+WWW-Authenticate: Basic realm="Admin Login Required."
 ```
 
-On seeing that header, the browser will display the prompt (`Log in, bro.`) along with a basic login form with fields for username and password. When the user submits the form, the browser will retry the request, only this time it will have the required `Authorization` HTTP header that we are looking for.
+On seeing that header, the browser will display the prompt (`Admin Login Required.`) along with a basic login form with fields for username and password. When the user submits the form, the browser will retry the request, only this time it will have the required `Authorization` HTTP header that we are looking for.
 
 ### Validating credentials
 
@@ -74,7 +76,7 @@ function authorization() {
   } else {
 
     // ask them to login again?
-    this.baa('Wrong details, try again, bro.');
+    this.baa('Admin Login Required.');
     return;
 
     // or maybe just throw a #401 error?
@@ -86,8 +88,72 @@ function authorization() {
 }
 ```
 
-> Note: The browser will keep sending the `Authorization` header on subsequent requests for about 15 minutes or more, effectively keeping the user logged in (from user perspective). Downside is that, server-side, you have to re-check the credentials on every request.
+### Bonus 1: Server-side caching
+
+The browser will keep sending the `Authorization` header on subsequent requests for about 15 minutes, effectively keeping the user logged in (from user perspective). Downside is that, server-side, you have to re-check the credentials on every request. As such it's probably worth keeping a cache of validated credentials to avoid excessive database lookups, for example:
+
+```javascript
+var baaCache = {};
+
+function authorization() {
+
+  // ...
+
+  if ( (baaCache[auth.user] && baaCache[auth.user] === auth.password) || isValidLogin( auth.user, auth.password ) ) {
+
+    baaCache[auth.user] = auth.password; // cache
 
-## Notes
+    // do authorised stuff
+
+  } else {
+    // ...
+  }
+}
 
-BAA doesn't make any attempt to encrypt the login details it sends via the `Authorization` HTTP header so, ideally, you should only ever use BAA over HTTPS connections.
+function housekeeping(tick) {
+  if (tick % 5 === 0) // every 5 mins clear cache
+    baaCache = {};
+}
+
+// add this to export.install() at top of script:
+F.on('service', housekeeping)
+
+// also add an export.uninstall() to remove the listener
+export.uninstall = function() {
+  F.removeListener('service', housekeeping);
+}
+```
+### Bonus 2: URI authentication
+
+The `.baa()` method only checks request HTTP headers for credentials, it doesn't check for credentials in the URI like this:
+
+```
+https://user:password@www.example.com/
+```
+
+If you wish to accept credentials in the URI, use `.req.uri.auth`:
+
+```javascript
+function authorization() {
+
+  // ...
+
+  if (auth.empty) { // check for URI auth first, before asking user to login
+
+    if (this.req.uri.auth) { // found credentials on auth, use those instead
+
+      let creds = this.req.uri.auth.split(':');
+      auth.user = creds[0];
+      auth.password = creds[1];
+      auth.empty = false;
+
+    } else {
+      this.baa('Admin Login Required.'); // or whatever prompt you want the user to see
+      return;
+    }
+
+  }
+
+  // ...
+}
+```
