add code annotations

Author: derisen

6-AdvancedScenarios/3-call-api-acrs/API/app.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
 const express = require('express');
 const session = require('express-session');
 const methodOverride = require('method-override');
@@ -30,7 +35,7 @@ app.use(express.json());
 
 /**
  * We need to enable CORS for client's domain in order to
- * expose www-authenticate header in response from web API
+ * expose www-authenticate header in response from the web API
  */
 app.use(cors({
     origin: process.env.CORS_ALLOWED_DOMAINS, // replace with client domain

6-AdvancedScenarios/3-call-api-acrs/API/controllers/adminController.js

@@ -57,24 +57,23 @@ exports.postDashboardPage = async(req, res, next) => {
         // check if acrs is empty   
         if (acrs.value.length === 0) {
 
-            // create 
             defaultAcrsList = [
                 {
                     id: 'c1',
                     displayName: 'Require strong authentication',
-                    description: 'Require strong authentication',
+                    description: 'User needs to perform multifactor authentication',
                     isAvailable: true
                 },
                 {
                     id: 'c2',
                     displayName: 'Require compliant devices',
-                    description: 'Require compliant devices',
+                    description: 'Users needs to prove using a compliant device',
                     isAvailable: true
                 },
                 {
                     id: 'c3',
                     displayName: 'Require trusted locations',
-                    description: 'Require trusted locations',
+                    description: 'User needs to prove connecting from a trusted location',
                     isAvailable: true
                 },
             ]

6-AdvancedScenarios/3-call-api-acrs/API/routes/adminRoutes.js

@@ -14,6 +14,7 @@ module.exports = (authProvider) => {
     router.get('/signin', authProvider.signIn({ successRedirect: '/admin' }));
     router.get('/signout', authProvider.signOut({ successRedirect: '/admin' }));
 
+    // check if user is authenticated, then obtain an access token for the specified resource
     router.get(
         '/dashboard',
         authProvider.isAuthenticated(),

6-AdvancedScenarios/3-call-api-acrs/API/utils/claimsManager.js

@@ -1,5 +1,7 @@
-const authConfig = require('../.env');
-
+/**
+ * This custom middleware inspects the incoming request for client capabilities and auth context
+ * @param {string} authContextId
+ */
 const checkForRequiredAuthContext = (req, res, next, authContextId) => {
     if (!req.authInfo['acrs'] || !req.authInfo['acrs'].includes(authContextId)) {
         if (isClientCapableOfClaimsChallenge(req.authInfo)) {
@@ -18,6 +20,11 @@ const checkForRequiredAuthContext = (req, res, next, authContextId) => {
     }
 }
 
+/**
+ * xms_cc claim in the access token indicates that the client app of user is capable of
+ * handling claims challenges. See for more: https://docs.microsoft.com/en-us/azure/active-directory/develop/claims-challenge#client-capabilities
+ * @param {Object} accessTokenClaims: 
+ */
 const isClientCapableOfClaimsChallenge = (accessTokenClaims) => {
     if (accessTokenClaims['xms_cc'] && accessTokenClaims['xms_cc'].includes('CP1')) {
         return true;
@@ -26,13 +33,19 @@ const isClientCapableOfClaimsChallenge = (accessTokenClaims) => {
     return false;
 }
 
+/**
+ * Generates www-authenticate header and claims challenge for a given authentication context id. For more information, see: 
+ * https://docs.microsoft.com/en-us/azure/active-directory/develop/claims-challenge#claims-challenge-header-format
+ */
 const generateClaimsChallenge = (authContextId) => {
     const clientId = process.env.CLIENT_ID;
 
     const statusCode = 401;
 
+    // claims challenge object
     const challenge = { access_token: { acrs: { essential: true, value: authContextId }}};
 
+    // base64 encode the challenge object
     const base64str = Buffer.from(JSON.stringify(challenge)).toString('base64');
     const headers = ["www-authenticate", "Bearer realm=\"\", authorization_uri=\"https://login.microsoftonline.com/common/oauth2/v2.0/authorize\", client_id=\"" + clientId + "\", error=\"insufficient_claims\", claims=\"" + base64str + "\", cc_type=\"authcontext\""];
     const message = "The presented access tokens had insufficient claims. Please request for claims designated in the www-authentication header and try again.";

6-AdvancedScenarios/3-call-api-acrs/API/utils/routeGuard.js

@@ -4,16 +4,18 @@ const AuthContext = require('../models/authContext');
 const authContextGuard = (req, res, next) => {
     const acrs = AuthContext.getAuthContexts();
 
+    // if there is no auth context in the db, let the request through
     if (acrs.length === 0) {
         return next();
     } else {
         const authContext = acrs.find(ac => ac.operation === req.method && ac.tenantId === req.authInfo.tid); 
 
         if (authContext) {
+            // if found, check the request for the required claims
             return checkForRequiredAuthContext(req, res, next, authContext.authContextId);
         }
 
-        return next();
+        next();
     }
 }
 

6-AdvancedScenarios/3-call-api-acrs/SPA/src/authConfig.js

@@ -1,8 +1,3 @@
-/*
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
 import { LogLevel } from "@azure/msal-browser";
 
 /**

6-AdvancedScenarios/3-call-api-acrs/SPA/src/fetch.js

@@ -1,8 +1,3 @@
-/*
- * Copyright (c) Microsoft Corporation. All rights reserved.
- * Licensed under the MIT License.
- */
-
 import { BrowserAuthError } from "@azure/msal-browser";
 import { protectedResources } from "./authConfig";
 import { msalInstance } from "./index";
@@ -22,6 +17,13 @@ const getToken = async () => {
     return response.accessToken;
 }
 
+/**
+ * This method inspects the HTTP response from a fetch call for the "www-authenticate header"
+ * If present, it grabs the claims challenge from the header, then uses msal to ask Azure AD for a new access token containing the needed claims
+ * If not present, then it simply returns the response as json
+ * For more information, visit: https://docs.microsoft.com/en-us/azure/active-directory/develop/claims-challenge#claims-challenge-header-format
+ * @param {Object} response: HTTP response
+ */
 const handleClaimsChallenge = async (response) => {
     if (response.status === 401) {
         if (response.headers.get('www-authenticate')) {
@@ -32,7 +34,7 @@ const handleClaimsChallenge = async (response) => {
 
             try {
                 await msalInstance.acquireTokenPopup({
-                    claims: window.atob(claimsChallenge),
+                    claims: window.atob(claimsChallenge), // decode the base64 string
                     scopes: protectedResources.apiTodoList.scopes
                 });
             } catch (error) {

6-AdvancedScenarios/3-call-api-acrs/SPA/src/index.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
 import React from "react";
 import ReactDOM from "react-dom";