通过

添加代码以启用 SSO

  • 项目

在添加启用 SSO 的代码之前，请确保使用 Microsoft Entra ID 注册应用。

使用 Microsoft Entra ID 注册

需要配置选项卡应用的客户端代码，以便从 Entra ID Microsoft获取访问令牌。 访问令牌是由选项卡应用颁发。 如果选项卡应用需要其他 Microsoft Graph 权限，则需要将访问令牌传递到服务器端，并将其交换为 Microsoft Graph 令牌。

配置用于处理访问令牌的代码

本节介绍：

添加客户端代码

若要获取当前应用用户的应用访问权限，客户端代码必须调用 Teams 以获取访问令牌。 需要更新客户端代码，以便使用 getAuthToken() 启动验证过程。


详细了解 getAuthToken ()

getAuthToken() 是 Microsoft Teams JavaScript 库中的方法。 它请求代表应用颁发Microsoft Entra 访问令牌。 如果令牌未过期，则从缓存中获取。 如果过期，则会向Microsoft Entra ID 发送请求以获取新的访问令牌。

有关详细信息，请参阅 getAuthToken。

何时调用 getAccessToken

在需要当前应用用户的访问令牌时使用 getAuthToken() ：

如果需要访问令牌... 调用 getAuthToken () ...
当应用用户访问应用时 之后 microsoftTeams.app.initialize()。
使用应用的特定功能 当应用用户执行需要登录的操作时。

添加 getAuthToken 的代码

将 JavaScript 代码片段添加到选项卡应用，以执行以下操作：

  • 调用 getAuthToken()。
  • 分析访问令牌或将其传递给服务器端代码。

下面的代码段演示了调用 getAuthToken() 的示例。

microsoftTeams.app.initialize().then(() => {
    getClientSideToken()
        .then((clientSideToken) => {
            return getServerSideToken(clientSideToken);
        })
        .then((profile) => {
            return useServerSideToken(profile);
        })
        .catch((error) => {
            ...
        })
}

    function getClientSideToken() {

        return new Promise((resolve, reject) => {
            display("1. Get auth token from Microsoft Teams");
            
            microsoftTeams.authentication.getAuthToken().then((result) => {
                display(result);

                resolve(result);
            }).catch((error) => {
                reject("Error getting token: " + error);
            });
        });
    }

因此，可以将 getAuthToken() 调用添加到所有在需要令牌时启动操作的函数和处理程序。


下面是客户端代码的示例：

配置客户端代码

当 Teams 收到访问令牌时，会根据需要对其进行缓存和重复使用。 每当 getAuthToken() 调用时，都可以使用此令牌，直到它过期，而无需再次调用Microsoft Entra ID。

重要

作为访问令牌安全性的最佳做法：

  • 需要访问令牌时，始终调用 getAuthToken()。
  • Teams 会自动缓存访问令牌，因此无需将其缓存或存储在应用代码中。

当你调用 getAuthToken() 并且需要应用用户的同意才能获得用户级权限时，登录的应用用户会显示一个“Microsoft Entra”对话框。

选项卡单一登录对话提示

显示的同意对话框适用于在 Entra ID Microsoft 中定义的开放 id 范围。 应用用户必须只提供一次同意。 应用用户可以在同意后访问和使用选项卡应用来获取授予的权限和范围。

重要

不需要同意对话的方案：

  • 如果租户管理员已代表租户授予同意，则无需提示应用用户同意。 这意味着应用用户看不到同意对话框，并且可以无缝访问应用。
  • 如果你的 Microsoft Entra 应用注册在 Teams 中请求身份验证的同一租户中，则不能要求应用用户同意，并且会立即获得访问令牌。 仅当 Microsoft Entra 应用在不同租户中注册时，应用用户才同意这些权限。

如果遇到任何错误，请参阅 Teams 中的 SSO 身份验证疑难解答。

使用访问令牌作为身份令牌

返回到选项卡应用的令牌既是访问令牌，也是 ID 令牌。 或者，选项卡应用可以使用令牌作为访问令牌，以向服务器端上的 API 发出经过身份验证的 HTTPS 请求。

从 getAuthToken() 中返回的访问令牌可用于使用令牌中的以下声明来建立应用用户的标识：

  • name：应用用户的显示名称。
  • preferred_username：应用用户的电子邮件地址。
  • oid：表示应用用户 ID 的 GUID。
  • tid：表示应用用户登录到的租户的 GUID。

Teams 可以缓存与应用用户标识相关联的信息，例如用户的首选项。

注意

如果需要构建唯一 ID 来表示系统中的应用用户，请参阅“使用声明可靠地识别用户”以获取详细信息。

将访问令牌传递到服务器端代码

如果需要访问服务器上的 Web API，则需要将访问令牌传递给服务器端代码。 Web API 必须解码访问令牌才能查看该令牌的声明。

注意

如果在返回的访问令牌中未收到用户主体名称 (UPN) ，请在Microsoft Entra ID 中将其添加为 可选声明 。 有关详细信息，请参阅访问令牌。

成功回调 getAuthToken() 中的访问令牌（为经过身份验证的用户）提供对 Web API 的访问权限。 如果需要，服务器端代码也可以分析令牌以获取身份信息。

如果需要传递访问令牌来获取 Microsoft Graph 数据，请参阅 具有 Microsoft Graph 权限的扩展选项卡应用。

用于将访问令牌传递到服务器端的代码

以下代码显示了将访问令牌传递到服务器端的示例。 向服务器端 Web API 发送请求时，令牌在 Authorization 标头中传递。 此示例发送 JSON 数据，因此它使用该 POST 方法。 如果未写入服务器，则 GET 足以发送访问令牌。

function getServerSideToken(clientSideToken) {
        return new Promise((resolve, reject) => {
            microsoftTeams.app.getContext().then((context) => {
                fetch('/getProfileOnBehalfOf', {
                    method: 'post',
                    headers: {
                        'Content-Type': 'application/json'
                    },
                    body: JSON.stringify({
                        'tid': context.user.tenant.id,
                        'token': clientSideToken
                    }),
                    mode: 'cors',
                    cache: 'default'
                })
                .then((response) => {
                    if (response.ok) {
                        return response.json();
                    } else {
                        reject(response.error);
                    }
                })
                .then((responseJson) => {
                    if (responseJson.error) {
                        reject(responseJson.error);
                    } else {
                        const profile = responseJson;

                        resolve(profile);
                    }
                });
            });
        });
    }

验证访问令牌

有关验证访问令牌的详细信息，请参阅 验证令牌。

示例访问令牌

以下代码是访问令牌的典型解码有效负载：

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

代码示例

示例名称 Description .NET Node.js 清单
选项卡 SSO Microsoft Teams 示例应用，用于选项卡Microsoft Entra SSO View 视图、
Teams 工具包		 不适用
选项卡、机器人和消息扩展 (ME) SSO 此示例演示选项卡、机器人和 ME 的 SSO - 搜索、操作和链接展开。 View View View

后续步骤

更新 Teams 应用清单并预览应用

另请参阅