From 9a6df729f91971a95de57bc3e949df410ecc91b2 Mon Sep 17 00:00:00 2001
From: Chris Houseknecht <chouse@ansible.com>
Date: Thu, 28 Aug 2014 16:34:15 -0400
Subject: [PATCH] JS documentation Authentication docs. Plus tweaks to doc site
 configuration.

---
 .../static/js/controllers/Authentication.js   | 51 ++++++++++++++++---
 1 file changed, 43 insertions(+), 8 deletions(-)

diff --git a/awx/ui/static/js/controllers/Authentication.js b/awx/ui/static/js/controllers/Authentication.js
index 78e6637a2f..fc605bdf5e 100644
--- a/awx/ui/static/js/controllers/Authentication.js
+++ b/awx/ui/static/js/controllers/Authentication.js
@@ -14,15 +14,52 @@
  * @description
  * Controller for handling /#/login and /#/logout routes.
  *
- * Tower (app.js) checks if the user is authenticated and whether the user session is in an unexpired state. If either condition is not true,
- * the user is redirected to /#/login.
+ * Tower (app.js) verifies the user is authenticated and that the user session is not expired. If either condition is not true,
+ * the user is redirected to /#/login and the Authentication controller.
  *
- * Functions for checking the session state are found in [lib/ansible/AuthService.js](/static/docs/api/lib.ansible.function:AuthService)
+ * Methods for checking the session state are found in [lib/ansible/AuthService.js](/static/docs/api/lib.ansible.function:AuthService), which is referenced here as Authorization.
  *
+ * #Login Modal Dialog
+ *
+ * The modal dialog prompting for username and password is found in templates/ui/index.html.
+ *```
+ *     <!-- login modal -->
+ *     <div id="login-modal" class="modal fade">
+ *         <div class="modal-dialog">
+ *             <div class="modal-content" id="login-modal-content">
+ *             </div><!-- modal-content -->
+ *         </div><!-- modal-dialog -->
+ *     </div><!-- modal -->
+ *```
+ * HTML for the login form is generated, compiled and injected into <div id="login-modal-content"></div> by the controller. This is done to associate the form with the controller's scope. Because
+ * <div id="login-modal"></div> is outside of the ng-view container, it gets associated with $rootScope by default. In the controller we create a new scope using $rootScope.$new() and associate
+ * that with the login form. Doing this each time the controller is instantiated insures the form is clean and not pre-populated with a prior user's username and password.
+ *
+ * Just before the release of 2.0 a bug was discovered where clicking logout and then immediately clicking login without providing a username and password would successfully log
+ * the user back into Tower. Implementing the above approach fixed this, forcing a new username/password to be entered each time the login dialog appears.
+ *
+ * #Login Workflow
+ *
+ * When the the login button is clicked, the following occurs:
+ *
+ * - Call Authorization.retrieveToken(username, password) - sends a POST request to /api/v1/authtoken to get a new token value.
+ * - Call Authorization.setToken(token, expires) to store the token and exipration time in a session cookie.
+ * - Start the expiration timer by calling the init() method of [lib/ansible/Timer.js](/static/docs/api/lib.ansible.function:Timer)
+ * - Get user informaton by calling Authorization.getUser() - sends a GET request to /api/v1/me
+ * - Store user information in the session cookie by calling Authorization.setUser().
+ * - Get the Tower license by calling Authorization.getLicense() - sends a GET request to /api/vi/config
+ * - Stores the license object in local storage by calling Authorization.setLicense(). This adds the Tower version and a tested flag to the license object. The tested flag is initially set to false.
+ *
+ * Note that there is a session timer kept on the server side as well as the client side. Each time an API request is made, Tower (in app.js) calls
+ * Timer.isExpired(). This verifies the UI does not think the session is expired, and if not, moves the expiration time into the future. The number of
+ * seconds between API calls before a session is considered expired is set in config.js as session_timeout.
+ *
+ * @Usage
+ * This is usage information.
  */
 'use strict';
 
-function Authenticate($log, $cookieStore, $compile, $window, $scope, $rootScope, $location, Authorization, ToggleClass, Alert, Wait,
+function Authenticate($log, $cookieStore, $compile, $window, $rootScope, $location, Authorization, ToggleClass, Alert, Wait,
     Timer, Empty) {
 
     var setLoginFocus, lastPath, sessionExpired, loginAgain,
@@ -171,10 +208,9 @@ function Authenticate($log, $cookieStore, $compile, $window, $scope, $rootScope,
             });
     });
 
-    // Call the API to get an cauth token
+    // Call the API to get an auth token
     scope.systemLogin = function (username, password) {
         $('.api-error').empty();
-        var token;
         if (Empty(username) || Empty(password)) {
             Alert('Error!', 'Please provide a username and password before attempting to login.', 'alert-danger', setLoginFocus, null, null, false);
         } else {
@@ -182,7 +218,6 @@ function Authenticate($log, $cookieStore, $compile, $window, $scope, $rootScope,
             Authorization.retrieveToken(username, password)
                 .success(function (data) {
                     $('#login-modal').modal('hide');
-                    token = data.token;
                     Authorization.setToken(data.token, data.expires);
                     $rootScope.sessionTimer = Timer.init();
                     scope.$emit('AuthorizationGetUser');
@@ -213,6 +248,6 @@ function Authenticate($log, $cookieStore, $compile, $window, $scope, $rootScope,
     };
 }
 
-Authenticate.$inject = ['$log', '$cookieStore', '$compile', '$window', '$scope', '$rootScope', '$location', 'Authorization', 'ToggleClass', 'Alert', 'Wait',
+Authenticate.$inject = ['$log', '$cookieStore', '$compile', '$window', '$rootScope', '$location', 'Authorization', 'ToggleClass', 'Alert', 'Wait',
     'Timer', 'Empty'
 ];