Partilhar via

Solucionar problemas de mensagens de erro no logon único (SSO)

  • Artigo

Este artigo fornece algumas orientações sobre como solucionar problemas com o logon único (SSO) nos suplementos do Office e como fazer com que seu suplemento habilitado para SSO lide de forma robusta com os erros ou condições especiais.

Observação

A API de Logon Único é compatível com Word, Excel, Outlook e PowerPoint. Confira mais informações sobre os programas para os quais a API de logon único tem suporte no momento em Conjuntos de requisitos da IdentityAPI. Se estiver a trabalhar com um suplemento do Outlook, certifique-se de que ativa a Autenticação Moderna para o inquilino do Microsoft 365. Para obter informações sobre como fazê-lo, consulte Ativar ou desativar a autenticação moderna para o Outlook no Exchange Online.

Ferramentas de depuração

Recomendamos fortemente que você use uma ferramenta que possa interceptar e exibir as solicitações HTTP a partir de seu serviço Web do suplemento, além de respostas para ele, quando você estiver desenvolvendo. Alguns dos mais populares são:

Causas e tratamento dos erros do getAccessToken

Para acessar exemplos de tratamento de erro descritos nesta seção, confira:

13000

A API getAccessToken não é suportada pelo suplemento ou pela versão do Office.

  • A versão do Office não é compatível com o SSO. A versão necessária é a subscrição do Microsoft 365, em qualquer canal mensal.
  • O manifesto do suplemento está sem a seção WebApplicationInfo adequada.

O suplemento deverá responder a esse erro recorrendo a um sistema de autenticação de usuário alternativo. Para obter mais informações, confira Requisitos e Melhores Práticas.

13001

O utilizador não tem sessão iniciada no Office. Na maioria dos cenários, você deve evitar que esse erro apareça passando a opção allowSignInPrompt: true no parâmetro AuthOptions.

Mas pode haver exceções. Por exemplo, no caso de você desejar que o suplemento seja aberto com recursos que exijam um usuário conectado; mas somente se o usuário já estiver conectado ao Office. Se o utilizador não tiver sessão iniciada, pretende que o suplemento seja aberto com um conjunto alternativo de funcionalidades que não exijam que o utilizador tenha sessão iniciada. Nesse caso, essa é a lógica executada quando o suplemento inicia chamadas getAccessToken sem allowSignInPrompt: true. Use o erro 13001 como sinalizador para informar ao suplemento para apresentar o conjunto alternativo de recursos.

Outra opção é responder ao 13001 recorrendo a um sistema alternativo de autenticação de usuário. Isso conectará o usuário ao AAD, mas não o conectará ao Office.

Normalmente, este erro não ocorre no Office na Web. Se o cookie do utilizador expirar, Office na Web devolve o erro 13006. No entanto, se um utilizador aceder a Outlook na Web a partir do Firefox com a Proteção de Controlo Avançada ativada, ocorrerá o erro 13001.

13002

O usuário abortou a entrada ou o consentimento; por exemplo, escolhendo Cancelar no diálogo de consentimento.

  • Se o seu suplemento fornece funções que não exigem que o usuário esteja conectado (ou que tenha concedido o consentimento), seu código deve capturar esse erro e permitir que o suplemento permaneça em execução.
  • Se o suplemento exigir um usuário conectado que tenha dado consentimento, o código deverá exibir um botão de logon.

13003

Tipo de Usuário não suportado. O utilizador não tem sessão iniciada no Office com uma conta Microsoft válida, Microsoft 365 Education ou conta profissional. Isso pode acontecer se o Office funcionar com uma conta de domínio no local, por exemplo. O código deve retornar a um sistema alternativo de autenticação de usuário. No Outlook, este erro também poderá ocorrer se a autenticação moderna estiver desativada para o inquilino do utilizador no Exchange Online. Para obter mais informações, confira Requisitos e Melhores Práticas.

13004

Recurso inválido. (Este erro só deve ser visto no desenvolvimento.) O manifesto do suplemento não foi configurado corretamente. Atualize o manifesto. Para saber mais, confira Validar o manifesto de suplemento do Office. O problema mais comum é que o <elemento Recurso> (no <elemento WebApplicationInfo> ) tem um domínio que não corresponde ao domínio do suplemento. Embora a parte do protocolo do valor Resource deva ser “api” e não “https”, todas as outras partes do nome de domínio (incluindo a porta, se houver) devem ser as mesmas para o suplemento.

13005

Concessão inválida. Isso geralmente significa que o Office não foi pré-autorizado para o serviço Web do suplemento. Para obter mais informações, consulte Criar a aplicação de serviço e Registar um Suplemento do Office que utiliza o início de sessão único (SSO) com o plataforma de identidade da Microsoft. Isso também pode acontecer se o usuário não concedeu as permissões de aplicativo de serviço para o seu profile, ou se tiver revogado um consentimento. O código deve retornar a um sistema alternativo de autenticação de usuário.

Outra causa possível durante o desenvolvimento, é que o suplemento esteja usando o Internet Explorer e você um certificado autoassinado. (Para determinar que browser ou webview está a ser utilizado pelo suplemento, consulte Browsers e controlos webview utilizados pelos Suplementos do Office.)

13006

Erro do Cliente. Este erro somente aparece no Office na Web. Seu código deve sugerir que o usuário saia e reinicie a sessão do Office no navegador.

13007

A aplicação do Office não conseguiu obter um token de acesso para o serviço Web do suplemento.

13008

O usuário desencadeou uma operação que chama o getAccessToken antes de uma chamada anterior do getAccessToken concluída. Este erro somente aparece no Office na Web. O código deve solicitar ao usuário que repita a operação após a conclusão da operação anterior.

13010

O utilizador está a executar o suplemento no Office no Microsoft Edge. O domínio do Microsoft 365 do utilizador e o login.microsoftonline.com domínio encontram-se numa zona de segurança diferente nas definições do browser. Este erro somente aparece no Office na Web. Se esse erro for retornado, o usuário já terá visto uma mensagem explicando o erro e vinculando a uma página sobre como alterar a configuração da zona. Se o seu suplemento fornece funções que não exigem que o usuário esteja conectado, o código deve capturar esse erro e permitir que o suplemento permaneça em execução.

13012

Existem várias causas possíveis.

  • O suplemento está em execução em uma plataforma não dá suporte à API getAccessToken. Por exemplo, não é suportado no iPad. Veja também Conjuntos de requisitos da API de Identidade.
  • O documento do Office foi aberto a partir do separador Ficheiros de um canal do Teams com a opção Editar no Teams no menu pendente Abrir . A getAccessToken API não é suportada neste cenário.
  • A opção forMSGraphAccess foi passada na chamada ao getAccessToken e o usuário obteve o suplemento no AppSource. Nesse cenário, o administrador do locatário não deu o consentimento ao suplemento para os escopos (permissões) do Microsoft Graph necessários. Uma nova chamada ao getAccessToken com o allowConsentPrompt, não resolverá o problema porque o Office poderá solicitar ao usuário o consentimento apenas para o escopo AAD do profile.

O código deve retornar a um sistema alternativo de autenticação de usuário.

No desenvolvimento, o suplemento é sideloaded no Outlook e a opção forMSGraphAccess foi passada na chamada ao getAccessToken.

13013

O getAccessToken foi chamado demasiadas vezes num curto espaço de tempo, pelo que o Office limitava a chamada mais recente. Normalmente, isto é causado por um ciclo infinito de chamadas para o método . Existem cenários em que é aconselhável recuperar o método. No entanto, o código deve utilizar um contador ou uma variável de sinalizador para garantir que o método não é recolhido repetidamente. Se o mesmo caminho de código "repetir" estiver novamente em execução, o código deverá reverter para um sistema alternativo de autenticação de utilizador. Para obter um exemplo de código, veja como a retryGetAccessToken variável é utilizada em HomeES6.js ou ssoAuthES6.js.

50001

Este erro (que não é específico de getAccessToken) pode indicar que o browser tem uma cópia antiga dos ficheiros office.js em cache. Quando estiver a desenvolver, limpe a cache do browser. Outra possibilidade é que a versão do Office não seja suficientemente recente para suportar o SSO. No Windows, a versão mínima é a Versão 1911 (Compilação 12215.20006). No Mac, é a Versão 16.32 (19102902).

Em um suplemento de produção, o suplemento deverá responder a esse erro recorrendo a um sistema de autenticação de usuário alternativo. Para obter mais informações, confira Requisitos e Melhores Práticas.

Erros no lado do servidor do Azure Active Directory

Para exemplos do tratamento de erro descritos nesta seção, confira:

Erros no acesso condicional/autenticação multifatorial

Em determinadas configurações de identidade no AAD e no Microsoft 365, é possível que alguns recursos acessíveis com o Microsoft Graph exijam autenticação multifator (MFA), mesmo quando o inquilino do Microsoft 365 do utilizador não. Quando o AAD recebe uma solicitação de um token para o recurso protegido por MFA, através do fluxo Em Nome De, ele retorna ao serviço Web do seu suplemento uma mensagem JSON que contém uma propriedade claims. A propriedade de reivindicações tem informações sobre quais outros fatores de autenticação são necessários.

O código deve testar essa propriedade de claims. Dependendo da arquitetura do seu suplemento, você poderá testá-lo no lado do cliente ou testá-lo no lado do servidor e retransmiti-lo ao cliente. Você precisa dessa informação no cliente porque o Office processa a autenticação para os suplementos de SSO. Se você retransmiti-lo do lado do servidor, a mensagem para o cliente pode ser um erro (como 500 Server Error ou 401 Unauthorized) ou estar no corpo de uma resposta de sucesso (como 200 OK). Em ambos os casos, o retorno de chamada (falha ou sucesso) da chamada AJAX do lado do cliente do seu código para a API da Web do seu suplemento deve testar essa resposta.

Independentemente da sua arquitetura, se o valor de afirmações tiver sido enviado do AAD, o código deve recuperar getAccessToken e transmitir a opção authChallenge: CLAIMS-STRING-HERE no options parâmetro . Quando o AAD vê esta cadeia, pede ao utilizador os fatores adicionais e, em seguida, devolve um novo token de acesso que será aceite no fluxo em nome de.

Se o AAD não tiver um registro de que o consentimento (para o recurso Microsoft Graph) foi concedido ao suplemento pelo usuário (ou administrador do locatário), o AAD enviará uma mensagem de erro ao seu serviço Web. Seu código deve dizer ao cliente (no corpo de uma resposta 403 Forbidden, por exemplo).

Se o suplemento precisar de escopos do Microsoft Graph que só possam ser consentidos por um administrador, seu código deverá gerar um erro. Se os únicos escopos necessários puderem ser consentidos pelo usuário, o código deverá retornar a um sistema alternativo de autenticação de usuário.

Erros de escopos (permissões) inválidos ou ausentes

Esse tipo de erro só deve aparecer no desenvolvimento.

Erro de audiência inválido no token de acesso do Microsoft Graph

Seu código do lado do servidor deve enviar uma resposta 403 Forbidden ao cliente que deve apresentar uma mensagem amigável ao usuário e, possivelmente, também registrar o erro no console ou gravá-lo em um registro.