Aplicativos do Azure AD para Suplementos do Office e SSO
As ferramentas de desenvolvedor fornecidas pela Microsoft para criar suplementos do Office com ASP.NET ou Node.js utilitários incluídos para registrar o aplicativo Microsoft Entra necessário. Essa ferramenta, configure-sso, simplifica não apenas o registro do aplicativo, mas também a configuração da estação de trabalho do desenvolvedor.
Nesta unidade, você aprenderá a criar o registro do aplicativo Microsoft Entra para um Suplemento do Office que implementa o SSO (logon único). Você também aprenderá algumas práticas recomendadas pela Microsoft ao criar Suplementos do Office que implementam o SSO.
Registrar um aplicativo Microsoft Entra para o SSO de suplemento do Office
Vamos examinar os requisitos para registrar um aplicativo Microsoft Entra usado por um Suplemento do Office que implementa o SSO.
Microsoft Entra registro de aplicativo
A primeira etapa é registrar um aplicativo Microsoft Entra no centro de administração Microsoft Entra (https://aad.portal.azure.com).
Ao registrar o aplicativo, verifique se você define os tipos de conta com suporte como contas em qualquer aplicativo de diretório organizacional (Qualquer diretório Microsoft Entra – Multilocatário).
Importante
Os aplicativos se Suplemento do Office não podem ser de um único locatário; eles devem ser de multilocatário.
Autenticação
A próxima etapa é definir as configurações de autenticação do aplicativo.
Seu aplicativo deve ter pelo menos dois URIs de Redirecionamento listados:
- página de suplemento, como a URL da página HTML do painel de tarefas
- página de fallback, como a página fallbackauthdialog.html
Ambas as opções de tokens de fluxo híbrido e global implícito devem ser habilitadas, pois os Suplementos do Office são normalmente aplicativos do lado do cliente:
- Tokens de acesso (usados para fluxos implícitos)
- Tokens de ID (usados para fluxos implícitos e híbridos)
Permissões de API
Outra parte importante do aplicativo Microsoft Entra são as permissões necessárias para funcionar.
Cada aplicativo precisa receber as permissões OpenID openid e profile. Algumas bibliotecas exigem permissões extras. Por exemplo, a Biblioteca de Autenticação da Microsoft para .NET requer a permissão office_access.
Se o suplemento precisar de alguma permissão para o Microsoft Graph, elas também devem ser adicionadas aqui.
Embora não seja necessário, ao registrar o aplicativo, como administrador você pode consentir essas permissões previamente em nome de todos os usuários do locatário. Isso simplifica o fluxo de autenticação para que os usuários não precisem consentir para que o suplemento possa usá-lo pela primeira vez.
Expor uma API
Seu aplicativo deve expor suas próprias permissões para Microsoft Entra ID e clientes do Office. Na tela Expor uma API , defina o URI da ID do Aplicativo. Por padrão, ele é api://<APP_ID>, mas você deve atualizá-lo para incluir o domínio onde a base de código do suplemento está hospedada.
Inclua a URL antes da parte <APP_ID> do URI. Por exemplo: api://addin.contoso.com/<APP_UD>. Esse domínio deve corresponder ao domínio em que todos os recursos definidos no arquivo manifest.xml do suplemento são atendidos.
A próxima etapa é expor uma permissão, também chamada de escopo. Esse escopo, access_as_user, será usado pelos clientes do Office para indicar que eles podem agir em nome do usuário conectado ao fornecer o token de inicialização para o Microsoft Graph ao iniciar o fluxo OAuth2 On-Behalf-Of.
Por fim, você deve conceder essa permissão a todos os aplicativos cliente do Office. Isso configura o aplicativo para confiar em todos os aplicativos clientes do Office para obter a permissão access_as_user.
Cada tipo de cliente do Office é representado por uma ID exclusiva. Certifique-se de incluir o aplicativo a seguir. Ao fazer isso, certifique-se de habilitar a permissão access_as_user:
ea5a67f6-b6f3-4338-b240-c655ddc3cc8e(Microsoft Office)
Importante
O serviço ea5a67f6-b6f3-4338-b240-c655ddc3cc8e é uma autorização de grupo que inclui todos os outros hosts do Office, portanto, você pode apenas incluir este em vez de listar cada um dos seguintes aplicativos individuais:
d3590ed6-52b3-4102-aeff-aad2292ab01c(Microsoft Office)57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office na Web)08e18876-6177-487e-b8b5-cf950c1e598c(Office na Web)bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook na Web)93d53678-613d-4013-afc1-62e9e444a0a5(Office na Web)
O último serviço listado acima, 93d53678-613d-4013-afc1-62e9e444a0a5, é um novo serviço de SSO introdução em janeiro de 2022.
Práticas recomendadas no desenvolvimento de SSO de suplementos do Office
A Microsoft recomenda o seguinte ao criar suplementos do Office que implementam o SSO.
Use allowConsentPrompt se você precisar apenas do perfil do usuário
Em alguns cenários, o suplemento do Office pode usar o SSO apenas para obter o perfil do usuário. Nesses casos, considere substituir o comportamento padrão do processo de entrada, passando a opção { allowConsentPrompt: true } ao chamar getAccessToken() no SDK do Office.js.
O valor padrão da propriedade é false. Essa propriedade permite ao Office obter silenciosamente um token de acesso ou através de um consentimento interativo, se necessário. Quando a propriedade estiver definida como false, se o Office não conseguir obter um token porque o usuário não consentiu, ele receberá um erro descritivo.
No entanto, quando definido como true, o Office exibirá um consentimento interativo quando não conseguir obter silenciosamente um token de acesso.
Importante
Lembre-se de que o Office só pode solicitar o consentimento do usuário para a permissão profile OpenID, e não qualquer permissão do Microsoft Graph.
Implementar um método de autorização de fallback
A autenticação e a autorização com suplementos do Office nem sempre são um caminho direto para o sucesso. Como este módulo explica, há vários cenários em que o suplemento pode falhar durante o processo de autorização.
Isso pode incluir o cenário em que o usuário não consentiu as permissões do Microsoft Graph necessárias para o suplemento. Nesse caso, é melhor se o suplemento puder falhar rapidamente para solicitar ao usuário logo no início para que ele consenta as permissões necessárias. Essa é uma abordagem melhor do que esperar até mais tarde no processo para notificar o usuário.
Implementar a abordagem "fail fast" para autorização
Repetindo a seção anterior, lembre-se do que você aprendeu em uma lição anterior. Quando o Office solicita o token de inicialização, ele pode incluir a opção de autorização { forGraphAccess: true } ao chamar getAccessToken() no SDK do Office.js.
Quando Microsoft Entra ID recebe isso, ele faz outra marcar para ver se o usuário já consentiu com as permissões solicitadas do Microsoft Graph. Se não tiverem, Microsoft Entra ID responderá com um código de erro específico que seu suplemento pode manipular no sistema de autorização de fallback para solicitar que o usuário consenta com as permissões do Microsoft Graph.
Pré-autorizar todos os clientes do Office com seu suplemento
Conforme mostrado nesta unidade, você pode pré-autorizar seu registro de aplicativo Microsoft Entra usado pelo suplemento do Office para confiar em todos os aplicativos cliente do Office. Isso inclui todos os clientes da área de trabalho, móveis e web do Office.
Isso garante que o suplemento funcione no número máximo de cenários.