Enable single sign-on in an Office Add-in with nested app authentication

Initialize the MSAL library

Next, you need to initialize MSAL and get an instance of the public client application.

Add the following code to the taskpane.js or taskpane.ts file. Replace the Enter_the_Application_Id_Here placeholder with the Azure app ID you saved previously. About the following code note:

• The initMsal function initializes MSAL by calling createNestablePublicClientApplication. This creates a nestable public client application that supports SSO with Outlok.
• The initMsal function sets the authority to common, which supports work and school accounts or personal Microsoft accounts. If you want to configure a single tenant or other account types, see Application configuration options for additional authority options.

let msalInstance = undefined;

/**
 * Initialize MSAL as a nestable public client application.
  */
async function initMsal() {
  if (!msalInstance) {
    const clientId = "Enter_the_Application_Id_Here";
    const msalConfig = {
      auth: {
        clientId: clientId,
        authority: "https://login.microsoftonline.com/common"
      },
      cache: {
        cacheLocation: "localStorage"
      }
    };
    msalInstance = await createNestablePublicClientApplication(msalConfig);
  }
}

Acquire your first token

The tokens acquired by MSAL.js via NAA will be issued for your Azure app registration ID. In this code sample, you acquire a token for the Microsoft Graph API. If the user has an active session with Microsoft Entra ID the token is acquired silently. If not, the library prompts the user to sign in interactively. The token is then used to call the Microsoft Graph API.

The following steps show the pattern to use for acquiring a token.

1. Specify your scopes. NAA supports incremental and dynamic consent so always request the minimum scopes needed for your code to complete its task.
2. Call acquireTokenSilent. This will get the token without requiring user interaction.
3. If acquireTokenSilent fails, call acquireTokenPopup to display an interactive dialog for the user. acquireTokenSilent can fail if the token expired, or the user has not yet consented to all of the requested scopes.

The following code shows how to implement this authentication pattern in your own project.

1. Replace the run function in taskpane.js or taskpane.ts with the following code. The code specifies the minimum scopes needed to read the user's files.

   export async function run() {
     await initMsal();
     // Specify minimum scopes needed for the access token.
     const tokenRequest = {
       scopes: ["Files.Read", "User.Read"],
     };
     let accessToken = null;
   
     // TODO 1: Use msalInstance to get an access token.
   
     // TODO 2: Call the Microsoft Graph API.
   }
   

   Important

   The token request must include scopes other than just offline_access, openid, profile, or email. You can use any combination of the previous scopes, but you must include at least one additional scope. If not, the token request can fail.

2. Replace TODO 1 with the following code. This code calls acquireTokenSilent to get the access token.

   try {
     const userAccount = await msalInstance.acquireTokenSilent(tokenRequest);
     console.log("Acquired token silently.");
     accessToken = userAccount.accessToken;
   } catch (silentError) {
     // TODO 1a: Handle acquireTokenSilent failure.
   
   }
   

3. Replace TODO 1a with the following code. This code checks if acquireTokenSilent threw an InteractionRequiredAuthError. If so the code calls acquireTokenPopup so that MSAL can use a popup dialog to interact with the user. Interaction can be required for a variety of reasons, such as completing multi-factor authorization.

   if (silentError instanceof InteractionRequiredAuthError) {
     console.log(`Unable to acquire token silently: ${silentError}`);
     // Silent acquisition failed. Continue to interactive acquisition.
     try {
       const userAccount = await msalInstance.acquireTokenPopup(tokenRequest);
       console.log("Acquired token interactively.");
       accessToken = userAccount.accessToken;
     } catch (popupError) {
       // Acquire token interactive failure.
       console.error(`Unable to acquire token interactively: ${popupError}`);
       return;
     }
   } else {
     // Acquire token silent failure. Error can't be resolved through interaction.
     console.error(`Unable to acquire token silently: ${silentError}`);
     return;
   }
   

Call an API

After acquiring the token, use it to call an API. The following example shows how to call the Microsoft Graph API by calling fetch with the token attached in the Authorization header.

• Replace TODO 2 with the following code.

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: `Bearer ${accessToken}` },
    }
  );
  
  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);
  
    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");
  
    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
  

Once all the previous code is added to the run function, be sure a button on the task pane calls the run function. Then you can sideload the add-in and try out the code.

Initialize the MSAL library

Next, you need to initialize MSAL and get an instance of the public client application. This is used to get access tokens when needed. We recommend that you put the code that creates the public client application in the Office.onReady method.

1. Add the following initMsal function to the taskpane.js or taskpane.ts file. It calls createNestablePublicClientApplication to initialize an MSAL instance to use NAA.
2. Replace the Enter_the_Application_Id_Here placeholder with the Azure app ID you saved previously.

let msalInstance = null; // MSAL instance

/**
 * Initialize MSAL as a nestable public client application.
 */
async function initMsal() {
  if (!msalInstance) {
    const clientId = "Enter_the_Application_Id_Here";
    const msalConfig = {
      auth: {
        clientId: clientId,
        authority: "https://login.microsoftonline.com/common"
      },
      cache: {
        cacheLocation: "localStorage"
      }
    };
    msalInstance = await createNestablePublicClientApplication(msalConfig);
  }
}

Add a function to get the login hint

When running in Word, Excel, or PowerPoint in the browser, you must provide a login hint to MSAL to identify the correct account. You can get the login hint from the Office authContext.userPrincipalName property. Add the following function which can be called at any time to get the login hint.

Add the following function to the taskpane.js or taskpane.ts file.

/**
 * Get the login hint from Office.AuthContext for a better SSO experience.
 * This is especially important for Office in a browser.
 */
async function getLoginHint() {
    try {
        if (typeof Office !== "undefined" && Office.context) {
            const authContext = await Office.auth.getAuthContext();
            if (authContext?.userPrincipalName) return authContext.userPrincipalName;
        }
    } catch (error) {
        console.warn("Could not get login hint:", error);
    }
    return null;
}

Acquire the access token

Build a function to acquire the access token.

Add the following function to the taskpane.js or taskpane.ts file. About the following code note:

• It gets the login hint which is required when running in Word, Excel, or PowerPoint in a browser.
• It calls ssoSilent (not acquireTokenSilent) to get an access token.
• If ssoSilent fails, it checks if interaction is required. If so it calls acquireTokenPopup so MSAL can interact with the user.

/**
 * Acquire an access token silently, or interactively if needed.
 * @param {Array} scopes - The scopes for which the token is requested.
 * @returns {Promise<string>} - The acquired access token.
 */
async function acquireAccessToken(scopes) {
  await initMsal();

  const request = {
    scopes: scopes,
    loginHint: await getLoginHint()
  }

  let authResult = null;
  try {
    authResult = await msalInstance.ssoSilent(request);
  } catch (error) {
    if (error instanceof InteractionRequiredAuthError) {
      authResult = await msalInstance.acquireTokenPopup(request);
    } else {
      console.error("Silent token acquisition failed:", error);
    }
  }
  if (!authResult) {
    throw new Error("Could not acquire access token");
  }
  console.log(authResult);
  return authResult.accessToken;

}

Get token and call the Graph API

After acquiring the token, use it to call an API. The following example shows how to call the Microsoft Graph API by calling fetch with the token attached in the Authorization header.

Update the run function in the taskpane.js or taskpane.ts file to match the following code. About the following code note:

• It calls the acquireAccessToken function you created previously and passes the Files.Read and User.Read scopes. The token request must include scopes other than just offline_access, openid, profile, or email. You can use any combination of the previous scopes, but you must include at least one additional scope. If not, the token request can fail.
• It uses the access token to make a call the Microsoft Graph API to retrieve 10 of the user's file names from OneDrive.

export async function run() {
  let accessToken;
  try {
    // Acquire an access token for Microsoft Graph.
    accessToken = await acquireAccessToken(["Files.Read", "User.Read"]);
    console.log("Access token acquired:", accessToken);
  }
  catch (error) {
    console.error("Error acquiring access token:", error);
    return;
  }

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: `Bearer ${accessToken}` },
    }
  );

  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);

    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");

    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
}

Once all the previous code is added to the run function, be sure a button on the task pane calls the run function. Then you can sideload the add-in and try out the code.