Use logon único (SSO) ou CORS (compartilhamento de recursos entre origens) em seu suplemento do Office baseado em eventos ou com relatórios de spam

Quando um suplemento implementa a ativação baseada em eventos ou relatórios de spam integrados, os eventos são executados em um tempo de execução separado. Para configurar o SSO (logon único) ou solicitar dados externos por meio de CORS (compartilhamento de recursos entre origens) nesses suplementos, você deve configurar um URI conhecido. Por meio desse recurso, o Office poderá identificar os suplementos, incluindo seus arquivos JavaScript, que dão suporte a solicitações de SSO ou CORS.

Observação

As etapas neste artigo se aplicam somente a suplementos executados no Excel, PowerPoint ou Word no Windows, ou ao Outlook clássico no Windows. Isso ocorre porque eles usam um arquivo JavaScript, enquanto esses aplicativos no Mac, na Web e no novo Outlook no Windows usam um arquivo HTML que faz referência ao mesmo arquivo JavaScript. Para saber mais, consulte Ativar suplementos com eventos e Implementar um suplemento integrado de relatório de spam.

Listar suplementos permitidos em um URI conhecido

Para listar quais suplementos podem funcionar com SSO ou CORS, crie um arquivo JSON que identifique cada arquivo JavaScript para cada suplemento. Em seguida, hospede esse arquivo JSON em um URI conhecido. Um URI conhecido permite a especificação de todos os arquivos JS hospedados que estão autorizados a obter tokens para a origem da web atual. Isso garante que o proprietário da origem tenha controle total sobre quais arquivos JavaScript hospedados devem ser usados em um suplemento e quais não são, evitando vulnerabilidades de segurança em torno da representação, por exemplo.

O exemplo a seguir mostra como configurar o SSO ou o CORS para dois suplementos (uma versão principal e uma versão beta). Você pode listar quantos suplementos forem necessários, dependendo de quantos você fornecer do seu servidor Web.

{
    "allowed":
    [
        "https://addin.contoso.com:8000/main/js/autorun.js",
        "https://addin.contoso.com:8000/beta/js/autorun.js"
    ]
}

Hospede o arquivo JSON em um local nomeado .well-known no URI na raiz da origem. Por exemplo, se a origem for https://addin.contoso.com:8000/, o URI conhecido será https://addin.contoso.com:8000/.well-known/microsoft-officeaddins-allowed.json. Para esclarecimento, esse arquivo deve ser hospedado em seu Suplemento da Web do Office, não no servidor Web para o qual você está tentando fazer uma solicitação CORS. Consulte o exemplo de Outlook-Add-in-SSO-events para obter um exemplo usando o local recomendado.

A origem refere-se a um padrão de esquema + subdomínio + domínio + porta. O nome do local deve ser .well-known, e o nome do arquivo de recurso deve ser microsoft-officeaddins-allowed.json. Esse arquivo deve conter um objeto JSON com um atributo chamado allowed cujo valor é uma matriz de todos os arquivos JavaScript autorizados para SSO para seus respectivos suplementos.

Depois de configurar o URI conhecido, se o suplemento implementar SSO, você poderá chamar a API getAccessToken() para obter um token de acesso com a identidade do usuário.

Importante

Office.auth.getAccessToken só tem suporte no Outlook clássico no Windows a partir da versão 2111 (Build 14701.20000). Se você precisar usar o SSO herdado do Office em versões mais antigas do Outlook, chame OfficeRuntime.auth.getAccessToken seu suplemento baseado em eventos ou de relatório de spam. Essa API fornece a mesma funcionalidade e tem suporte em todas as versões do cliente que dão suporte à ativação baseada em eventos, relatórios de spam integrados e SSO herdado do Office.

Confira também

  • Last updated on