Usar provedores OAuth externos
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:
Para adicionar autenticação a navegadores externos
Inicie o processo de entrada de autenticação externo. O aplicativo de terceiros chama a função
authentication.authenticate
TeamsJS comisExternal
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); })
Os clientes do Teams abrem a URL em um navegador externo depois de substituir automaticamente os espaços reservados por
oauthRedirectMethod
,authId
ehostRedirectUrl
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}
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
,oauthRedirectMethod
ehostRedirectUrl
no parâmetro de consulta OAuthstate
ao gerar a URL de logon para o OAuthProvider. Ostate
contém o passadoauthId
,oauthRedirectMethod
ehostRedirectUrl
, 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.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. Aredirect_uri
é uma rota dedicada no servidor de aplicativo. Você pode registrar aredirect_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= …
Entre no navegador externo. Os provedores OAuth redirecionam de volta para o
redirect_uri
com o código de auth e o objeto state.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 chamanotifySuccess()
.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.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
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários