Merge 4343e29 into 5d25b67

Author: Grace Yim

CONTRIBUTING.md

@@ -16,3 +16,9 @@ To run the tests enter:
 ```shell
 $ mvn test
 ```
+
+To get coverage reports with the JaCoCo Maven Plugin:
+```shell
+$ mvn clean verify -P all-tests
+$ open target/site/jacoco/index.html
+```

README-Iframe.md

@@ -1,33 +1,30 @@
 # Authenticating using the Toopher `iframe`
 
-Toopher's `iframe`-based authentication flow is the simplest way for web developers to integrate Toopher Two-Factor Authentication into an application.
+Toopher's `<iframe>`-based authentication flow is the simplest way for web developers to integrate Toopher Two-Factor Authentication into an application.
 
-## Toopher `iframe` Authentication Overview
+## Toopher `<iframe>` Authentication Overview
 
 The `iframe`-based authentication flow works by inserting an `<iframe>` element into the HTML displayed to the user after a successful username/password validation (but before they are actually logged-in to the service).  The `iframe` URL is generated by our library and its content is served from the Toopher API server.  The `iframe` guides the user through the process of authenticating with Toopher.  Once complete, the `iframe` will return the result of the authentication to your server by `POST`ing the response via HTML to an endpoint of your choice.  Your server validates the cryptographic signature using our library which determines whether or not the user successfully authenticated.
 
 Two distinct `iframe` flows are available: 
 
-* **Simple** serve an all-in-one `iframe` that handles *Pairing* and
-  *Authentication*
+* **Simple** serve an all-in-one `iframe` that handles *Pairing* and *Authentication*
 * **More flexible** serve the *Pairing* `iframe` and the *Authentication* `iframe` as needed. Note: a *Pairing* request is used to pair a user account with a particular mobile device (this is typically a one-time process); an *Authentication* request is used to authenticate a particular action on behalf of a user
 
 ## Authentication Workflow
 
-### Step 0: Primary Authentication
-
+### Primary Authentication
 We recommend using some form of primary authentication before initiating a Toopher authentication request.  Typical primary authentication methods involve verifying that the user has a valid username and password to access the resource being protected.
 
 ### Step 1: Embed a request in an `<iframe>`
-
 After verifying the user's primary authentication, but before Assuming the user's primary authentication checks out, the next step is to kickoff Toopher authentication.
 
 1. Generate a URI by specifying the request parameters to the library as detailed below
 1. Display a webpage to your user that embeds this URI within an `<iframe>` element.  The markup requirements for the `<iframe>` element are described in the "HTML Markup" section
 
 ### Step 2: Validate the result
 1. Toopher-iframe results posted back to server
-1. Server calls `ToopherIframe.validate()` to verify that result is valid.  `.validate()` returns a `Map` of trusted data if the signature is valid, or throws a `SignatureValidationError` if the signature is invalid.
+1. Server calls `ToopherIframe.validatePostback()` to verify that result is valid.  `.validatePostback()` returns a `Map` of trusted data if the signature is valid, or throws a `SignatureValidationError` if the signature is invalid.
 1. The server should check for possible errors returned by the API in the `error_code` map entry
 1. If no errors were returned, the result of the authentication is in the `granted` map entry
 
@@ -47,9 +44,9 @@ There is no difference in the markup required for a Pairing vs. an Authenticatio
 
 ### All-in-one iframe
 
-#### Generating an iframe URI
+#### Generating an iframe URL
 
-Every Toopher Authentication session should include a unique `requestToken` - a randomized `String` that is included in the signed request to the Toopher API and returned in the signed response from the Toopher `iframe`.  To guard against potential replay attacks, your code should validate that the returned `requestToken` is the same one used to create the request.
+Every Toopher Authentication session should include a unique `requestToken` - a randomized `String` that is included in the signed request to the Toopher API and returned in the signed response from the Toopher `<iframe>`.  To guard against potential replay attacks, your code should validate that the returned `requestToken` is the same one used to create the request.
 
 Creating a random request token and storing it in the server-side session using the Java Servlet API:
 
@@ -60,11 +57,11 @@ Creating a random request token and storing it in the server-side session using
 
 The Toopher Authentication API provides the requester a rich set of controls over authentication parameters.
 
-    String authIframeUrl = iframeApi.authUri(userName, resetEmail, actionName, automationAllowed, challengeRequired, requestToken, requesterMetadata, ttl);
+    String authIframeUrl = iframeApi.getAuthenticationUrl(userName, resetEmail, requestToken, actionName, requesterMetadata);
 
-For the simple case of authenticating a user at login, a `loginIframeUrl` helper method is available:
+For the simple case of authenticating a user at login, a `getAuthenticationUrl` helper method is available:
 
-    String loginIframeUrl = iframeApi.loginUri(userName, resetEmail, requestToken)
+    String loginIframeUrl = iframeApi.getAuthenticationUrl(userName, resetEmail, requestToken)
 
 When the the `iframe` is served this way Toopher will determine if the
 input `userName` is already paired; if they have not, we will show the
@@ -80,7 +77,7 @@ In this example, `data` is a `Map<String, String[]>` of the form data POSTed to
     request.getSession().removeAttribute("ToopherRequestToken");
 
     try {
-        Map<String, String> validatedData = iframeApi.validate(data, requestToken);
+        Map<String, String> validatedData = iframeApi.validatePostback(data, requestToken);
         if (validatedData.containsKey("error_code")) {
             String errorCode = validatedData.get("error_code");
             // There was an error -- user should not be authenticated
@@ -104,78 +101,8 @@ In this example, `data` is a `Map<String, String[]>` of the form data POSTed to
         // went wrong (incorrect session token, expired TTL, invalid signature)
     }
 
-### Separate Pairing and Authentication iframes
-
-#### Generating an Authentication iframe URI
-
-Every Toopher Authentication session should include a unique `requestToken` - a randomized `String` that is included in the signed request to the Toopher API and returned in the signed response from the Toopher `iframe`.  To guard against potential replay attacks, your code should validate that the returned `requestToken` is the same one used to create the request.
-
-Creating a random request token and storing it in the server-side session using the Java Servlet API:
-
-    private static final SecureRandom secureRandom = new SecureRandom();
-    // simple way to generate a randomized string.  
-    String requestToken = new BigInteger(20 * 8, secureRandom).toString(32);
-    request.getSession().setAttribute("ToopherRequestToken", requestToken);
-
-The Toopher Authentication API provides the requester a rich set of controls over authentication parameters.
-
-    String authIframeUrl = iframeApi.authUri(userName, resetEmail, actionName, automationAllowed, challengeRequired, requestToken, requesterMetadata, ttl);
-
-For the simple case of authenticating a user at login, a `loginIframeUrl` helper method is available:
-
-    String loginIframeUrl = iframeApi.loginUri(userName, resetEmail, requestToken)
-
-#### Generating a Pairing iframe URI
-
-    String pairIframeUrl = iframeApi.pairUri(userName, resetEmail)
+### Separate Pairing iframe
 
-#### Validating postback data from Authentication iframe and parsing API errors
+#### Generating a Pairing iframe URL
 
-In this example, `data` is a `Map<String, String[]>` of the form data POSTed to your server from the Toopher Authentication `iframe`.  You should replace the commented blocks with code appropriate for the condition described in the comment.
-
-    Map<String, String[]> data = httpServletRequest.getParameterMap();
-    String requestToken = (String)request.getSession().getAttribute("ToopherRequestToken");
-    // invalidate the Request Token to guard against replay attacks
-    request.getSession().removeAttribute("ToopherRequestToken");
-
-    try {
-        Map<String, String> validatedData = iframeApi.validate(data, requestToken);
-        if (validatedData.containsKey("error_code")) {
-            // check for API errors
-            String errorCode = validatedData.get("error_code");
-            if (errorCode.equals(ToopherIframe.PAIRING_DEACTIVATED)) {
-                // User deleted the pairing on their mobile device.
-                // 
-                // Your server should display a Toopher Pairing iframe so their account can be re-paired
-                //
-            } else if (errorCode.equals(ToopherIframe.USER_OPT_OUT)) {
-                // User has been marked as "Opt-Out" in the Toopher API
-                //
-                // If your service allows opt-out, the user should be granted access.
-                //
-            } else if (errorCode.equals(ToopherIframe.USER_UNKNOWN)) {
-                // User has never authenticated with Toopher on this server
-                //
-                // Your server should display a Toopher Pairing iframe so their account can be paired
-                //
-            }
-        } else {
-            // Signature is valid, and no api errors -- check authentication result
-            boolean authPending = validatedData.get("pending").toLowerCase().equals("true");
-            boolean authGranted = validatedData.get("granted").toLowerCase().equals("true");
-
-            // authenticationResult is the ultimate result of Toopher second-factor authentication
-            boolean authenticationResult = authGranted && !authPending;
-            if (authenticationResults) {
-                // Log user in
-            } else {
-                // Fail authentication attempt
-            }
-        }
-    } catch (ToopherIframe.SignatureValidationError e) {
-        // Signature was invalid -- user should not authenticated
-        // 
-        // e.getMessage() will return more information about what specifically
-        // went wrong (incorrect session token, expired TTL, invalid signature)
-        // 
-    }
+    String pairIframeUrl = iframeApi.getUserManagementUrl(userName, resetEmail)

README.md

@@ -16,7 +16,7 @@ Make sure you visit (http://dev.toopher.com) to get acquainted with the Toopher
 The first step to accessing the Toopher API is to sign up for an account at the development portal (http://dev.toopher.com) and create a "requester". When that process is complete, your requester is issued OAuth 1.0a credentials in the form of a consumer key and secret. Your key is used to identify your requester when Toopher interacts with your customers, and the secret is used to sign each request so that we know it is generated by you.  This library properly formats each request with your credentials automatically.
 
 #### The Toopher Two-Step
-Interacting with the Toopher web service involves two steps: pairing, and authenticating.
+Interacting with the Toopher web service involves two steps: pairing and authenticating.
 
 ##### Pair
 Before you can enhance your website's actions with Toopher, your customers will need to pair their phone's Toopher app with your website.  To do this, they generate a unique, nonsensical "pairing phrase" from within the app on their phone.  You will need to prompt them for a pairing phrase as part of the Toopher enrollment process.  Once you have a pairing phrase, just send it to the Toopher API along with your requester credentials and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
@@ -34,13 +34,25 @@ import com.toopher.*;
 ToopherAPI api = new ToopherAPI("<your consumer key>", "<your consumer secret>");
 
 // Step 1 - Pair with their phone's Toopher app
-PairingStatus pairing = api.pair("pairing phrase", "username@yourservice.com");
+// With pairing phrase
+Pairing pairing = api.pair("username@yourservice.com", "pairing phrase");
+// With SMS
+Pairing pairing = api.pair("username@yourservice.com", "555-555-5555")
+// With QR code
+Pairing pairing = api.pair("username@yourservice.com")
 
 // Step 2 - Authenticate a log in
-AuthenticationStatus auth = api.authenticate(pairing.id, "my computer");
+// With pairingId and terminal name
+AuthenticationRequest auth = api.authenticate(pairing.id, "my computer");
+// With username and requester specified Id (Returns exception if terminal is not found)
+AuthenticationRequest auth = api.authenticate("username", null, "requesterSpecifiedId")
+// With username, terminal name and requester specified Id (Returns exception if terminal is not found)
+AuthenticationRequest auth = api.authenticate("username", "my computer", "requesterSpecifiedId")
+// With username and terminal name (New terminal is created if terminal is not found)
+AuthenticationRequest auth = api.authenticate("username", "my computer")
 
 // Once they've responded you can then check the status
-AuthenticationStatus status = api.getAuthenticationStatus(auth.id);
+auth.refreshFromServer()
 if (status.pending == false && status.granted == true) {
     // Success!
 }
@@ -62,8 +74,17 @@ Alternatively, you can consume this library using Maven:
     </dependency>
 
 #### Try it out
-Check out `com.toopher.ToopherAPIDemo.java` for an example program that walks you through the whole process!  A runnable jar for the demo can be built and executed as follows:
+Check out `com.toopher.ToopherAPIDemo.java` for an example program that walks you through the whole process!
+
+###Ant
+A runnable jar for the demo can be built and executed in Ant as follows:
 ```shell
 $ ant
 $ java -jar dist/toopher-1.0.0.jar
 ```
+
+###Maven
+The demo can be executed in Maven as follows:
+```shell
+$ mvn exec:java -Dexec.mainClass="com.toopher.ToopherAPIDemo"
+```

assets/js/toopher-web.js

@@ -23,13 +23,15 @@
         frameworkPostArgs = $.parseJSON(frameworkPostArgsJSON);
       }
       var postData = $.extend({}, msgData.payload, frameworkPostArgs);
+      var toopherData = {'toopher_iframe_data': $.param(postData)};
+
       if(iframe.attr('use_ajax_postback')){
-      $.post(iframe.attr('toopher_postback'), postData)
+      $.post(iframe.attr('toopher_postback'), toopherData)
         .done(function(data){
           data = $.parseJSON(data);
         });
       } else {
-        postToUrl(iframe.attr('toopher_postback'), postData, 'POST');
+        postToUrl(iframe.attr('toopher_postback'), toopherData, 'POST');
       }
     }
   }

pom.xml

@@ -86,7 +86,7 @@
                     <destFile>${basedir}/target/coverage-reports/jacoco-unit.exec</destFile>
                     <dataFile>${basedir}/target/coverage-reports/jacoco-unit.exec</dataFile>
                     <excludes>
-                        <exclude>**/ToopherAPIDemo.java</exclude>
+                        <exclude>**/ToopherAPIDemo.class</exclude>
                     </excludes>
                 </configuration>
                 <executions>
@@ -125,7 +125,7 @@
                         <version>0.7.1.201405082137 </version>
                         <configuration>
                             <excludes>
-                                <exclude>**/ToopherAPIDemo.java</exclude>
+                                <exclude>**/ToopherAPIDemo.class</exclude>
                             </excludes>
                         </configuration>
                         <executions>

src/main/java/com/toopher/Action.java

@@ -0,0 +1,31 @@
+package com.toopher;
+
+import org.json.JSONException;
+import org.json.JSONObject;
+
+/**
+ * Created by graceyim on 1/26/15.
+ */
+public class Action extends ApiResponseObject {
+    /**
+     * The unique id for the authentication request
+     */
+    public String id;
+
+    /**
+     * The name of the action
+     */
+    public String name;
+
+    public Action(JSONObject json) throws JSONException {
+        super(json);
+
+        this.id = json.getString("id");
+        this.name = json.getString("name");
+    }
+
+    public void update(JSONObject jsonResponse) throws JSONException {
+        this.name = jsonResponse.getString("name");
+        this.updateRawResponse(jsonResponse);
+    }
+}

src/main/java/com/toopher/ApiResponseObject.java

@@ -11,22 +11,27 @@ public class ApiResponseObject {
     /**
      * A map of the raw API response data
      */
-    public Map raw;
-    
+    public Map<String, Object> rawResponse;
+
     public ApiResponseObject(JSONObject json) throws JSONException {
-    	this.raw = jsonToMap(json);
+        this.rawResponse = jsonToMap(json);
+    }
+
+    public void updateRawResponse(JSONObject json) throws JSONException {
+        this.rawResponse = jsonToMap(json);
     }
 
-    private Map<String, Object> jsonToMap(JSONObject json) throws JSONException{
-    	Map<String,Object> result = new HashMap<String,Object>();
-    	
-    	for (Iterator<String> i = json.keys(); i.hasNext(); ) {
-    		String key = i.next();
-    		Object o = json.get(key);
-    		result.put(key, o);
-    	}
-    	
-    	return result;
+    private Map<String, Object> jsonToMap(JSONObject json) throws JSONException {
+        Map<String, Object> result = new HashMap<String, Object>();
+
+        Iterator<?> i = json.keys();
+        while(i.hasNext()){
+            String key = (String) i.next();
+            Object o = json.get(key);
+            result.put(key, o);
+        }
+
+        return result;
     }
 
 }