Добавление кода для включения единого входа

Перед добавлением кода для включения единого входа убедитесь, что вы зарегистрировали приложение с помощью Идентификатора Microsoft Entra.

Регистрация с идентификатором Microsoft Entra

Необходимо настроить клиентский код приложения вкладки, чтобы получить маркер доступа из Идентификатора Microsoft Entra. Маркер доступа выдается от имени приложения вкладки. Если приложению вкладки требуются дополнительные разрешения Microsoft Graph, необходимо передать маркер доступа на стороне сервера и обменять его на маркер Microsoft Graph.

Содержание раздела:

• Добавьте код для клиента
• Передача маркера доступа серверному коду
• Проверка маркера доступа

Добавьте код для клиента

Чтобы получить доступ к приложению для текущего пользователя приложения, код на стороне клиента должен выполнить вызов Teams для получения маркера доступа. Чтобы инициировать процесс проверки, вам необходимо обновить клиентский код для использования getAuthToken().

Дополнительные сведения о getAuthToken()

getAuthToken() — это метод в библиотеке JavaScript Microsoft Teams. Он запрашивает выдачу маркера доступа Microsoft Entra от имени приложения. Маркер получается из кэша, если срок его действия не истек. Если срок действия истекает, запрос отправляется в Microsoft Entra ID для получения нового маркера доступа.

Дополнительные сведения см. в разделе getAuthToken.

Когда вызывать getAuthToken

Используйте 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.

Важно!

В качестве наилучшей методики обеспечения безопасности маркера доступа:

• Вызывайте getAuthToken() только тогда, когда вам нужен маркер доступа.
• Teams автоматически кэширует маркер доступа, поэтому нет необходимости кэшировать или хранить его в коде приложения.

Диалоговое окно согласия на получение маркера доступа

Когда вы звоните getAuthToken() и для разрешений уровня пользователя требуется согласие пользователя, для пользователя приложения, выполнившего вход, отображается диалоговое окно Microsoft Entra.

Появится диалоговое окно согласия для областей с открытым идентификатором, определенных в идентификаторе Microsoft Entra. Пользователь приложения должен дать согласие только один раз. Пользователь приложения может получить доступ к приложению вкладки и использовать его для предоставленных разрешений и областей после получения согласия.

Важно!

Сценарии, в которых диалоги согласия не нужны:

• Если администратор клиента предоставил согласие от имени клиента, пользователям приложений вообще не нужно запрашивать согласие. Это означает, что пользователи приложения не видят диалоговые окна согласия и могут беспрепятственно получать доступ к приложению.
• Если приложение Microsoft Entra зарегистрировано в том же клиенте, из которого вы запрашиваете проверку подлинности в Teams, пользователь приложения не может получить согласие и сразу же получает маркер доступа. Пользователи приложений соглашаться на эти разрешения, только если приложение Microsoft Entra зарегистрировано в другом клиенте.

Если вы столкнулись с какими-либо ошибками, см. раздел Устранение неполадок с проверкой подлинности единого входа в Teams.

Использование маркера доступа в качестве маркера удостоверений

Маркер, возвращенный в приложение вкладки, является одновременно маркером доступа и маркером идентификатора. Приложение вкладки может использовать маркер в качестве маркера доступа для выполнения HTTPS-запросов, прошедших проверку подлинности, к API на стороне сервера.

Токен доступа, возвращенный из getAuthToken(), можно использовать для установления личности пользователя приложения с помощью следующих утверждений в маркере:

• name: отображаемое имя пользователя приложения.
• preferred_username: адрес электронной почты пользователя приложения.
• oid: GUID, представляющий идентификатор пользователя приложения.
• tid: идентификатор GUID, представляющий клиент, в который входит пользователь приложения.

Teams могут кэшировать эти сведения, связанные с удостоверением пользователя приложения, например предпочтениями пользователя.

Примечание.

Если вам нужно создать уникальный идентификатор для представления пользователя приложения в вашей системе, см. раздел Использование утверждений для надежной идентификации пользователя.

Передача маркера доступа серверному коду

Если вам нужно получить доступ к веб-API на сервере, необходимо передать маркер доступа в код на стороне сервера. Веб-API должны декодировать маркер доступа для просмотра утверждений для этого маркера.

Примечание.

Если вы не получили имя участника-пользователя (UPN) в возвращенном маркере доступа, добавьте его в качестве необязательного утверждения в идентификаторе Microsoft Entra. Дополнительные сведения см. в разделе Маркеры доступа.

Маркер доступа, полученный при успешном обратном вызове getAuthToken(), предоставляет доступ (для пользователя приложения, прошедшего проверку подлинности) к вашим веб-API. Код на стороне сервера также может анализировать маркер на предмет сведений об удостоверении, если это необходимо.

Если вам нужно передать маркер доступа для получения данных Microsoft Graph, см. Расширение приложения вкладки с разрешениями Microsoft Graph.

Код для передачи маркера доступа на сервер

В следующем коде показан пример передачи маркера доступа на сервер. Маркер передается в Authorizationзаголовке при отправке запроса в серверный веб-API. В этом примере отправляются данные 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"
}

Примеры кода

Название примера	Описание	.NET	Node.js	Манифест
Единый вход на вкладке	Пример приложения Microsoft Teams для вкладок Microsoft Entra SSO	Просмотр	View, Teams Toolkit	Н/Д
Единый вход в табуляции, бота и расширения сообщений (ME)	В этом примере показан единый вход для tab, бота и me — поиск, действие и распаковка ссылок.	Просмотр	Просмотр	Просмотр

Следующий этап

Обновление манифеста приложения Teams и предварительный просмотр приложения

См. также

• jwt.ms
• Необязательное утверждение Active Directory
• Маркеры доступа
• Обзор библиотеки проверки подлинности Microsoft (MSAL)
• Маркеры идентификатора платформы Microsoft Identity
• Маркеры доступа платформы удостоверений Майкрософт