add about the code section

Author: derisen

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

@@ -91,7 +91,7 @@ app.use(passport.initialize());
 
 passport.use(bearerStrategy);
 
-// protec api endpoints
+// protected api endpoints
 app.use('/api',
     passport.authenticate('oauth-bearer', { session: false }), // validate access tokens
     routeGuard, // check for auth context

6-AdvancedScenarios/3-call-api-acrs/README.md

@@ -287,26 +287,171 @@ Select the value and create the policy as required. For example, you might want
 
 ### Checking for client capabilities
 
+The client capabilities claim (`xms_cc`) indicate whether a client application can satisfy the claims challenge generated by a conditional access policy. To obtain this claim in an access token, we enable the `clientCapabilities` configuration option in [authConfig.js](./SPA/src/authConfig.js):
+
 ```javascript
+const msalConfig = {
+    auth: {
+        clientId: 'Enter_the_Application_Id_Here', 
+        authority: 'https://login.microsoftonline.com/Enter_the_Tenant_Info_Here',
+        redirectUri: "/", 
+        postLogoutRedirectUri: "/",
+        navigateToLoginRequestUrl: true, 
+        clientCapabilities: ["CP1"] // this lets the resource owner know that this client is capable of handling claims challenge.
+    }
+}
 
+const msalInstance = new PublicClientApplication(msalConfig);
 ```
 
 ### Checking for auth context
 
+In [app.js](./API/app.js), we add custom a `routeGuard` middleware to handle incoming requests web API's todolist endpoints:
+
+```javascript
+app.use('/api',
+    passport.authenticate('oauth-bearer', { session: false }), // validate access tokens
+    routeGuard, // check for auth context
+    todolistRoutes
+);
+```
+
+The `routeGuard` middleware checks the mock database for any auth context entries, and inspects the access token in the authorization header of the incoming request to see if it contains the necessary claims. If it does, it passes the request to the next middleware in chain. If it doesn't, the `checkForRequiredAuthContext` middleware takes over. This is shown in [routeGuard.js](./API/utils/routeGuard.js):
+
 ```javascript
+const authContextGuard = (req, res, next) => {
+    const acrs = AuthContext.getAuthContexts(); // get the current auth contexts from db
+
+    // 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);
+        }
 
+        next();
+    }
+}
 ```
 
-### Generating claims challenge
+In [claimsManager.js](./API/utils/claimsManager.js):
 
 ```javascript
+const checkForRequiredAuthContext = (req, res, next, authContextId) => {
+    if (!req.authInfo['acrs'] || !req.authInfo['acrs'].includes(authContextId)) {
+        if (isClientCapableOfClaimsChallenge(req.authInfo)) {
+            
+            const claimsChallenge = generateClaimsChallenge(authContextId);
+
+            return res.status(claimsChallenge.statusCode)
+                .set(claimsChallenge.headers[0], claimsChallenge.headers[1])
+                .json({error: claimsChallenge.message});
+
+        } else {
+            return res.status(403).json({ error: 'Client is not capable' });
+        }
+    } else {
+        next();
+    }
+}
 
+const isClientCapableOfClaimsChallenge = (accessTokenClaims) => {
+    if (accessTokenClaims['xms_cc'] && accessTokenClaims['xms_cc'].includes('CP1')) {
+        return true;
+    }
+
+    return false;
+}
+```
+
+### Generating claims challenge
+
+If there is an auth context entry in the mock database and the incoming request does not contain an access token with the necessary claims, the web API needs to create a **claims challenge** and send it to client application to allow the user to satisfy the challenge (for instance, perform multi-factor authentication). This is shown in [claimsManager.js](./API/utils/claimsManager.js):
+
+```javascript
+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.";
+
+    return {
+        headers,
+        statusCode,
+        message
+    }
+}
 ```
 
 ### Handling claims challenge
 
+Once the client app receives the claims challenge, it needs to present the user with a prompt for satisfying the challenge via Azure AD authorization endpoint. To do so, we use MSAL's `acquireTokenPopup()` API and provide the claims challenge as a parameter in the token request. This is shown in [fetch.js](./SPA/src/fetch.js), where we handle the response from a HTTP DELETE request the to web API with the `handleClaimsChallenge` method:
+
 ```javascript
+import { BrowserAuthError } from "@azure/msal-browser";
+import { protectedResources } from "./authConfig";
+import { msalInstance } from "./index";
+
+export const deleteTask = async (id) => {
+    const accessToken = await getToken();
+
+    const headers = new Headers();
+    const bearer = `Bearer ${accessToken}`;
+
+    headers.append("Authorization", bearer);
+
+    const options = {
+        method: "DELETE",
+        headers: headers
+    };
+
+    return fetch(protectedResources.apiTodoList.todoListEndpoint + `/${id}`, options)
+        .then(handleClaimsChallenge)
+        .catch(error => console.log(error));
+}
+
+const handleClaimsChallenge = async (response) => {
+    if (response.status === 401) {
+        if (response.headers.get('www-authenticate')) {
+            const authenticateHeader = response.headers.get("www-authenticate");
+
+            const claimsChallenge = authenticateHeader.split(" ")
+                .find(entry => entry.includes("claims=")).split('="')[1].split('",')[0];
+
+            try {
+                await msalInstance.acquireTokenPopup({
+                    claims: window.atob(claimsChallenge), // decode the base64 string
+                    scopes: protectedResources.apiTodoList.scopes
+                });
+            } catch (error) {
+                // catch if popups are blocked
+                if (error instanceof BrowserAuthError && 
+                    (error.errorCode === "popup_window_error" || error.errorCode === "empty_window_error")) {
+
+                    await msalInstance.acquireTokenRedirect({
+                        claims: window.atob(claimsChallenge),
+                        scopes: protectedResources.apiTodoList.scopes
+                    });
+                }
+            }
+        } else {
+            return { error: "unknown header" }
+        }
+    }
 
+    return response.json();
+}
 ```
 
 ## More information