嵌套应用身份验证

NAA 是嵌入主机环境（如 Teams、Outlook 和 Microsoft 365）中的 SPA 的新身份验证协议。 它简化了身份验证过程，以便跨嵌套在受支持的主机应用中的应用 (SSO) 单一登录。 NAA 模型支持主机应用的主要标识，其中包含嵌套应用的多个应用标识。 Microsoft在 Teams 选项卡、个人应用和 Office 加载项中使用此模型。

NAA 模型比代表 (OBO) 流具有多个优势：

• NAA 要求你仅使用 MSAL.js 库。 无需在 TeamsJS) (Teams JavaScript 客户端库中使用 getAuthToken 函数。

• 可以使用来自客户端代码的访问令牌（作为 SPA）调用 Microsoft Graph 等服务。 无需使用中间层服务器。

• 可以对范围使用增量和动态许可 (权限) 。

• 无需预授权主机（例如 Teams 或 Microsoft 365）来调用终结点。

  下表概述了 Teams Microsoft Entra SSO 与 NAA 之间的差异：

  开发所需的步骤	传统 Teams Entra SSO	NAA
  公开重定向 URI	必需	必需
  在Microsoft Entra ID 中注册 API	必需
  在Microsoft Entra ID 中定义自定义范围	必需
  授权 Teams 客户端应用	必需
  修改应用清单 (以前称为 Teams 应用清单)	必需	推荐*
  通过 TeamsJS SDK 获取访问令牌	必需
  请求用户同意以获得更多权限	必需
  在服务器上执行 OBO 交换	必需

• IT 管理员可能会阻止应用或仅同意Microsoft Entra ID 中应用的特定权限。 若要避免这种情况，必须在应用清单中包含应用 ID 和默认资源，以便管理员在 Teams 管理中心批准权限。

NAA 的用例

配置 NAA

若要配置嵌套身份验证，请执行以下步骤：

1. 注册 SPA
2. 添加受信任的代理
3. 初始化公共客户端应用
4. 获取第一个令牌
5. 调用 API

注册 SPA

必须在 Azure 门户 上为加载项创建Microsoft Entra ID 应用注册。 应用注册必须具有名称、支持的帐户类型和 SPA 重定向。 注册应用后，Azure 门户会生成Microsoft Entra应用注册 ID。 如果外接程序需要除 NAA 和 SSO 以外的其他应用注册，请参阅 注册单页应用程序。

添加受信任的代理

若要配置嵌套应用身份验证，应用必须主动配置应用的重定向 URI。 重定向 URI 向Microsoft 标识平台指示支持主机可以中转应用。 应用的重定向 URI 必须是 单页应用程序 类型，并且符合以下方案：

brk-multihub://<your_domain>

其中：

• brk-multihub 使身份验证可由配置为运行的任何Microsoft 365 支持的主机（例如 Teams、Outlook 或 Microsoft365.com）中转。
• < > your_domain是托管应用的完全限定域名。 例如 ，brk-multihub：//contoso.com。

域必须仅包含源，而不能包含其子路径。 例如：

✔️ brk-multihub：//myapp.teams.microsoft.com
❌ brk-multihub：//myapp.teams.microsoft.com/go

有关将 Teams 应用升级为在 Outlook 和 Microsoft365.com 中运行的详细信息，请参阅 跨 Microsoft 365 扩展 Teams 应用。

初始化公共客户端应用

根据需要初始化 MSAL 并获取公共客户端应用的实例以获取访问令牌。

import {
  AccountInfo,
  IPublicClientApplication,
  createNestablePublicClientApplication,
} from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: "your_client_id",
    authority: "https://login.microsoftonline.com/{your_tenant_id}",
    supportsNestedAppAuth: true
  },
};

let pca: IPublicClientApplication;

export function initializePublicClient() {
  console.log("Starting initializePublicClient");
  return createNestablePublicClientApplication(msalConfig).then(
    (result) => {
      console.log("Client app created");
      pca = result;
      return pca;
    }
  );
}

获取第一个令牌

MSAL.js 通过嵌套应用身份验证获取的令牌将为Microsoft Entra应用注册 ID 颁发。 MSAL.js 处理用户身份验证的令牌获取。 它尝试以无提示方式获取访问令牌。 如果这不成功，它会提示用户同意。 然后，该令牌用于调用Microsoft图形 API或其他受Microsoft Entra ID 保护的资源。 与 OBO 流不同，无需预授权主机来调用终结点。

若要获取令牌，请执行以下步骤：

1. 使用 MSAL.js 获取应用 ID 的令牌。 有关详细信息，请参阅 获取和使用访问令牌。

2. 使用 getActiveAccount API 验证是否有活动帐户来调用 publicClientApplication。 如果没有活动帐户，请尝试使用 其他筛选器参数（如 tenantID、 homeAccountId和 loginHint）从上下文接口检索缓存getAccount中的帐户。

   注意

   属性 homeAccountId 等效于 userObjectId TeamsJS 中。

3. 调用 publicClientApplication.acquireTokenSilent(accessTokenRequest) 以无提示方式获取令牌，无需用户交互。 accessTokenRequest 指定请求访问令牌的范围。 NAA 支持增量和动态同意。 确保始终请求代码完成其任务所需的最小范围。

4. 如果没有可用的帐户，MSAL.js 将 InteractionRequiredAuthError返回 。 调用 publicClientApplication.acquireTokenPopup(accessTokenRequest) 以显示用户的交互式对话。 acquireTokenSilent 如果令牌过期或用户未同意所有请求的范围，则可能会失败。

   以下代码片段显示了访问令牌的示例：

   
     // MSAL.js exposes several account APIs, logic to determine which account to use is the responsibility of the developer
     const account = publicClientApplication.getActiveAccount();
   
     const accessTokenRequest = {
     scopes: ["user.read"],
     account: account,
     };
   
     publicClientApplication
       .acquireTokenSilent(accessTokenRequest)
       .then(function (accessTokenResponse) {
         // Acquire token silent success
         let accessToken = accessTokenResponse.accessToken;
         // Call your API with token
         callApi(accessToken);
       })
       .catch(function (error) {
         //Acquire token silent failure, and send an interactive request
         if (error instanceof InteractionRequiredAuthError) {
           publicClientApplication
             .acquireTokenPopup(accessTokenRequest)
             .then(function (accessTokenResponse) {
               // Acquire token interactive success
               let accessToken = accessTokenResponse.accessToken;
               // Call your API with token
               callApi(accessToken);
             })
             .catch(function (error) {
               // Acquire token interactive failure
               console.log(error);
             });
         }
         console.log(error);
       });
   
   

调用 API

收到令牌后，使用它调用 API。 这可确保使用有效的令牌调用 API，以向服务器发出经过身份验证的请求。

以下示例演示如何向Microsoft图形 API发出经过身份验证的请求，以访问Microsoft 365 数据：

var headers = new Headers();
var bearer = "Bearer " + access_token;
headers.append("Authorization", bearer);
var options = {
    method: "GET",
    headers: headers
};

var graphEndpoint = "<https://graph.microsoft.com/v1.0/me>";

fetch(graphEndpoint, options)
    .then(function (response) {
        //do something with response
    });

用于嵌套应用身份验证的令牌预提取 (NAA)

为了提高性能并减少身份验证延迟，嵌套应用身份验证 (NAA) 支持令牌预提取。 此功能使主机能够在应用启动之前主动获取身份验证令牌，从而更快地访问受保护的资源。

如何启用令牌预提取

若要启用令牌预提取，请将 Teams 应用清单更新到版本 1.22 或更高版本，并在 中包含 webApplicationInfo部分nestedAppAuthInfo。

{
 "webApplicationInfo": {
   "id": "33333ddd-0000-0000-0000-88888757bbbb",
   "resource": "api://app.com/botid-33333ddd-0000-0000-0000-88888757bbbb",
   "nestedAppAuthInfo": [
     {
       "redirectUri": "brk-multihub://app.com",
       "scopes": ["openid", "profile", "offline_access"],
       "claims": "{\"access_token\":{\"xms_cc\":{\"values\":[\"CP1\"]}}}"
     }
   ]
 }
}

运作方式

启用令牌预提取后，主机环境会尝试在呈现应用之前获取和缓存所需的令牌。 这些令牌存储在内存中，并在启动时立即提供给应用。

此行为类似于旧版 Teams SSO 模型中的预提取功能，该模型在 getAuthToken 选项卡加载期间自动触发了 API。 使用嵌套应用身份验证 (NAA) ，此功能通过清单配置引入，无需进行后端令牌交换即可提高性能。

NAA 中令牌预提取的优点

• 通过减少应用启动期间的身份验证延迟来提高性能
• 跨嵌套应用启用单一登录 (SSO) ，无需重复登录

最佳做法

• 尽可能使用无提示身份验证：MSAL.js 提供了 acquireTokenSilent 方法，该方法通过在不提示用户的情况下发出无提示令牌请求来处理令牌续订。 方法首先在浏览器存储中查找有效的缓存令牌。 如果找不到，库会向Microsoft Entra ID 发出无提示请求，如果存在活动用户会话 (由Microsoft Entra域) 上浏览器中设置的 Cookie 确定，Microsoft Entra ID 将返回新的令牌。 库不会自动调用 acquireTokenSilent 方法。 建议在进行 API 调用 acquireTokenSilent 之前在应用中调用 以获取有效令牌。

  在某些情况下，尝试使用 方法获取令牌失败 acquireTokenSilent 。 例如，如果某个用户会话已过期，其 ID 为Microsoft Entra，或者应用用户更改了密码，acquireTokenSilent则会失败。 () acquireTokenPopup 调用交互式获取令牌方法。

• 具有回退：NAA 流提供跨Microsoft生态系统的兼容性。 但是，你的应用可能显示在未更新为支持 NAA 的下层客户端或旧版客户端中。 在这种情况下，你的应用不能支持无缝 SSO，你可能需要调用特殊的 API 来与用户交互以打开身份验证对话框。 有关详细信息，请参阅 为选项卡应用启用 SSO。

  注意

  如果使用非Microsoft Entra标识提供者，则不得使用 NAA，可以改用弹出身份验证。

• 对 NAA 的支持：并非所有主机应用环境都支持 NAA。 若要验证当前客户端是否支持此功能，可以调用指定的 API 来确定其状态。 返回值 表示 true 对 NAA 的支持，但 false 表示不支持 NAA。

• 在多个环境中测试应用：如果你的应用预期同时在 Web 视图和浏览器部署中运行，我们建议在这两个部署环境中测试你的应用，以确保其按预期运行。 浏览器中运行的某些 API 可能无法在 Web 视图中运行。

代码示例

另请参阅

• Microsoft 标识平台和 OAuth 2.0 代表流
• MSAL 中的缓存
• 嵌套应用身份验证简介：改进的 Teams 应用的身份验证协议