WIP: Simplify token strategy configuration

CHANGELOG.md

@@ -1,8 +1,23 @@
+## 3.0.0 (TBD)
+
+This release simplifies the [Stormpath Client API][] behaviour that was introduced in 2.0.0, the SDK now works in the following way:
+
+- By default, it will use the OAuth Token strategy, which means that:
+  - Login attemps are posted to `/oauth/token`
+  - Local storage is used to store the token. 
+  - Use `ReactStormpath.getAccesToken()` to get the access token and attach it to requests, as needed.
+  - This strategy with the Client API and with servers that are running our framework integrations, such as [Express-Stormpath][].
+
+- We still provide a cookie strategy, allowing you to use cookies to store and send the access token to your server. 
+
+For both cases, please see the [README][] and the [Upgrade Guide][] for specific examples of how to use this new version.
+
+
 ## 2.0.0 (January 13, 2017)
 
-This release adds support for the [Stormpath Client API][], which allows you to authenticate the user directly with Stormpath (authentication does not require extra software in your server).  The user receives an access token, which can be used to authorize requests on your server.  If you need to authorize requests on your server, you will sill want to use one of our SDKs to make that process simpler.
+*Deprecated* Please use 3.0.0 insetad.
 
-Please see the Readme for the new instructions for using the Client API.
+This release adds support for the [Stormpath Client API][], which allows you to authenticate the user directly with Stormpath (authentication does not require extra software in your server).  The user receives an access token, which can be used to authorize requests on your server.  If you need to authorize requests on your server, you will sill want to use one of our SDKs to make that process simpler.
 
 ## 1.3.4 (January 9, 2017)
 
@@ -107,4 +122,7 @@ Features:
   - Add support for new error structure ([#35](https://github.com/stormpath/stormpath-sdk-react/pull/35))
   - Add X-Stormpath-Agent header to requests ([#31](https://github.com/stormpath/stormpath-sdk-react/pull/31))
 
+[Express-Stormpath]: https://github.com/stormpath/express-stormpath
+[README]: https://github.com/stormpath/stormpath-sdk-react#stormpath-react-sdk
 [Stormpath Client API]: https://docs.stormpath.com/client-api/product-guide/latest/index.html
+[Upgrade Guide]: https://github.com/stormpath/stormpath-sdk-react/blob/master/UPGRADE.md

README.md

@@ -68,16 +68,18 @@ Stormpath already integrated!*
 
 3. **Initialize the SDK**
 
-  The React SDK leverages the [Stormpath Client API][] for its authentication needs. Login to your Stormpath Tenant, and find your Client API domain (inside your application's policy section).  Add your Client API domain as the `endpoints.baseUri` setting when initializing `ReactStormpath`:
+  The React SDK uses the [Stormpath Client API][] for its authentication needs. Login to your Stormpath Tenant, and find your Client API domain (inside your application's policy section).  Add your Client API domain as the `endpoints.baseUri` setting when initializing `ReactStormpath`:
 
   ```javascript
   ReactStormpath.init({
     endpoints: {
-      baseUri: 'https://{{clientApiDomainName}}'
+      baseUri: 'https://YOUR_CLIENT_API_DOMAIN.apps.stormpath.io'
     }
   });
   ```
 
+  Some alternate configurations available, e.g. if you want to use cookies (rather then the default local storage) for access token storage.  Please see the [Stormpath React SDK API Documentation][] for details.
+
 4. **Configure the Router**
 
   In the file where you setup your [React Router][] routes, change your [`ReactRouter.Router`][] to [`ReactStormpath.Router`][] as shown below:
@@ -193,7 +195,7 @@ Stormpath already integrated!*
 
 10. **That's It!**
 
-  You just added user authentication to your React app with Stormpath, you should now be able to register and login! See the [API Documentation][] for further information on how Stormpath can be used with your React app.  Once you have been able to successfully log in, the next section will discuss integrating with your own server.
+  You just added user authentication to your React app with Stormpath, you should now be able to register and login! See the [Stormpath React SDK API Documentation][] for further information on how Stormpath can be used with your React app.  Once you have been able to successfully log in, the next section will discuss integrating with your own server.
 
 11. **Making Authenticated Requests**
 
@@ -247,7 +249,7 @@ Stormpath already integrated!*
 
 ## Documentation
 
-For all available routes and components, see the [API Documentation][].
+For all available routes and components, see the [Stormpath React SDK API Documentation] Documentation][].
 
 ## Example
 
@@ -295,7 +297,7 @@ Apache 2.0, see [LICENSE](LICENSE).
 [`ReactStormpath.init()`]: https://github.com/stormpath/stormpath-sdk-react/blob/master/docs/api.md#initialization
 [`ReactStormpath.Router`]: https://github.com/stormpath/stormpath-sdk-react/blob/master/docs/api.md#router
 [`RegistrationForm`]: https://github.com/stormpath/stormpath-sdk-react/blob/master/docs/api.md#registrationform
-[API Documentation]: https://github.com/stormpath/stormpath-sdk-react/blob/master/docs/api.md
+[Stormpath React SDK API Documentation]: https://github.com/stormpath/stormpath-sdk-react/blob/master/docs/api.md
 [example app]: https://github.com/stormpath/stormpath-express-react-example
 [express-stormpath]: https://github.com/stormpath/express-stormpath
 [React Router]: https://github.com/rackt/react-router

UPGRADE.md

@@ -1,3 +1,20 @@
+## 1.x/2.x to 3.0.0 (TBD)
+
+This version adds support for the [Stormpath Client API][], which is specifically designed for front-end and mobile applications.  We suggest converting your React application to using this API for authenticating your users.  While the Client API is an easier way to authenticate users and get access tokens, your server is still responsible for authorizing requests with those tokens.  Our framework integrations such as [Express-Stormpath][] can still be used for this purpose.
+
+**If you are going to use the Client API:**
+
+- Please see the current [README][] for an example of how to find your Client API domain and pass it to this library.
+- If you are using [Express-Stormpath][], you should upgrade to 3.2.0 or later, and change any usage of `stormpath.loginRequired` to `stormpath.authenticationRequired`
+
+**If you do not wish to use the Client API:**
+
+If you already have a React application that is integrated with one of our server framework integrations, or you simply don't want to use the Client API and prefer to use our standard cookie approach, you can tell the React SDK to use your server with the cookie token strategy.  Please see the updated [Stormpath React SDK API Documentation][] for an example.
+
+## 2.0.0 (January 13, 2017)
+
+*Deprecated*. This version has been deprecated, please upgrade 3.0.0 instead.  This version introduced Client API support, but made it difficult to still use our traditional cookie solution for cookie storage.
+
 ## 1.3.3 to 1.3.4 (January 9, 2017)
 
 Nothing to do.
@@ -72,4 +89,9 @@ Notice:
   - The `LogoutLink` previously redirected the user to the path of the `LogoutRoute`.
   This has changed. The `LogoutRoute` is in fact no longer needed. So instead of
   redirecting to the `LogoutRoute` path, the `LogoutLink` will take care of doing
-  the logout itself.
+  the logout itself.
+
+[Express-Stormpath]: https://github.com/stormpath/express-stormpath
+[README]: https://github.com/stormpath/stormpath-sdk-react#stormpath-react-sdk
+[Stormpath Client API]: https://docs.stormpath.com/client-api/product-guide/latest/index.html
+[Stormpath React SDK API Documentation]: https://github.com/stormpath/stormpath-sdk-react/blob/master/docs/api.md

docs/api.md

@@ -1,15 +1,44 @@
-API Documentation
------------------
+Stormpath React SDK API Documentation
+-------------------------------------
 
 ## Initialization
 
-Before calling `React.render()` be sure to initialize/configure the SDK.
+Before calling `React.render()` be sure to initialize & configure the SDK, by providing the location of the authentication API.  We recommend you use the [Stormpath Client API][], and provide the domain for the Client API for your Stormpath application:
 
 ```javascript
-ReactStormpath.init();
+ReactStormpath.init({
+  endpoints: {
+    baseUri: 'https://YOUR_CLIENT_API_DOMAIN.apps.stormpath.io'
+  }
+});
+```
+
+Optionally, you can use one of our framework integrations, such as [Express-Stormpath][] to add the Stormpath authentication API to your own server, and then point the SDK at your server:
+
+```javascript
+ReactStormpath.init({
+  endpoints: {
+    baseUri: '/'  // The location of your server
+  }
+});
+```
+
+In both cases, when the user logs in they will have their access token stored in local storage and you can use `ReactStormpath.getAccessToken()` (read on for more detail).
+
+If you want to use our cookie strategy for storing the tokens (requires one of our framework integrations to assist) you would use this configuration:
+
+```javascript
+ReactStormpath.init({
+  endpoints: {
+    baseUri: '/',  // The location of your server
+  },
+  tokenStrategy: 'cookie'
+});
 ```
 
-If you want to configure it, simply pass an object with the configuration you want to use.
+## Configuration Reference
+
+The following configuration options are also available:
 
 ```javascript
 ReactStormpath.init({
@@ -24,24 +53,24 @@ ReactStormpath.init({
     store: yourReduxStore
   },
 
-  // Optional: If your are running our framework integration
-  // (e.g. express-stormpath) on a different domain, or you have
-  // changed the default endpoints in the framework integration.
-  // Values shown are the defaults.
+  // These are the default endpoints that the SDK will use when communicating 
+  // with Stormpath, and can be changed if needed.
   endpoints: {
-    baseUri: null, // E.g. https://api.example.com
+    baseUri: null, // e.g. 'https://YOUR_CLIENT_API_DOMAIN.apps.stormpath.io'
     me: '/me',
     login: '/login',
     register: '/register',
     verifyEmail: '/verify',
     forgotPassword: '/forgot',
     changePassword: '/change',
     logout: '/logout'
-  }
+  },
+
+  tokenStrategy: null // Local storage will be used it not set to `cookie`
 });
 ```
 
-## Authorization
+## Request Authentication
 
 Once the user is logged in, you can make authenticated requests to back-end APIs by getting the access token and attaching it to your request:
 
@@ -810,3 +839,6 @@ Note: If a group name contains a space, then that space should be replaced with
 ```javascript
 super_administrator || engineer
 ```
+
+[Express-Stormpath]: https://github.com/stormpath/express-stormpath
+[Stormpath Client API]: https://docs.stormpath.com/client-api/product-guide/latest/index.html

src/app.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'events';
 import { LocalStorage } from './storage';
-import { UserService, ClientApiUserService} from './services';
+import { StormpathCookieUserService, OAuthTokenUserService} from './services';
 import { UserConstants, TokenConstants } from './constants';
 import { UserStore, SessionStore, TokenStore } from './stores';
 import { FluxDispatcher, ReduxDispatcher } from './dispatchers';
@@ -41,14 +41,14 @@ class App extends EventEmitter {
 
     let baseUri = options.endpoints.baseUri;
 
-    if (baseUri && !utils.isSameHost(baseUri, window.location.href)) {
+    if (options.tokenStrategy === 'cookie') {
+      userService = new StormpathCookieUserService(options.endpoints);
+    } else {
       tokenStore = new TokenStore(options.storage, 'stormpath:token');
-      userService = new ClientApiUserService(options.endpoints);
+      userService = new OAuthTokenUserService(options.endpoints);
 
       userService.setToken('access_token', tokenStore.get('access_token'));
       userService.setToken('refresh_token', tokenStore.get('refresh_token'));
-    } else {
-      userService = new UserService(options.endpoints);
     }
 
     let userStore = new UserStore(userService, sessionStore);

src/services/index.js

@@ -1,4 +1,4 @@
 export BaseService from './BaseService';
 export RequestPool from './RequestPool';
-export UserService from './UserService';
-export ClientApiUserService from './ClientApiUserService';
+export StormpathCookieUserService from './stormpath-cookie-user-service';
+export OAuthTokenUserService from './oauth-token-user-service';

src/services/ClientApiUserService.js → src/services/oauth-token-user-service.js

@@ -1,9 +1,9 @@
 import utils from '../utils';
-import UserService from './UserService';
+import StormpathCookieUserService from './stormpath-cookie-user-service';
 import TokenActions from '../actions/TokenActions';
 import context from '../context';
 
-export default class ClientApiUserService extends UserService {
+export default class OAuthTokenUserService extends StormpathCookieUserService {
   tokens = {
     access_token: null,
     refresh_token: null

src/services/UserService.js → src/services/stormpath-cookie-user-service.js

@@ -2,7 +2,7 @@ import utils from '../utils';
 import BaseService from './BaseService';
 import RequestPool from './RequestPool';
 
-export default class UserService extends BaseService {
+export default class StormpathCookieUserService extends BaseService {
   constructor(endpoints, forceAgentHeader) {
     let defaultEndpoints = {
       me: '/me',