Utilizar proveedores OAuth externos

  • Artículo

Nota:

En este tema se refleja la versión 2.0.x de la biblioteca cliente JavaScript de Microsoft Teams (TeamsJS). Si usa una versión anterior, consulte la introducción a la biblioteca TeamsJS para obtener instrucciones sobre las diferencias entre la versión más reciente de TeamsJS y las versiones anteriores.

Puede admitir proveedores de OAuth externos o de terceros, como Google, GitHub, LinkedIn y Facebook mediante la API actualizadaauthenticate():

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

Agregue los siguientes valores a la authenticate() API para admitir proveedores de OAuth externos:

  • parámetro isExternal
  • Tres valores de marcador de posición en el parámetro existente url

En la tabla siguiente se proporciona la lista de parámetros de authenticate() API (AuthenticatePopUpParameters) y funciones junto con sus descripciones:

Parámetro Descripción
isExternal El tipo de parámetro es booleano, que indica que la ventana de autenticación se abre en un explorador externo.
height Alto preferido para el elemento emergente. El valor se puede omitir si está fuera de los límites aceptables.
url
Dirección URL del servidor de aplicaciones de terceros para el elemento emergente de autenticación, con los tres marcadores de posición de parámetro siguientes:

- oauthRedirectMethod: pasar marcador de posición en {}. La plataforma Teams reemplaza este marcador de posición por un vínculo profundo o una página web, que actualiza el servidor de aplicaciones si la llamada procede de una plataforma móvil.

- authId: UUID (identificador único universal) reemplaza este marcador de posición. El servidor de aplicaciones lo usa para mantener la sesión.

- hostRedirectUrl: pase el marcador de posición en {}. La plataforma y el cliente actuales reemplazan este marcador de posición por una dirección URL de redireccionamiento, que redirige al usuario al cliente correcto después de completar la autenticación.
width Ancho preferido para el elemento emergente. El valor se puede omitir si está fuera de los límites aceptables.

Nota:

El authID parámetro es válido durante la sesión de autenticación, que tiene un tiempo de espera predeterminado de 120 segundos.

Para obtener más información sobre los parámetros, vea autenticar (AuthenticatePopUpParameters) función.

Agregar autenticación a exploradores externos

La siguiente imagen proporciona el flujo para agregar autenticación a exploradores externos:

authenticate-OAuth

Para agregar autenticación a exploradores externos

  1. Inicie el proceso de inicio de sesión de autenticación externo. La aplicación de terceros llama a la función authentication.authenticate TeamsJS con isExternal establecido como true para iniciar el proceso de inicio de sesión de autenticación externo.

    El pasado url contiene marcadores de posición para {authId}, {oauthRedirectMethod}y {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. Los clientes de Teams abren la dirección URL en un explorador externo después de reemplazar automáticamente los marcadores de posición de oauthRedirectMethod, authIdy hostRedirectUrl con valores adecuados.

    Ejemplo

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

  3. Responde el servidor de aplicaciones de terceros. El servidor de aplicaciones de terceros recibe y guarda con los tres parámetros url de consulta siguientes:

    Parámetro Descripción
    oauthRedirectMethod Indica cómo la aplicación de terceros debe enviar la respuesta de la solicitud de autenticación al cliente, con uno de los dos valores: vínculo profundo o página.
    authId Request-id Teams crea para esta solicitud de autenticación específica que debe devolverse al cliente a través de un vínculo profundo.
    hostRedirectUrl El vínculo profundo incluye el esquema de dirección URL del cliente que inicia el redireccionamiento después de la autenticación.

    Sugerencia

    La aplicación puede serializar authId, oauthRedirectMethody hostRedirectUrl en el parámetro de consulta de OAuth state al generar la dirección URL de inicio de sesión para OAuthProvider. state contiene los valores pasados authId, oauthRedirectMethody hostRedirectUrl, cuando OAuthProvider redirige al servidor y la aplicación usa los valores para enviar la respuesta de autenticación al cliente que inicia, como se describe en el paso 6.

  4. El servidor de aplicaciones de terceros redirige a urlespecificado. El servidor de aplicaciones de terceros redirige a la página de autenticación de proveedores de OAuth en el explorador externo. redirect_uri es una ruta dedicada en el servidor de aplicaciones. Puede registrar redirect_uri en la consola de desarrollo de proveedores de OAuth como estático; los parámetros deben enviarse a través del objeto de estado.

    Ejemplo

    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. Inicie sesión en el explorador externo. Los proveedores de OAuth redirigen de nuevo a redirect_uri con el código de autenticación y el objeto de estado.

  6. El servidor de aplicaciones de terceros controla la respuesta y comprueba oauthRedirectMethod, que se devuelve desde el proveedor de OAuth externo en el objeto de estado para determinar si la respuesta debe devolverse a través del vínculo profundo auth-callback o a través de la página web que llama notifySuccess()a .

    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
…

    Por ejemplo, en el cliente móvil de Teams, los resultados modificados hostRedirectUrl son los siguientes:

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

    El valor proporcionado de hostRedirectUrl depende del cliente que inicia el flujo de autenticación externa.

  7. Teams llama a la devolución de llamada correcta y envía el resultado (código de autenticación) a la aplicación de terceros. La aplicación recibe el código en la devolución de llamada correcta y usa el código para recuperar el token y, a continuación, la información del usuario y actualizar la interfaz de usuario.

    successCallback: function (result) { 
… 
}

Vea también