使用 SSO 获取已登录用户的标识

getAccessToken使用 API 获取包含登录到 Office 的当前用户的标识的访问令牌。 访问令牌也是 ID 令牌，因为它包含有关已登录用户的标识声明，例如其名称和电子邮件。 调用自己的 Web 服务时，还可以使用 ID 令牌来标识用户。 若要调用 getAccessToken，必须将 Office 外接程序配置为将 SSO 与 Office 配合使用。

在本文中，你将创建一个获取 ID 令牌的 Office 外接程序，并在任务窗格中显示用户的姓名、电子邮件和唯一 ID。

注意

Office 和 API 的 getAccessToken SSO 并不适用于所有方案。 始终实现回退对话框，以在 SSO 不可用时登录用户。 有关详细信息，请参阅 使用 Office 对话框 API 进行身份验证和授权。

创建应用注册

若要将 SSO 与 Office 配合使用，需要在 Azure 门户中创建应用注册，以便Microsoft 标识平台可以为 Office 外接程序及其用户提供身份验证和授权服务。

1. 若要注册应用，请转到“Azure 门户 - 应用注册”页。

2. 使用 管理员 凭据登录到 Microsoft 365 租户。 例如，MyName@contoso.onmicrosoft.com。

3. 选择“新注册”。 在“注册应用”页上，按如下方式设置值。

   • 将“名称”设置为“Office-Add-in-SSO”。
   • 将“受支持的帐户类型”设置为“任何组织目录中的帐户和个人 Microsoft 帐户”（例如，Skype、Xbox、Outlook.com）。
   • 将应用程序类型设置为 “Web ”，然后将 “重定向 URI” 设置为 https://localhost:[port]/dialog.html。 将 替换为 [port] Web 应用程序的正确端口号。 如果使用 Yo Office 创建了加载项，则端口号通常为 3000，并在 package.json 文件中找到。 如果使用 Visual Studio 2019 创建了加载项，则会在 Web 项目的 SSL URL 属性中找到该端口。
   • 选择“注册”。

4. 在 Office-Add-in-SSO 页上，复制并保存 应用程序 (客户端) ID 和 目录 (租户) ID 的值。 你将在后面的过程中使用它们。

   注意

   当其他应用程序（如 Office 客户端应用程序 (（例如 PowerPoint、Word、Excel) ）寻求对应用程序的授权访问权限时，此应用程序 (客户端) ID 是“受众”值。 当应用程序反过来寻求对 Microsoft Graph 的授权访问权限时，它也是应用程序的“客户端 ID”。

5. 选择“管理”下的“身份验证”。 在 “隐式授予 ”部分中，为 访问令牌 和 ID 令牌启用复选框。

6. 在窗体顶部，选择“保存”。

7. 在“管理”下选择“公开 API”。 选择“ 设置” 链接。 这将以 的形式 api://[app-id-guid]生成应用程序 ID URI，其中 [app-id-guid] 是 应用程序 (客户端) ID。

8. 在生成的 ID 中，插入 localhost:[port]/ (记下追加到双正斜杠与 GUID 之间的末尾) 的正斜杠“/”。 将 替换为 [port] Web 应用程序的正确端口号。 如果使用 Yo Office 创建了加载项，则端口号通常为 3000，并在 package.json 文件中找到。 如果使用 Visual Studio 2019 创建了加载项，则会在 Web 项目的 SSL URL 属性中找到该端口。

   完成后，整个 ID 应具有 窗体 api://localhost:[port]/[app-id-guid];例如 api://localhost:44355/c6c1f32b-5e55-4997-881a-753cc1d563b7。

9. 选择“添加一个作用域”按钮。 在打开的面板中，输入 access_as_user 作为 <“作用域> 名称”。

10. 将“谁能同意?”设置为“管理员和用户”。

11. 填写用于配置管理员和用户同意提示的字段，这些字段的值适用于 access_as_user 范围，使 Office 客户端应用程序能够使用与当前用户具有相同权限的外接程序 Web API。 建议：

    • 管理员同意显示名称：Office 可以充当用户。
    • 管理员许可描述：使 Office 能够借助与当前用户相同的权限调用加载项的 Web API。
    • 用户同意显示名称：Office 可以充当你。
    • 用户同意说明：允许 Office 使用您拥有的相同权限调用外接程序的 Web API。

12. 确保将“状态”设置为“已启用”。

13. 选择“添加作用域”。

    注意

    文本字段正下方显示的作用域>名称的<域部分应自动匹配前面设置的应用程序 ID URI，并/access_as_user追加到末尾;例如。 api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user

14. 在 “授权的客户端应用程序 ”部分中，输入以下 ID 以预授权所有Microsoft Office 应用程序终结点。

    • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (所有Microsoft Office 应用程序终结点)

    注意

    该 ea5a67f6-b6f3-4338-b240-c655ddc3cc8e ID 在以下所有平台上预授权 Office。 或者，如果出于任何原因想要在某些平台上拒绝对 Office 的授权，则可以输入以下 ID 的正确子集。 只需省略要从中扣留授权的平台的 ID 即可。 这些平台上加载项的用户将无法调用 Web API，但外接程序中的其他功能仍可正常工作。

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
    • 93d53678-613d-4013-afc1-62e9e444a0a5（Office 网页版）
    • bc59ab01-8403-45c6-8796-ac3ef710b3e3（Outlook 网页版）

15. 选择“添加客户端应用程序”按钮，然后在打开的面板中，将 设置为[app-id-guid]“应用程序 (客户端) ID”，并检查 框api://localhost:44355/[app-id-guid]/access_as_user。

16. 选择“添加应用程序”。

17. 选择“管理”下的“API 权限”，然后选择“添加权限”。 在打开的面板上，选择 Microsoft Graph，然后选择“委派权限”。

18. 使用“选择权限”搜索框来搜索加载项需要的权限。 搜索并选择 配置文件 权限。 Office profile 应用程序需要权限才能获取外接程序 Web 应用程序的令牌。

    • profile

    注意

    User.Read 权限可能已默认列出。 最好不要请求不需要的权限，因此，如果外接程序实际上不需要此权限，我们建议取消选中此权限的框。

19. 选择窗格下方选择“添加权限”。

20. 在同一页上，选择“为<租户名称>授予管理员同意”按钮，然后选择“是”进行显示的确认。

创建 Office 加载项

Visual Studio 2019

1. 启动 Visual Studio 2019 并选择 “创建新项目”。
2. 搜索并选择 Excel Web 外接程序 项目模板。 然后选择“下一步”。 注意：SSO 适用于任何 Office 应用程序，但 Excel 是本文中使用的应用程序。
3. 输入项目名称（例如 sso-display-user-info），然后选择“ 创建”。 可以将其他字段保留为默认值。
4. 在 “选择加载项类型 ”对话框中，选择“ 向 Excel 添加新功能”，然后选择“ 完成”。

项目已创建，并将在解决方案中包含两个项目。

• sso-display-user-info：包含将加载项旁加载到 Excel 的清单和详细信息。
• sso-display-user-infoWeb：承载加载项网页的 ASP.NET 项目。

Yo Office

请确保已 设置开发环境。

1. 输入以下命令创建项目。

   yo office --projectType taskpane --name 'sso-display-user-info' --host excel --js true
   

项目在名为 sso-display-user-info 的新文件夹中创建。

配置清单

Visual Studio 2019

在 解决方案资源管理器 中，打开 sso-display-user-info>sso-display-user-infoManifest>sso-display-user-info.xml。

Yo Office

在 Visual Studio Code 中，打开 manifest.xml 文件。

1. 清单底部附近是一个结束 </Resources> 元素。 将以下 XML 插入到 元素正下方， </Resources> 但在结束 </VersionOverrides> 元素之前。 对于 Outlook 以外的 Office 应用程序，请将 标记添加到部分的 <VersionOverrides ... xsi:type="VersionOverridesV1_0"> 末尾。 对 Outlook，请将此标记添加到 <VersionOverrides ... xsi:type="VersionOverridesV1_1"> 部分的末尾。

   <WebApplicationInfo>
       <Id>[application-id]</Id>
       <Resource>api://localhost:[port]/[application-id]</Resource>
       <Scopes>
           <Scope>openid</Scope>
           <Scope>user.read</Scope>
           <Scope>profile</Scope>
       </Scopes>
   </WebApplicationInfo>
   

2. 将 替换为 [port] 项目的正确端口号。 如果使用 Yo Office 创建了加载项，则端口号通常为 3000，并在 package.json 文件中找到。 如果使用 Visual Studio 2019 创建了加载项，则会在 Web 项目的 SSL URL 属性中找到该端口。

3. 将这两个 [application-id] 占位符替换为应用注册中的实际应用程序 ID。

4. 保存文件。

插入的 XML 包含以下元素和信息。

• <WebApplicationInfo> - 以下元素的父元素。
• <ID> - 加载项的客户端 ID 这是在注册外接程序时获取的应用程序 ID。 请参阅向 Azure AD v2.0 端点注册使用 SSO 的 Office 加载项。
• <资源> - 加载项的 URL。 这是在 AAD 中注册加载项时使用的相同 URI（包括 api: 协议）。 此 URI 的域部分必须与域（包括外接程序清单的“资源”>部分的 URL< 中使用的任何子域）匹配，并且 URI 必须以 Id> 中的<客户端 ID 结尾。
• <Scopes> - 一个或多个 <Scope> 元素的父级。
• <范围> - 指定加载项需要对 AAD 的权限。 profile如果外接程序无法访问 Microsoft Graph，则始终需要 和 openID 权限，并且可能是唯一所需的权限。 如果是，则还需要<为所需的Microsoft Graph 权限使用 Scope> 元素;例如 、User.ReadMail.Read。 在代码中用于访问 Microsoft Graph 的库可能需要其他权限。 例如，Microsoft身份验证库 (适用于 .NET 的 MSAL) 需要 offline_access 权限。 有关详细信息，请参阅向 Office 加载项中的 Microsoft Graph 授权。

添加 jwt-decode 包

可以调用 getAccessToken API 从 Office 获取 ID 令牌。 首先，添加 jwt-decode 包，以便更轻松地解码和查看 ID 令牌。

Visual Studio 2019

1. 打开 Visual Studio 解决方案。

2. 在菜单上，选择 “工具”>“NuGet 包管理器>包管理器控制台”。

3. 在 包管理器控制台中输入以下命令。

   Install-Package jwt-decode -Projectname sso-display-user-infoWeb

Yo Office

1. 从终端/控制台窗口转到外接程序项目的根文件夹。

2. 输入以下命令

   npm install jwt-decode

将 UI 添加到任务窗格

修改任务窗格，以便它可以显示将从 ID 令牌获取的用户信息。

Visual Studio 2019

1. 打开 Home.html 文件。

2. 将以下脚本标记添加到 <head> 页面的 部分。 这将包括之前添加的 jwt-decode 包。

   <script src="Scripts/jwt-decode-2.2.0.js" type="text/javascript"></script>
   

3. 将 <body> 节替换为以下 HTML。

   <body>
     <h1>Welcome</h1>
     <p>
       Sign in to Office, then choose the <b>Get ID Token</b> button to see your
       ID token information.
     </p>
     <button id="getIDToken">Get ID Token</button>
     <div>
       <span id="userInfo"></span>
     </div>
   </body>
   

Yo Office

1. 打开 src/taskpane/taskpane.html 文件。

2. 将 <body> 节替换为以下 HTML。

   <body>
     <h1>Welcome</h1>
     <p>
       Sign in to Office, then choose the <b>Get ID Token</b> button to see your
       ID token information.
     </p>
     <button id="getIDToken">Get ID Token</button>
     <div>
       <span id="userInfo"></span>
     </div>
   </body>
   

调用 getAccessToken API

最后一步是通过调用 getAccessToken获取 ID 令牌。

Visual Studio 2019

1. 打开 Home.js 文件。

2. 使用以下代码替换文件的全部内容。

   (function () {
     "use strict";
   
     // The initialize function must be run each time a new page is loaded.
     Office.initialize = function (reason) {
       $(document).ready(function () {
         $("#getIDToken").on("click", getIDToken);
       });
     };
   
     async function getIDToken() {
       try {
         let userTokenEncoded = await OfficeRuntime.auth.getAccessToken({
           allowSignInPrompt: true,
         });
         let userToken = jwt_decode(userTokenEncoded);
         document.getElementById("userInfo").innerHTML =
           "name: " +
           userToken.name +
           "<br>email: " +
           userToken.preferred_username +
           "<br>id: " +
           userToken.oid;
         console.log(userToken);
       } catch (error) {
         document.getElementById("userInfo").innerHTML =
           "An error occurred. <br>Name: " +
           error.name +
           "<br>Code: " +
           error.code +
           "<br>Message: " +
           error.message;
         console.log(error);
       }
     }
   })();
   

3. 保存文件。

Yo Office

1. 打开 src/taskpane/taskpane.js 文件。

2. 使用以下代码替换文件的全部内容。

   import jwt_decode from "jwt-decode";
   
   Office.onReady((info) => {
     if (info.host === Office.HostType.Excel) {
       document.getElementById("getIDToken").onclick = getIDToken;
     }
   });
   
   async function getIDToken() {
     try {
       let userTokenEncoded = await OfficeRuntime.auth.getAccessToken({
         allowSignInPrompt: true,
       });
       let userToken = jwt_decode(userTokenEncoded);
       document.getElementById("userInfo").innerHTML =
         "name: " +
         userToken.name +
         "<br>email: " +
         userToken.preferred_username +
         "<br>id: " +
         userToken.oid;
       console.log(userToken);
     } catch (error) {
       document.getElementById("userInfo").innerHTML =
         "An error occurred. <br>Name: " +
         error.name +
         "<br>Code: " +
         error.code +
         "<br>Message: " +
         error.message;
       console.log(error);
     }
   }
   

3. 保存文件。

运行加载项

Visual Studio 2019

选择 “调试>开始调试”，或按 F5。

Yo Office

从命令行运行 npm start 。

1. Excel 启动时，使用用于创建应用注册的同一租户帐户登录到 Office。
2. 在 “主页” 功能区上，选择“ 显示任务窗格 ”以打开加载项。
3. 在加载项的任务窗格中，选择“ 获取 ID 令牌”。

加载项将显示登录时使用的帐户的名称、电子邮件和 ID。

注意

如果遇到任何错误，请查看本文中有关应用注册的注册步骤。 设置应用注册时缺少详细信息是使用 SSO 时出现问题的常见原因。 如果仍无法使加载项成功运行，请参阅 排查单一登录 (SSO) 的错误消息 。

停止加载项

Visual Studio 2019

选择 “停止调试”，或按 Shift+F5。

Yo Office

从命令行运行 npm stop 。

另请参阅

使用声明可靠地标识用户 (使用者和对象 ID)