Использование внешних поставщиков OAuth

  • Статья

Примечание.

В этом разделе представлена версия 2.0.x клиентской библиотеки JavaScript (TeamsJS) Microsoft Teams. Если вы используете более раннюю версию, ознакомьтесь с обзором библиотеки TeamsJS , чтобы узнать о различиях между последней версией TeamsJS и более ранними версиями.

Вы можете поддерживать внешних или сторонних поставщиков OAuth, таких как Google, GitHub, LinkedIn и Facebook с помощью обновленного authenticate() API:

function authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>

Добавьте следующие значения в API для поддержки authenticate() внешних поставщиков OAuth:

  • Параметр isExternal
  • Три значения заполнителей в существующем url параметре

В следующей таблице приведен список authenticate() параметров API (AuthenticatePopUpParameters) и функций, а также их описания:

Параметр Описание
isExternal Тип параметра — логический. Он указывает, что окно аутентификации открывается во внешнем браузере.
height Предпочтительная высота всплывающего окна. Значение можно игнорировать, если он находится за пределами допустимых границ.
url
URL-адрес стороннего сервера приложений для всплывающего окна проверки подлинности со следующими тремя заполнителями параметров:

- oauthRedirectMethod: передача заполнителя в {}. Платформа Teams заменяет этот заполнитель прямой ссылкой или веб-страницей, которая обновляет сервер приложений, если вызов поступает с мобильной платформы.

- authId: UUID (универсальный уникальный идентификатор) заменяет этот заполнитель. Сервер приложений использует его для обслуживания сеанса.

- hostRedirectUrl: передает заполнитель в {}. Текущая платформа и клиент заменяют этот заполнитель URL-адресом перенаправления, который перенаправляет пользователя на правильный клиент после завершения проверки подлинности.
width Предпочтительная ширина всплывающего окна. Значение можно игнорировать, если он находится за пределами допустимых границ.

Примечание.

Параметр authID действителен в течение сеанса проверки подлинности, время ожидания которого по умолчанию составляет 120 секунд.

Дополнительные сведения о параметрах см. в разделе Функция authenticate (AuthenticatePopUpParameters).

Добавление проверки подлинности во внешние браузеры

На следующем изображении обеспечивается поток для добавления проверки подлинности во внешние браузеры:

authenticate-OAuth

Добавление проверки подлинности во внешние браузеры

  1. 1. Инициация внешнего процесса аутентификации. Стороннее приложение вызывает функцию authentication.authenticate TeamsJS с isExternal параметром true, чтобы инициировать внешний процесс аутентификации входа.

    Переданный url объект содержит заполнители для {authId}, {oauthRedirectMethod}и {hostRedirectUrl}.

       authentication.authenticate({
      url: `${window.location.origin}/auth-start?oauthRedirectMethod={oauthRedirectMethod}&authId={authId}&hostRedirectUrl={hostRedirectUrl}&googleId=${googleId}`,
      isExternal: true
    }).then((result) => {
      this.getGoogleServerSideToken(result);
    }).catch((reason) => {
      console.log("failed" + reason);
      reject(reason);
    })

  2. Клиенты Teams открывают URL-адрес во внешнем браузере после автоматической замены заполнителей для oauthRedirectMethod, authIdи hostRedirectUrl подходящими значениями.

    Пример

     https://3p.app.server/auth?oauthRedirectMethod=deeplink&authId=1234567890&hostRedirectUrl=msteams://teams.microsoft.com/l/auth-callback?authId=1234567890&result={result}

  3. Сторонний сервер приложений отвечает. Сторонний сервер приложений получает и сохраняет с тремя следующими параметрами url запроса:

    Параметр Описание
    oauthRedirectMethod Указывает, как стороннее приложение должно отправлять клиенту ответ на запрос проверки подлинности, используя одно из двух значений: прямую ссылку или страницу.
    authId Команда teams с идентификатором запроса создает для этого конкретного запроса проверки подлинности, который необходимо отправить клиенту через прямую ссылку.
    hostRedirectUrl Прямая ссылка включает схему URL-адресов инициирующего клиента для перенаправления после проверки подлинности.

    Совет

    Приложение может маршалировать authId, oauthRedirectMethodи hostRedirectUrl в параметре запроса OAuth state при создании URL-адреса входа для OAuthProvider. Содержит state переданные authId, oauthRedirectMethodи hostRedirectUrl, если OAuthProvider перенаправляется на сервер, а приложение использует значения для отправки ответа проверки подлинности обратно в инициирующий клиент, как описано на шаге 6.

  4. Сервер сторонних приложений перенаправляется на указанный url. Сторонний сервер приложений перенаправляется на страницу проверки подлинности поставщиков OAuth во внешнем браузере. — redirect_uri это выделенный маршрут на сервере приложений. Вы можете зарегистрировать redirect_uri в консоли разработчика поставщиков OAuth как статический, параметры должны быть отправлены через объект state.

    Пример

    https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https://3p.app.server/authredirect&state={"authId":"…","oauthRedirectMethod":"…","hostRedirectUrl":"_"}&client_id=…    &response_type=code&access_type=offline&scope= …

  5. 5. Вход во внешний браузер. Поставщики OAuth перенаправляют обратно на redirect_uri объект с кодом проверки подлинности и объектом состояния.

  6. Сторонний сервер приложений обрабатывает ответ и проверяет oauthRedirectMethod, который возвращается от внешнего поставщика OAuth в объекте состояния, чтобы определить, нужно ли возвращать ответ через прямую ссылку обратного вызова проверки подлинности или через веб-страницу, которая вызывает notifySuccess().

    if (state.oauthRedirectMethod === 'deeplink') {
   const clientRedirectUrl: string = state.hostRedirectUrl.replace('{result}', req.query.code)
   return res.redirect(clientRedirectUrl)
}
else {
// continue redirecting to a web-page that will call notifySuccess() – usually this method is used in Teams-Web
…

    Например, в мобильном клиенте Teams измененные hostRedirectUrl результаты будут следующими:

    return res.redirect(`msteams://teams.microsoft.com/l/auth-callback?authId=${state.authId}&result=${req.query.code}`)

    Указанное значение hostRedirectUrl зависит от клиента, который инициирует внешний поток проверки подлинности.

  7. Teams вызывает обратный вызов успешного выполнения и отправляет результат (код проверки подлинности) в стороннее приложение. Приложение получает код в обратном вызове и использует код для получения маркера, а затем сведений о пользователе и обновления пользовательского интерфейса.

    successCallback: function (result) { 
… 
}

См. также