Usar provedores OAuth externos

  • Artigo

Observação

Este tópico reflete a versão 2.0.x da biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Se você estiver usando uma versão anterior, consulte a visão geral da biblioteca do TeamsJS para obter diretrizes sobre as diferenças entre o TeamsJS mais recente e as versões anteriores.

Você pode dar suporte a provedores OAuth externos ou de terceiros, como Google, GitHub, LinkedIn e Facebook usando a API atualizadaauthenticate():

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

Adicione os seguintes valores à authenticate() API para dar suporte a provedores OAuth externos:

  • Parâmetro isExternal
  • Três valores de espaço reservado no parâmetro existente url

A tabela a seguir fornece a lista de parâmetros de authenticate() API (AuthenticatePopUpParameters) e funções junto com suas descrições:

Parâmetro Descrição
isExternal O tipo de parâmetro é Booliano, que indica que a janela de autenticação é aberta em um navegador externo.
height A altura preferencial para o pop-up. O valor pode ser ignorado se estiver fora dos limites aceitáveis.
url
A URL do servidor de aplicativo de terceiros para o pop-up de autenticação, com os três espaços reservados a seguir:

- oauthRedirectMethod: Espaço reservado de aprovação em {}. A plataforma teams substitui esse espaço reservado por um link profundo ou página da Web, que atualiza o servidor de aplicativo se a chamada vem de uma plataforma móvel.

- authId: UUID (identifer exclusivo universal) substitui esse espaço reservado. O servidor de aplicativo o usa para manter a sessão.

- hostRedirectUrl: passe espaço reservado em {}. A plataforma e o cliente atuais substituem esse espaço reservado por uma URL de redirecionamento, que redireciona o usuário para o cliente correto após a conclusão da autenticação.
width A largura preferencial para o pop-up. O valor pode ser ignorado se estiver fora dos limites aceitáveis.

Observação

O authID parâmetro é válido pela duração da sessão de auth, que tem um tempo limite padrão de 120 segundos.

Para obter mais informações sobre parâmetros, consulte a função authenticatePopUpParameters .

Adicionar autenticação a navegadores externos

A imagem a seguir fornece o fluxo para adicionar autenticação a navegadores externos:

authenticate-OAuth

Para adicionar autenticação a navegadores externos

  1. Inicie o processo de entrada de autenticação externo. O aplicativo de terceiros chama a função authentication.authenticate TeamsJS com isExternal definida como true para iniciar o processo de logon externo.

    O passado url contém espaços reservados para {authId}, {oauthRedirectMethod}e {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. Os clientes do Teams abrem a URL em um navegador externo depois de substituir automaticamente os espaços reservados por oauthRedirectMethod, authIde hostRedirectUrl por valores adequados.

    Exemplo

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

  3. O servidor de aplicativo de terceiros responde. O servidor de aplicativo de terceiros recebe e salva o url com os três parâmetros de consulta a seguir:

    Parâmetro Descrição
    oauthRedirectMethod Indica como o aplicativo de terceiros deve enviar a resposta da solicitação de autenticação de volta ao cliente, com um dos dois valores: link profundo ou página.
    authId O Teams de id de solicitação cria para essa solicitação de autenticação específica que precisa ser enviada de volta ao cliente por meio de um link profundo.
    hostRedirectUrl O link profundo inclui o esquema de URL do cliente iniciador para redirecionar após a autenticação.

    Dica

    O aplicativo pode empacotar authId, oauthRedirectMethode hostRedirectUrl no parâmetro de consulta OAuth state ao gerar a URL de logon para o OAuthProvider. O state contém o passado authId, oauthRedirectMethode hostRedirectUrl, quando OAuthProvider redireciona para o servidor e o aplicativo usa os valores para enviar a resposta de autenticação de volta para o cliente iniciador, conforme descrito na etapa 6.

  4. O servidor de aplicativo de terceiros redireciona para o especificado url. O servidor de aplicativo de terceiros redireciona para a página de autenticação de provedores OAuth no navegador externo. A redirect_uri é uma rota dedicada no servidor de aplicativo. Você pode registrar a redirect_uri no console de desenvolvimento do provedor OAuth como estático, os parâmetros precisam ser enviados por meio do objeto de estado.

    Exemplo

    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. Entre no navegador externo. Os provedores OAuth redirecionam de volta para o redirect_uri com o código de auth e o objeto state.

  6. O servidor de aplicativo de terceiros manipula a resposta e verifica oauthRedirectMethod, que é retornada do provedor OAuth externo no objeto de estado para determinar se a resposta precisa ser retornada por meio do link profundo de retorno de chamada de auth ou por meio da página da Web que chama 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
…

    Por exemplo, no cliente móvel do Teams, o modificado resulta hostRedirectUrl no seguinte:

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

    O valor fornecido de hostRedirectUrl depende do cliente que inicia o fluxo de autenticação externa.

  7. O Teams chama o retorno de chamada de sucesso e envia o resultado (código de auth) para o aplicativo de terceiros. O aplicativo recebe o código no retorno de chamada de êxito e usa o código para recuperar o token, depois as informações do usuário e atualizar a interface do usuário.

    successCallback: function (result) { 
… 
}

Confira também