add stormpath token authenticator docs and tests

docs/app/scripts/app.js

@@ -98,6 +98,14 @@ angular.module('docsApp', [
         templateUrl: 'views/samlIdpUrlBuilder.html',
         controller: 'MainCtrl'
       })
+      .when('/oauthStormpathTokenAuthenticator', {
+        templateUrl: 'views/oauthStormpathTokenAuthenticator.html',
+        controller: 'MainCtrl'
+      })
+      .when('/oauthStormpathTokenAuthenticationResult', {
+        templateUrl: 'views/oauthStormpathTokenAuthenticationResult.html',
+        controller: 'MainCtrl'
+      })
       .otherwise({
         redirectTo: '/home'
       });

docs/app/scripts/controllers/mainNav.js

@@ -220,6 +220,17 @@ function items() {
       anchor('authenticate')
     ]),
 
+    item('OAuthStormpathTokenAuthenticator', 'oauthStormpathTokenAuthenticator', [
+      anchor('Overview', 'top'),
+      anchor('constructor'),
+      anchor('authenticate')
+    ]),
+
+    item('OAuthStormpathTokenAuthenticationResult', 'oauthStormpathTokenAuthenticationResult', [
+      anchor('Overview', 'top'),
+      anchor('getAccount')
+    ]),
+
     item('Tenant', null, [
       anchor('Overview', 'top'),
       anchor('createApplication'),

docs/app/views/assertionAuthenticationResult.md

@@ -1,4 +1,4 @@
-## AsssertionAuthenticationResult
+## AssertionAuthenticationResult
 
 An `AsssertionAuthenticationResult` is returned by the [StormpathAssertionAuthenticator](stormpathAssertionAuthenticator).
 It encapsulates an authentication result from ID Site Callback or SAML Callback, and allows you to get the account that has authenticated.
@@ -15,7 +15,7 @@ Retrieves the [Account](account) object of the user that has authenticated.
 #### Usage
 
 ```javascript
-asssertionAuthenticationResult.getAccount(function(err, account) {
+assertionAuthenticationResult.getAccount(function(err, account) {
   console.log(account);
 });
 ```
@@ -63,4 +63,4 @@ The original JWT that was returned to your application, as the `?jwtResponse=<st
 <a name="expandedJwt"></a>
 ### <span class="property">property</span> .expandedJwt <em>Object</em>
 
-The parsed `stormpath_token`.
+The parsed `stormpath_token`.

docs/app/views/oauthStormpathTokenAuthenticationResult.md

@@ -0,0 +1,51 @@
+## OAuthStormpathTokenAuthenticationResult
+
+An `OAuthStormpathTokenAuthenticationResult` is returned by the [OAuthStormpathTokenAuthenticator](oauthStormpathTokenAuthenticator).
+It encapsulates an authentication result from ID Site Callback callback, and allows you to get the account that has authenticated.
+
+
+---
+
+<a name="getAccount"></a>
+### <span class="member">method</span> getAccount(*[options,]* callback)
+
+Retrieves the [Account](account) object of the user that has authenticated.
+
+#### Usage
+
+```javascript
+oauthStormpathTokenAuthenticationResult.getAccount(function(err, account) {
+  console.log(account);
+});
+```
+
+#### Parameters
+
+<table class="table table-striped table-hover table-curved">
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Type</th>
+      <th>Presence</th>
+      <th>Description<th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>_`options`_</td>
+      <td>`object`</td>
+      <td>_optional_</td>
+      <td>Name/value pairs to use as query parameters, for example, for [resource expansion](http://docs.stormpath.com/rest/product-guide/#link-expansion).</td>
+    </tr>
+    <tr>
+      <td>`callback`</td>
+      <td>function</td>
+      <td>required</td>
+      <td>The callback to execute upon resource retrieval. The 1st parameter is an `Error` object.  The 2nd parameter is the retrieved [Account](account) resource.</td>
+        </tr>
+  </tbody>
+</table>
+
+#### Returns
+
+If the request fails, the callback's first parameter (err) will report the failure. If the request succeeds, a [Account](account) instance will be provided to the callback as the callback's second parameter.

docs/app/views/oauthStormpathTokenAuthenticator.md

@@ -0,0 +1,110 @@
+## OAuthStormpathTokenAuthenticator
+
+Provides the ability to authenticate with Stormpath JWTs (`stormpath_token`).
+Your application will recieve this token when a user is redirected to your application from an ID Site.
+
+---
+
+
+<a name="constructor"></a>
+### <span class="member">constructor</span> OAuthStormpathTokenAuthenticator(application)
+
+Creates a new `OAuthStormpathTokenAuthenticator` instance for the provided application.
+
+
+#### Usage
+
+```javascript
+var authenticator = new stormpath.OAuthStormpathTokenAuthenticator(application);
+```
+
+
+#### Parameters
+
+<table class="table table-striped table-hover table-curved">
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Type</th>
+      <th>Presence</th>
+      <th>Description<th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`application`</td>
+      <td>[`Application`](application)</td>
+      <td>required</td>
+      <td>Stormpath [Application](application) to authenticate against.</td>
+    </tr>
+  </tbody>
+</table>
+
+
+#### Returns
+
+A new [`OAuthStormpathTokenAuthenticator`](oauthStormpathTokenAuthenticator) instance.
+
+---
+
+
+<a name="authenticate"></a>
+### <span class="member">method</span> authenticate(data, callback)
+
+Authenticates a `stormpath_token` and returns a [OAuthStormpathTokenAuthenticationResult](outhStormpathTokenAuthenticationResult), which
+can provide the [Account](account) that has authenticated.
+
+The `stormpath_token` is the value of the `jwtResponse` parameter in the callback URL, e.g. `https://myapp.com/idsite/callback?jwtResponse=<stormpath_token>`.
+
+
+#### Usage
+
+```javascript
+authenticator.authenticate(data, function(err, authenticationResult) {
+  if (err) {
+    console.error(err);
+    return;
+  }
+  console.log(authenticationResult);
+});
+```
+
+
+#### Parameters
+
+<table class="table table-striped table-hover table-curved">
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Type</th>
+      <th>Presence</th>
+      <th>Description<th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`data`</td>
+      <td>`object`</td>
+      <td>required</td>
+      <td>
+        <p>An object literal, with the following properties:</p>
+        <ul>
+          <li>`stormpath_token` - REQUIRED - A Stormpath JWT from an ID Site callback.</li>
+        </ul>
+      </td>
+    </tr>
+    <tr>
+      <td>`callback`</td>
+      <td>`function`</td>
+      <td>required</td>
+      <td>The callback to execute upon server response. The 1st parameter is an [error](Error).  The 2nd parameter is an [OAuthStormpathTokenAuthenticationResult](oauthStormpathTokenAuthenticationResult) instance.</td>
+    </tr>
+  </tbody>
+</table>
+
+
+#### Returns
+
+If the request fails, the callback's first parameter (`err`) will report the
+failure.  If the request succeeds, a [OAuthStormpathTokenAuthenticationResult](oauthStormpathTokenAuthenticationResult) instance
+will be provided to the callback as the callback's second parameter.

lib/authc/StormpathAssertionAuthenticator.js

@@ -23,6 +23,7 @@ StormpathAssertionAuthenticator.prototype.authenticate = function authenticate(s
     if (jwt.body.err){
       return callback(jwt.body.err);
     }
+
     // For Stormpath mapped JWT fields, see:
     // https://docs.stormpath.com/rest/product-guide/latest/005_auth_n.html#step-5-stormpath-response-with-jwt
     var accountHref = jwt.body.sub;

lib/oauth/stormpath-token.js

@@ -20,6 +20,14 @@ function OAuthStormpathTokenAuthenticator(application) {
 OAuthStormpathTokenAuthenticator.prototype.authenticate = function authenticate(data, callback) {
   var application = this.application;
 
+  if (typeof data !== 'object') {
+    throw new Error('The \'data\' parameter must be an object.');
+  }
+
+  if (typeof callback !== 'function') {
+    throw new Error('The \'callback\' parameter must be a function.');
+  }
+
   var formData = {
     grant_type: 'stormpath_token',
     token: data.stormpath_token

test/it/helpers.js

@@ -167,10 +167,39 @@ function getDefaultAccountStore(application,done){
   });
 }
 
+/**
+ * Creates a Stormpath JWT from an application and account.
+ *
+ * @function
+ *
+ * @param {Application} application - Stormpath Application to authenticate with.
+ * @param {Account} account - Stormpath account to authenticate with.
+ *
+ * @returns string - The serialized Stormpath JWT.
+ */
+function createStormpathToken(application, account, apiKey) {
+  if (!apiKey) {
+    apiKey = application.dataStore.requestExecutor.options.client.apiKey;
+  }
+
+  var payload = {
+    sub: account.href,
+    iat: new Date().getTime() / 1000,
+    iss: application.href,
+    status: 'AUTHENTICATED',
+    aud: apiKey.id
+  };
+
+  var token = common.jwt.create(payload, apiKey.secret, 'HS256');
+
+  return token.compact();
+}
+
 module.exports = {
   getDefaultAccountStore: getDefaultAccountStore,
   cleanupApplicationAndStores: cleanupApplicationAndStores,
   createApplication: createApplication,
+  createStormpathToken: createStormpathToken,
   getClient: getClient,
   uniqId: uniqId,
   fakeAccount: fakeAccount,