Remove custom metadata and URI parameters in favour of referencing this data from the 'state' URI parameter

Author: MrSwitch

README.md

@@ -118,19 +118,26 @@ oauthshim.getCredentials = function(id,callback){
 
 ## Authentication API
 
+The API adopts similar URL format as the standard OAuth2. Additional metadata about how to handle the request is communicated through the `state` parameter as a JSON string.
+
 ### Authentication OAuth 2.0
 
-The OAuth2 flow for the shim starts after a web application sends a client out to a providers site to grant permissions. The response is an authorization code "[AUTH_CODE]" which is returned to your site, this needs to be exchanged for an Access Token. Your page then needs to send this code to an //auth-server with your client_id in exhchange for an access token, e.g.
+[STATE] includes:
+
+||key||value||
+|oauth.version|2|
+|oauth.grant|[PROVIDERS_OAUTH2_GRANT_URL]|
+
+
+The OAuth2 flow for the shim starts after a web application sends a client out to a providers site to grant permissions. The response is an authorization code "[AUTH_CODE]" which is returned to your site, this needs to be exchanged for an Access Token. Your page then needs to send this code to an //auth-server to be exhchanged for an access token, e.g.
 
 
 	?redirect_uri=[REDIRECT_PATH]
 	&code=[AUTH_CODE]
 	&client_id=[APP_KEY]
 	&state=[STATE]
-	&grant_url=[PROVIDERS_OAUTH2_GRANT_URL]
 
-
-The client will be redirected back to the location of [REDIRECT_PATH], with the contents of the server response as well as whatever was defined in the [STATE] in the hash. e.g...
+The //auth-server exchanges the Authorization code for an access_token and redirects the client back to the location of [REDIRECT_PATH], with the contents of the server response as well as whatever was defined in the [STATE] in the hash. e.g...
 
 
 	[REDIRECT_PATH]#state=[STATE]&access_token=ABCD1233234&expires=123123123
@@ -139,18 +146,24 @@ The client will be redirected back to the location of [REDIRECT_PATH], with the
 
 ### Authentication OAuth 1.0 & 1.0a
 
+[STATE] includes:
+
+||key||value||
+|oauth.version|1.0a|
+|oauth.request|[OAUTH_REQUEST_TOKEN_URL]|
+|oauth.auth|[OAUTH_AUTHORIZATION_URL]|
+|oauth.token|[OAUTH_TOKEN_URL]|
+|oauth_proxy|//auth-server|
+
 OAuth 1.0 has a number of steps so forgive the verbosity here. An app is required to make an initial request to the //auth-server, which in-turn initiates the authentication flow.
 
 
-	?redirect_uri=[REDIRECT_PATH]
+	//auth-server?redirect_uri=[REDIRECT_PATH]
 	&client_id=[APP_KEY]
-	&request_url=[OAUTH_REQUEST_TOKEN_URL]
-	&auth_url=[OAUTH_AUTHORIZATION_URL]
-	&token_url=[OAUTH_TOKEN_URL]
 	&state=[STATE]
 
 
-The OAuthShim signs the client request and redirects the user to the providers login page defined by `[OAUTH_AUTHRIZATION_URL]`.
+The //auth-server signs the client request and redirects the user to the providers login page defined by `[OAUTH_AUTHRIZATION_URL]`.
 
 Once the user has signed in they are redirected back to a page on the developers app defined by `[REDIRECT_PATH]`. 
 
@@ -159,20 +172,17 @@ The provider should have included an oauth_callback parameter which was defined
 
 	[REDIRECT_PATH]
 	?state=[STATE]
-	&proxy_url=https://auth-server.herokuapp.com/proxy
 	&client_id=[APP_KEY]
-	&token_url=[OAUTH_TOKEN_URL]
 	&oauth_token=abc12465
 
 
 The page you defined locally as the `[REDIRECT_PATH]`, must then construct a call to //auth-server to exchange the unauthorized oauth_token for an access token. This would look like this...
 
 
-	?oauth_token=abc12465
+	//auth-server?oauth_token=abc12465
 	&redirect_uri=[REDIRECT_PATH]
 	&client_id=[APP_KEY]
 	&state=[STATE]
-	&token_url=[OAUTH_TOKEN_URL]
 
 
 Finally the //auth-server returns the access_token to your redirect path and its the responsibility of your script to store this in the client in order to make subsequent API calls.

src/oauth-shim.js

@@ -116,7 +116,7 @@ module.exports.interpret = function( req, res, next ){
 	//
 	// OAUTH1
 	//
-	else if( p.redirect_uri && ( ( p.oauth && parseInt(p.oauth.version,10) === 1 ) || p.token_url || p.oauth_token ) ) {
+	else if( p.redirect_uri && ( ( p.oauth && parseInt(p.oauth.version,10) === 1 ) || p.oauth_token ) ) {
 
 		p.location = url.parse("http"+(req.connection.encrypted?"s":'')+'://'+req.headers.host+req.url);
 

src/oauth1.js

@@ -55,13 +55,13 @@ module.exports = function(p, callback){
 	//
 	if(!p.oauth_token){
 
-		// Change the path to be that of the intiial handshake
-		path = (p.request_url || (p.oauth?p.oauth.request:null));
+		// Change the path to be that of the intitial handshake
+		path = p.oauth ? p.oauth.request : null;
 
 		if(!path){
 			return callback( p.redirect_uri, {
 				error : "required_request_url",
-				error_message : "A request_url is required",
+				error_message : "A state.oauth.request is required",
 				state : p.state || ''
 			});
 		}
@@ -73,9 +73,9 @@ module.exports = function(p, callback){
 
 		// Callback
 		var oauth_callback = p.redirect_uri + (p.redirect_uri.indexOf('?')>-1?'&':'?') + param({
+			// proxy_url: Deprecated as of HelloJS @ v1.7.1 - property included in `state`, accessed from `state` hence.
 			proxy_url : p.location.protocol + '//'+ p.location.host + p.location.pathname,
 			state     : p.state || '',
-			token_url : p.token_url || p.oauth.token,
 			client_id : p.client_id
 		}, function(r){
 			// Encode all the parameters
@@ -104,12 +104,12 @@ module.exports = function(p, callback){
 		//
 
 		// Change the path to be that of the Providers token exchange
-		path = p.token_url || (p.oauth?p.oauth.token:null);
+		path = p.oauth ? p.oauth.token : null;
 
 		if(!path){
 			return callback( p.redirect_uri, {
 				error : "required_token_url",
-				error_message : "A token_url is required to authenticate the oauth_token",
+				error_message : "A state.oauth.token url is required to authenticate the oauth_token",
 				state : p.state || ''
 			});
 		}
@@ -224,7 +224,7 @@ module.exports = function(p, callback){
 			}
 
 			// Great redirect the user to authenticate
-			var url = (p.auth_url||p.oauth.auth);
+			var url = p.oauth.auth;
 			callback( url + (url.indexOf('?')>-1?'&':'?') + param(params) );
 		}
 

src/oauth2.js

@@ -38,12 +38,12 @@ module.exports = function(p, callback){
 	}
 
 	// Get the grant_url
-	var grant_url = p.grant_url || p.grant || (p.oauth ? p.oauth.grant : false  );
+	var grant_url = p.oauth ? p.oauth.grant : false;
 
 	if(!grant_url){
 		return callback({
 			error : "required_grant",
-			error_message  : "Missing parameter grant_url",
+			error_message  : "Missing parameter state.oauth.grant url",
 			state : p.state || ''
 		});
 	}