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 você estiver trabalhando com um suplemento do Outlook, habilite a Autenticação Moderna para a locação do Microsoft 365. Para obter informações sobre como fazer isso, consulte Habilitar ou desabilitar a autenticação moderna para o Outlook em 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. Duas das ferramentas 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 é compatível 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 assinatura 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 usuário não iniciou sessão 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 usuário não estiver conectado, e você deseja que o suplemento seja aberto com um conjunto alternativo de recursos que não exijam que o usuário esteja. 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.

Este erro nunca aparece no Office na Web. Se os cookies do usuário expirarem, o Office na Web retornará o erro 13006.

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 usuário não está conectado ao Office com uma conta microsoft válida ou Microsoft 365 Education ou conta de trabalho. 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, esse erro também pode ocorrer se a autenticação moderna estiver desabilitada para o locatário do usuário em Exchange Online. Para obter mais informações, confira Requisitos e Melhores Práticas.

13004

Recurso inválido. (Esse erro só deve ser visto no desenvolvimento.) O manifesto de 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 Resource> (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, confira Criar o aplicativo de serviço e Registrar o suplemento com o ponto de extremidade v2.0 do Azure AD. 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 qual navegador ou visão da Web está sendo usado pelo suplemento, consulte Navegadores e controles webview usados 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

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

  • Se ocorrer este erro durante o desenvolvimento, certifique-se de que o registro e o manifesto do suplemento especifiquem as permissões de profile (e a permissão de openid, se estiver usando o MSAL.NET). Para mais informações, confira Registrar o suplemento com o ponto de extremidade do Microsoft Azure AD v2.0.
  • Na produção, uma incompatibilidade de conta pode causar esse erro. Por exemplo, se o usuário tentar entrar com uma MSA (conta pessoal da Microsoft) quando uma conta de trabalho ou de estudante era esperada. Para esses casos, seu código deve voltar para um sistema alternativo de autenticação de usuário. Para obter mais informações sobre tipos de conta, consulte Tipos de identidade e conta para aplicativos de um e vários locatários

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 usuário está executando o suplemento no Office no Microsoft Edge. O domínio microsoft 365 do usuário e o login.microsoftonline.com domínio estão em diferentes zonas de segurança nas configurações do navegador. 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

Há várias causas possíveis.

  • O suplemento está em execução em uma plataforma não dá suporte à API getAccessToken. Por exemplo, ele não é suportado no iPad. Consulte também conjuntos de requisitos da API de Identidade.
  • O documento do Office foi aberto na guia Arquivos de um canal do Teams usando a opção Editar no Teams no menu suspenso Abrir . Não getAccessToken há suporte para a API nesse 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 muitas vezes em um curto período de tempo, então o Office restringiu a chamada mais recente. Isso geralmente é causado por um loop infinito de chamadas para o método. Há cenários ao lembrar que o método é aconselhável. No entanto, seu código deve usar um contador ou uma variável de sinalizador para garantir que o método não seja lembrado repetidamente. Se o mesmo caminho de código de "repetição" estiver sendo executado novamente, o código deverá voltar para um sistema alternativo de autenticação de usuário. Para obter um exemplo de código, consulte como a retryGetAccessToken variável é usada em HomeES6.js ou ssoAuthES6.js.

50001

Este erro (que não é específico de getAccessToken) pode indicar que o navegador colocou um cópia antiga dos arquivos office.js em cache. Quando você estiver desenvolvendo, limpe o cache do navegador. Também é possível que a versão do Office não esteja suficientemente recente para dar suporte à SSO. No Windows, o build mínimo é 16.0.12215.20006. No Mac, é 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 MFA (autenticação multifator), mesmo quando o aluguel do Microsoft 365 do usuário 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 de sua arquitetura, se o valor de declarações tiver sido enviado do AAD, seu código deverá recordar getAccessToken e passar a opção authChallenge: CLAIMS-STRING-HERE no options parâmetro. Quando o AAD vir essa string, ele solicitará ao usuário os fatores adicionais e retornará um novo token de acesso que será aceito 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.

  • Seu código do lado do servidor deve enviar a resposta 403 Forbidden ao cliente, que deve registrar o erro no console ou gravá-lo em um log.
  • Verifique se a seção de Escopos do manifesto do suplemento especifica todas as permissões necessárias. E certifique-se de que seu registro do serviço Web do suplemento especifique as mesmas permissões. Verifique também os erros de ortografia. Para mais informações, confira Registrar o suplemento com o ponto de extremidade do Microsoft Azure AD v2.0.

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.