ibm-cloud-security
diff --git a/‎README.md‎
Lines changed: 41 additions & 2 deletions b/‎README.md‎
Lines changed: 41 additions & 2 deletions
diff --git a/‎lib/strategies/api-strategy.js‎
Lines changed: 125 additions & 99 deletions b/‎lib/strategies/api-strategy.js‎
Lines changed: 125 additions & 99 deletions
diff --git a/‎lib/strategies/webapp-strategy.js‎
Lines changed: 32 additions & 0 deletions b/‎lib/strategies/webapp-strategy.js‎
Lines changed: 32 additions & 0 deletions
@@ -109,7 +109,24 @@ app.listen(port, function(){
 });
 
 ```
-
+<!---
+##### Protecting APIs using the APIStrategy: Access Control
+Using access control, you can define the scopes that are required to access a specific endpoint.
+```JavaScript
+app.get("/api/protected",
+	passport.authenticate(APIStrategy.STRATEGY_NAME, {
+		audience: "myApp",
+		scope: "read write update"
+	}),
+	function(req, res) {
+		res.send("Hello from protected resource");
+	}
+);
+```
+The scope parameter defines the required scopes. 
+The audience parameter is optional and should be set to the application clientId
+to guarantee the scopes are for the requested application. 
+-->
 #### Protecting web applications using WebAppStrategy
 WebAppStrategy is based on the OAuth2 authorization_code grant flow and should be used for web applications that use browsers. The strategy provides tools to easily implement authentication and authorization flows. When WebAppStrategy provides mechanisms to detect unauthenticated attempts to access protected resources. The WebAppStrategy will automatically redirect user's browser to the authentication page. After successful authentication user will be taken back to the web application's callback URL (redirectUri), which will once again use WebAppStrategy to obtain access, identity and refresh tokens from App ID service. After obtaining these tokens the WebAppStrategy will store them in HTTP session under WebAppStrategy.AUTH_CONTEXT key. In a scalable cloud environment it is recommended to persist HTTP sessions in a scalable storage like Redis to ensure they're available across server app instances.
 
@@ -207,7 +224,21 @@ app.get("/protected", passport.authenticate(WebAppStrategy.STRATEGY_NAME), funct
 // Start the server!
 app.listen(process.env.PORT || 1234);
 ```
-
+<!---
+##### Protecting web applications using WebAppStrategy: Access Control
+Using access control, you can check which scopes exist on the request.
+```JavaScript
+app.get("/protected", passport.authenticate(WebAppStrategy.STRATEGY_NAME), function(req, res){
+    if(WeAppStrategy.hasScope(req, "read write")){
+      	res.json(req.user);
+    }
+    else {
+        res.send("insufficient scopes!");
+    }
+});
+```
+Use WebAppStrategy's hasScope method to check if a given request has some specific scopes.
+-->
 #### Anonymous login
 WebAppStrategy allows users to login to your web application anonymously, meaning without requiring any credentials. After successful login the anonymous user access token will be persisted in HTTP session, making it available as long as HTTP session is kept alive. Once HTTP session is destroyed or expired the anonymous user access token will be destroyed as well.  
 
@@ -554,6 +585,14 @@ selfServiceManager.updateUserDetails(uuid, userData, iamToken).then(function (us
 	}
 ```
 
+### Logging
+This SDK uses the log4js package for logging. By default the logging level is set to `info`. To create your own logging configuration for your application, add a log4js.json file and set the `process.env.LOG4JS_CONFIG` environment variable to your json file.
+
+To learn more about log4js, visit the documentation here (https://log4js-node.github.io/log4js-node/).
+
+## Got Questions?
+Join us on [Slack](https://www.ibm.com/cloud/blog/announcements/get-help-with-ibm-cloud-app-id-related-questions-on-slack) and chat with our dev team.
+
 
 ### Logging
 This SDK uses the log4js package for logging. By default the logging level is set to `info`. To create your own logging configuration for your application, add a log4js.json file and set the `process.env.LOG4JS_CONFIG` environment variable to your json file.
 
@@ -18,9 +18,9 @@ const ServiceUtil = require('../utils/service-util');
 const PublicKeyUtil = require("../utils/public-key-util");
 
 const ERROR = {
-	INVALID_REQUEST: "invalid_request", // HTTP 400
-	INVALID_TOKEN: "invalid_token", // HTTP 401
-	INSUFFICIENT_SCOPE: "insufficient_scope" // HTTP 401
+  INVALID_REQUEST: "invalid_request", // HTTP 400
+  INVALID_TOKEN: "invalid_token", // HTTP 401
+  INSUFFICIENT_SCOPE: "insufficient_scope" // HTTP 401
 };
 
 const AUTHORIZATION_HEADER = "Authorization";
@@ -30,119 +30,145 @@ const BEARER = "Bearer";
 const logger = log4js.getLogger(STRATEGY_NAME);
 
 function ApiStrategy(options) {
-	logger.debug("Initializing");
-	options = options || {};
-	this.name = ApiStrategy.STRATEGY_NAME;
-	this.serviceConfig = new ServiceUtil.loadConfig('APIStrategy', [constants.OAUTH_SERVER_URL], options);
+  logger.debug("Initializing");
+  options = options || {};
+  this.name = ApiStrategy.STRATEGY_NAME;
+  this.serviceConfig = new ServiceUtil.loadConfig('APIStrategy', [constants.OAUTH_SERVER_URL], options);
 }
 
 ApiStrategy.STRATEGY_NAME = STRATEGY_NAME;
 ApiStrategy.DEFAULT_SCOPE = "appid_default";
 
-ApiStrategy.prototype.authenticate = function (req, options={}) {
-	var self = this;
-	logger.debug("authenticate");
-
-	var requiredScope = ApiStrategy.DEFAULT_SCOPE;
-	if (options.scope) {
-		requiredScope += " " + options.scope;
+/**
+ *
+ * @param req - an HTTP request object
+ * @param options.scope - The required scopes, separated by spaces. For example: 'read write update'
+ * @param options.audience - (optional) the application clientId, or the resource URI.
+ * @returns {*}
+ */
+ApiStrategy.prototype.authenticate = function (req, options = {}) {
+  var self = this;
+  logger.debug("authenticate");
+  
+  if (options.scope && typeof options.scope !== 'string' || options.audience && typeof options.audience !== 'string') {
+    return self.fail(buildWwwAuthenticateHeader('Illegal Scope', ERROR.INVALID_REQUEST), 400);
+  }
+  
+  let requiredScopes = ApiStrategy.DEFAULT_SCOPE;
+  if (options.scope && options.scope.trim()) { // if the required scopes are just whitespace, skip.
+    // split by spaces and keep only non empty scopes. excluded default scope as it is always there
+	const scopesArray = options.scope.split(" ").filter(scope => scope !== '' && scope !== ApiStrategy.DEFAULT_SCOPE);
+    for (const requiredScope of scopesArray) {
+	  requiredScopes += " " +  requiredScope;
 	}
-
-	// Retrieve authorization header from request
-	var authHeader = req.header(AUTHORIZATION_HEADER);
-	if (!authHeader) {
-		logger.warn("Authorization header not found");
-		return self.fail(buildWwwAuthenticateHeader(requiredScope, ERROR.INVALID_TOKEN), 401);
+  }
+  
+  // Retrieve authorization header from request
+  const authHeader = req.header(AUTHORIZATION_HEADER);
+  if (!authHeader) {
+	logger.warn("Authorization header not found");
+	return self.fail(buildWwwAuthenticateHeader(requiredScopes, ERROR.INVALID_TOKEN), 401);
+  }
+  
+  // Validate that first header component is Bearer
+  const authHeaderComponents = authHeader.split(" ");
+  if (authHeaderComponents[0].indexOf(BEARER) !== 0) {
+	logger.warn("Malformed authorization header");
+	return self.fail(buildWwwAuthenticateHeader(requiredScopes, ERROR.INVALID_TOKEN), 401);
+  }
+  
+  // Validate header has exactly 2 or 3 components (Bearer, access_token, [id_token])
+  if (authHeaderComponents.length !== 2 && authHeaderComponents.length !== 3) {
+	logger.warn("Malformed authorization header");
+	return self.fail(buildWwwAuthenticateHeader(requiredScopes, ERROR.INVALID_TOKEN), 401);
+  }
+  
+  // Validate second header component is a valid access_token
+  var accessTokenString = authHeaderComponents[1];
+  
+  // Decode and validate access_token
+  TokenUtil.decodeAndValidate(accessTokenString, this.serviceConfig.getOAuthServerUrl()).then(function (accessToken) {
+	if (!accessToken) {
+	  logger.warn("Invalid access_token");
+	  return self.fail(buildWwwAuthenticateHeader(requiredScopes, ERROR.INVALID_TOKEN), 401);
 	}
-
-	// Validate that first header component is Bearer
-	var authHeaderComponents = authHeader.split(" ");
-	if (authHeaderComponents[0].indexOf(BEARER) !== 0) {
-		logger.warn("Malformed authorization header");
-		return self.fail(buildWwwAuthenticateHeader(requiredScope, ERROR.INVALID_TOKEN), 401);
+	// Validate token contains required scopes
+	const requiredScopesArray = requiredScopes.split(" ").filter(scope => scope !== "");
+	const suppliedScopesArray = accessToken.scope.split(" ");
+	for (const requiredScope of requiredScopesArray) {
+	  if (!suppliedScopesArray.includes(requiredScope)) {
+		logger.warn("access_token does not contain required scope. Expected ::", requiredScopes, " Received ::",
+		  accessToken.scope);
+		return self.fail(buildWwwAuthenticateHeader(requiredScopes, ERROR.INSUFFICIENT_SCOPE), 401);
+	  }
 	}
 
-	// Validate header has exactly 2 or 3 components (Bearer, access_token, [id_token])
-	if (authHeaderComponents.length !== 2 && authHeaderComponents.length !== 3) {
-		logger.warn("Malformed authorization header");
-		return self.fail(buildWwwAuthenticateHeader(requiredScope, ERROR.INVALID_TOKEN), 401);
+	// validate the audience section
+	if (!accessToken.aud) {
+		return self.fail(buildWwwAuthenticateHeader("access token missing audience section", ERROR.INVALID_TOKEN), 401);
 	}
-
-	// Validate second header component is a valid access_token
-	var accessTokenString = authHeaderComponents[1];
-
-	// Decode and validate access_token
-	TokenUtil.decodeAndValidate(accessTokenString, this.serviceConfig.getOAuthServerUrl()).then(function (accessToken) {
-		if (!accessToken) {
-			logger.warn("Invalid access_token");
-			return self.fail(buildWwwAuthenticateHeader(requiredScope, ERROR.INVALID_TOKEN), 401);
+	if (!Array.isArray(accessToken.aud)) {
+		return self.fail(buildWwwAuthenticateHeader("access token malformed audience array", ERROR.INVALID_TOKEN), 401);
+	}
+	if (options.audience && options.audience.trim()) {
+		// audience is an array (currently we support only 1 item in the array)
+		const requestAudience = options.audience.trim();
+		const requiredList = requestAudience.split(' ');
+		if (requiredList.length > 1) {
+			return self.fail(buildWwwAuthenticateHeader("multiple audiences are not supported", ERROR.INVALID_REQUEST), 400);
 		}
-
-		// Validate token contains required scopes
-		var requiredScopeElements = requiredScope.split(" ");
-		var suppliedScopeElements = accessToken.scope.split(" ");
-		for (var i = 0; i < requiredScopeElements.length; i++) {
-			var requiredScopeElement = requiredScopeElements[i];
-			var found = false;
-			for (var j = 0; j < suppliedScopeElements.length; j++) {
-				var suppliedScopeElement = suppliedScopeElements[j];
-				if (requiredScopeElement === suppliedScopeElement) {
-					found = true;
-					break;
-				}
-			}
-			if (!found) {
-				logger.warn("access_token does not contain required scope. Expected ::", requiredScope, " Received ::",
-					accessToken.scope);
-				return self.fail(buildWwwAuthenticateHeader(requiredScope, ERROR.INSUFFICIENT_SCOPE), 401);
-			}
+		const tokenAudience = accessToken.aud;
+		if (!tokenAudience.includes(requestAudience)) {
+			return self.fail(buildWwwAuthenticateHeader("audience mismatch. expected:" + tokenAudience +
+			  " got:" + requestAudience, ERROR.INSUFFICIENT_SCOPE), 401);
 		}
-
-		req.appIdAuthorizationContext = {
-			accessToken: accessTokenString,
-			accessTokenPayload: accessToken
-		};
-
-		// Decode and validate id_token
-		var identityTokenString;
-		var identityToken;
-		if (authHeaderComponents.length === 3) {
-			identityTokenString = authHeaderComponents[2];
-			TokenUtil.decodeAndValidate(identityTokenString, self.serviceConfig.getOAuthServerUrl()).then(function (identityToken) {
-				if (identityToken) {
-					req.appIdAuthorizationContext.identityToken = identityTokenString;
-					req.appIdAuthorizationContext.identityTokenPayload = identityToken;
-				} else {
-					logger.warn("Invalid identity_token. Proceeding with access_token only");
-				}
-				logger.debug("authentication success");
-				return self.success(identityToken || null);
-			}).catch(() => {
-				logger.debug("authentication failed due to invalid identity token");
-				return self.fail(buildWwwAuthenticateHeader(requiredScope, ERROR.INVALID_TOKEN), 401);
-			});
+	}
+	
+	req.appIdAuthorizationContext = {
+	  accessToken: accessTokenString,
+	  accessTokenPayload: accessToken
+	};
+	
+	// Decode and validate id_token
+	var identityTokenString;
+	var identityToken;
+	if (authHeaderComponents.length === 3) {
+	  identityTokenString = authHeaderComponents[2];
+	  TokenUtil.decodeAndValidate(identityTokenString, self.serviceConfig.getOAuthServerUrl()).then(function (identityToken) {
+		if (identityToken) {
+		  req.appIdAuthorizationContext.identityToken = identityTokenString;
+		  req.appIdAuthorizationContext.identityTokenPayload = identityToken;
 		} else {
-			logger.debug("authentication success: identity_token not found. Proceeding with access_token only");
-			return self.success(identityToken || null);
+		  logger.warn("Invalid identity_token. Proceeding with access_token only");
 		}
-	}).catch(function () {
-		logger.debug("authentication failed due to invalid access token");
-		return self.fail(buildWwwAuthenticateHeader(requiredScope, ERROR.INVALID_TOKEN), 401);
-	});
-
-	// .success(user, info) - call on auth success. user=object, info=object
-	// .fail(challenge, status) - call on auth failure. challenge=string, status=int
-	// .redirect(url, status) - call on redirect required. url=url, status=int
-	// .pass() - skip strategy processing
-	// .error(err) - error during strategy processing. err=Error obj
+		logger.debug("authentication success");
+		return self.success(identityToken || null);
+	  }).catch(() => {
+		logger.debug("authentication failed due to invalid identity token");
+		return self.fail(buildWwwAuthenticateHeader(requiredScopes, ERROR.INVALID_TOKEN), 401);
+	  });
+	} else {
+	  logger.debug("authentication success: identity_token not found. Proceeding with access_token only");
+	  return self.success(identityToken || null);
+	}
+  }).catch(function () {
+	logger.debug("authentication failed due to invalid access token");
+	return self.fail(buildWwwAuthenticateHeader(requiredScopes, ERROR.INVALID_TOKEN), 401);
+  });
+  
+  // .success(user, info) - call on auth success. user=object, info=object
+  // .fail(challenge, status) - call on auth failure. challenge=string, status=int
+  // .redirect(url, status) - call on redirect required. url=url, status=int
+  // .pass() - skip strategy processing
+  // .error(err) - error during strategy processing. err=Error obj
 };
 
 function buildWwwAuthenticateHeader(scope, error) {
-	var msg = BEARER + " scope=\"" + scope + "\"";
-	if (error) {
-		msg += ", error=\"" + error + "\"";
-	}
-	return msg;
+  var msg = BEARER + " scope=\"" + scope + "\"";
+  if (error) {
+	msg += ", error=\"" + error + "\"";
+  }
+  return msg;
 }
 
 module.exports = ApiStrategy;
@@ -551,4 +551,36 @@ WebAppStrategy.prototype.logoutSSO = function (req, res, options = {}) {
 	res.redirect(url);
 };
 
+/**
+ * Returns true if the token on the request's session has the required scopes.
+ * @param req: The request containing the App ID token.
+ * @param requiredScopes {String}: Scope names (not fullName) separated by spaces. For example: 'write read update'.
+ * @returns {boolean}
+ */
+WebAppStrategy.hasScope = function (req, requiredScopes) {
+  if (typeof requiredScopes !== 'string' || !requiredScopes.trim()) {
+    logger.error('requiredScopes is either empty or not a string');
+    return true;
+  }
+  if (!req || !req.session || !req.session[WebAppStrategy.AUTH_CONTEXT] ||
+    !req.session[WebAppStrategy.AUTH_CONTEXT].accessTokenPayload ||
+    typeof req.session[WebAppStrategy.AUTH_CONTEXT].accessTokenPayload.scope !== 'string') {
+    logger.warn('access token scope could not be found on request\'s session');
+    return false;
+  }
+  
+  const suppliedScopes = req.session[WebAppStrategy.AUTH_CONTEXT].accessTokenPayload.scope;
+  // get the required scopes as an array
+  const requiredScopesArray = requiredScopes.split(" ").filter(scope => scope !== ""); // split by spaces and ignore empty required scopes
+  // get the supplied scopes as an array while removing the prefix (app URI) since the required scopes aren't prefixed:
+  const suppliedScopesArray = suppliedScopes.split(" ").map(fullScope => fullScope.split("/").pop());
+  
+  for (const requiredScope of requiredScopesArray) {
+	if (!suppliedScopesArray.includes(requiredScope)) {
+	  return false;
+	}
+  }
+  return true;
+};
+
 module.exports = WebAppStrategy;