Merge pull request #231 from Adam-Auth0/master

Add rule templates for multifactor stepup authenticaiton & adding email address to access token.

rules.json

@@ -22,6 +22,16 @@
         "description": "<p>This rule checks if a user belongs to an AD group and if not, it will return Access Denied.</p>\n<blockquote>\n  <p>Note: you can mix this with <code>context.clientID</code> or <code>clientName</code> to do it only for specific application</p>\n</blockquote>",
         "code": "function activeDirectoryGroups(user, context, callback) {\n  var groupAllowed = 'group1';\n  if (user.groups) {\n    var userHasAccess = user.groups.some(\n      function (group) {\n        return groupAllowed === group;\n      });\n\n    if (!userHasAccess) {\n      return callback(new UnauthorizedError('Access denied.'));\n    }\n  }\n\n  callback(null, user, context);\n}"
       },
+      {
+        "id": "add-email-to-access-token",
+        "title": "Add email to access token",
+        "overview": "Add the authenticated user's email address to the access token.",
+        "categories": [
+          "access control"
+        ],
+        "description": "<p>This rule will add the authenticated user's <code>email</code> attribute value to the access token.</p>",
+        "code": "function (user, context, callback) {\n  // This rule adds the authenticated user's email address to the access token.\n\n  var namespace = 'https://example.com/';\n\n  context.accessToken[namespace + 'email'] = user.email;\n  return callback(null, user, context);\n}"
+      },
       {
         "id": "check-domains-against-connection-aliases",
         "title": "Check if user email domain matches configured domain",
@@ -500,6 +510,16 @@
         "description": "<p>This rule is used to trigger multifactor authentication when the requesting IP is from outside the corporate IP range.</p>",
         "code": "function guardianMultifactorIpRange(user, context, callback) {\n  const ipaddr = require('ipaddr.js');\n  const corp_network = \"192.168.1.134/26\";\n  const current_ip = ipaddr.parse(context.request.ip);\n\n  if (!current_ip.match(ipaddr.parseCIDR(corp_network))) {\n    context.multifactor = {\n      provider: 'guardian',\n\n      // optional, defaults to true. Set to false to force Guardian authentication every time.\n      // See https://auth0.com/docs/multifactor-authentication/custom#change-the-frequency-of-authentication-requests for details\n      allowRememberBrowser: false\n    };\n  }\n\n  callback(null, user, context);\n}"
       },
+      {
+        "id": "guardian-multifactor-stepup-authentication",
+        "title": "Multifactor Stepup Authentication",
+        "overview": "Used to challenge for a second factor when requested by sending acr_values.",
+        "categories": [
+          "multifactor"
+        ],
+        "description": "<p>This rule will challenge for a second authentication factor on request (step up) when\nacr_values = 'http://schemas.openid.net/pape/policies/2007/06/multi-factor' is sent in\nthe request. Before the challenge is made, 'context.authentication.methods' is checked\nto determine when the user has already successfully completed a challenge in the\ncurrent session.</p>",
+        "code": "function (user, context, callback) {\n\n  // This rule initiates multi-factor authenticaiton as a second factor\n  // whenever the request contains the following value:\n  // \n  // acr_values = 'http://schemas.openid.net/pape/policies/2007/06/multi-factor'\n  // \n  // and multi-factor authentication has not already been completed in the\n  // current session/\n  \n  if (context.request.query.acr_values === 'http://schemas.openid.net/pape/policies/2007/06/multi-factor' && !context.authentication.methods.some(method => method.name === 'mfa')) {\n  \n  \tcontext.multifactor = {\n        provider: 'any',\n        allowRememberBrowser: false,\n      };\n    }\n\n  callback(null, user, context);\n}"
+      },
       {
         "id": "guardian-multifactor",
         "title": "Multifactor with Auth0 Guardian",

src/rules/add-email-to-access-token.js

@@ -0,0 +1,19 @@
+/**
+ * @title Add email to access token
+ * @overview Add the authenticated user's email address to the access token.
+ * @gallery true
+ * @category access control
+ *
+ * This rule will add the authenticated user's `email` attribute value to the access token.
+ *
+ *
+ */
+
+function (user, context, callback) {
+  // This rule adds the authenticated user's email address to the access token.
+
+  var namespace = 'https://example.com/';
+
+  context.accessToken[namespace + 'email'] = user.email;
+  return callback(null, user, context);
+}

src/rules/guardian-multifactor-stepup-authentication.js

@@ -0,0 +1,34 @@
+/**
+ * @title Multifactor Stepup Authentication
+ * @overview Used to challenge for a second factor when requested by sending acr_values.
+ * @gallery true
+ * @category multifactor
+ *
+ * This rule will challenge for a second authentication factor on request (step up) when
+ * acr_values = 'http://schemas.openid.net/pape/policies/2007/06/multi-factor' is sent in
+ * the request. Before the challenge is made, 'context.authentication.methods' is checked
+ * to determine when the user has already successfully completed a challenge in the
+ * current session.
+ *
+ */
+
+function (user, context, callback) {
+
+  // This rule initiates multi-factor authenticaiton as a second factor
+  // whenever the request contains the following value:
+  // 
+  // acr_values = 'http://schemas.openid.net/pape/policies/2007/06/multi-factor'
+  // 
+  // and multi-factor authentication has not already been completed in the
+  // current session/
+
+  if (context.request.query.acr_values === 'http://schemas.openid.net/pape/policies/2007/06/multi-factor' && !context.authentication.methods.some(method => method.name === 'mfa')) {
+
+  	context.multifactor = {
+        provider: 'any',
+        allowRememberBrowser: false,
+      };
+    }
+
+  callback(null, user, context);
+}

test/rules/add-email-to-access-token.test.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const loadRule = require('../utils/load-rule');
+const ContextBuilder = require('../utils/contextBuilder');
+const UserBuilder = require('../utils/userBuilder')
+
+const ruleName = 'add-email-to-access-token';
+
+describe(ruleName, () => {
+  let user;
+  let context;
+  let rule;
+
+  beforeEach(() => {
+    rule = loadRule(ruleName);
+
+    user = new UserBuilder().build();
+    context = new ContextBuilder().build();
+  });
+
+  it('should add email to outgoing accessToken', (done) => {
+    const namespace = 'https://example.com/';
+    rule(user, context, (err, u, c) => {
+      expect(c.accessToken[namespace + 'email']).toBe(user.email);
+
+      done();
+    });
+  });
+});

test/rules/guardian-multifactor-stepup-authentication.test.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const loadRule = require('../utils/load-rule');
+const ContextBuilder = require('../utils/contextBuilder');
+const RequestBuilder = require('../utils/requestBuilder');
+
+const ruleName = 'guardian-multifactor-ip-range';
+
+describe(ruleName, () => {
+  let user;
+  let context;
+  let rule;
+
+  beforeEach(() => {
+    rule = loadRule(ruleName);
+  });
+
+  describe('should set multifactor provider', () => {
+    beforeEach(() => {
+      const request = new RequestBuilder().build();
+      context = new ContextBuilder()
+        .withRequest(request)
+        .build();
+    });
+
+    it('if request contains acr_vales="http://schemas.openid.net/pape/policies/2007/06/multi-factor" and the context.authentication.methods array contains an element for name="mfa"', (done) => {
+      rule(user, context, (err, u, c) => {
+        expect(c.multifactor.provider).toBe('guardian');
+        expect(c.multifactor.allowRememberBrowser).toBe(false);
+
+        done();
+      });
+    });
+  });
+
+  describe('should do nothing', () => {
+    beforeEach(() => {
+      const request = new RequestBuilder().build();
+      request.ip = '192.168.1.135';
+      context = new ContextBuilder()
+        .withRequest(request)
+        .build();
+    });
+
+    it('if acr_values is not in request or if it is present, but not set to "http://schemas.openid.net/pape/policies/2007/06/multi-factor" or the context.authentication.methods array does not contain an element for name="mfa"', (done) => {
+      rule(user, context, (err, u, c) => {
+        expect(c.multifactor).toBeFalsy();
+
+        done();
+      });
+    });
+  });
+});