Habilitar o login único (SSO) em um Suplemento do Office

Os usuários entrarão no Office usando sua conta pessoal da Microsoft ou sua conta de trabalho ou Microsoft 365 Education. Aproveite isso e use o SSO (login único) para autenticar e autorizar o usuário ao seu suplemento sem exigir que ele entre uma segunda vez.

Imagem mostrando o processo de logon de um suplemento.

Como o SSO funciona em tempo de execução

O diagrama a seguir mostra como funciona o processo de SSO. Os elementos azuis representam o Office ou a plataforma de identidade da Microsoft. Os elementos cinza representam o código que você escreve e incluem o código ao lado do cliente (painel de tarefas) e o código ao lado do servidor no seu suplemento.

Diagrama que mostra o processo de SSO.

  1. No suplemento, seu código JavaScript chama a API do Office.js getAccessToken. Se o usuário já estiver conectado ao Office, o host do Office retornará o token de acesso com as declarações do usuário conectado.
  2. Se o usuário não estiver conectado, o aplicativo host do Office abrirá uma caixa de diálogo para o usuário entrar. O Office redireciona para a plataforma de identidade da Microsoft para concluir o processo de entrada.
  3. Se essa for a primeira vez que o usuário atual usar o seu suplemento, será solicitado que ele consinta.
  4. O aplicativo host do Office solicita o token de acesso da plataforma de identidade da Microsoft para o usuário atual.
  5. O plataforma de identidade da Microsoft retorna o token de acesso ao Office. O Office armazenará o token no seu nome para que futuras chamadas do getAccessToken retornem ao token armazenado em cache.
  6. O aplicativo host do Office retorna o token de acesso ao suplemento como parte do objeto de resultado retornado pela getAccessToken chamada.
  7. O token é um token de acesso e um token de identidade. Você pode usá-lo como um token de identidade para analisar e examinar as declarações sobre o usuário, como o nome e o endereço de e-mail do usuário.
  8. Opcionalmente, o suplemento pode usar o token como um token de acesso para fazer solicitações HTTPS autenticadas nas APIs ao lado do servidor. Como o token de acesso contém declarações de identidade, o servidor pode armazenar informações associadas à identidade do usuário; como as preferências do usuário.

Requisitos e as práticas recomendadas

Não armazenar o token de acesso em cache

Nunca armazene em cache ou armazene o token de acesso no código ao lado do cliente. Sempre chame o getAccessToken quando precisar de um token de acesso. O Office armazenará em cache o token de acesso (ou solicitará um novo se ele tiver expirado). Isso ajudará a evitar o vazamento acidental do token do seu suplemento.

Habilitar a autenticação moderna do Outlook

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.

Implementar um sistema de autenticação de fallback

Você não deve confiar no SSO como único método do suplemento de autenticação. Devem implementar um sistema de autenticação alternativo que o suplemento possa se enquadrar em determinadas situações de erro. Por exemplo, se o seu suplemento for carregado em uma versão mais antiga do Office que não oferece suporte ao SSO, a getAccessToken chamada falhará.

Quanto aos suplementos do Excel, Word e PowerPoint, normalmente você vai querer voltar a usar a plataforma de identidade da Microsoft. Para obter mais informações, consulte Autenticar com a plataforma de identidade da Microsoft.

Quanto aos suplementos do Outlook, há um sistema de fallback recomendado. Para mais informações, confira Cenário: implementar o logon único no serviço em um Suplemento do Outlook.

Você também pode usar um sistema de tabelas e autenticação de usuário, ou pode aproveitar um dos provedores de login social. Para mais informações sobre como fazer isso com um Suplemento do Office, consulte Autorizar serviços externos no Suplemento do Office.

Para obter exemplos de código que usam a plataforma de identidade da Microsoft como o sistema de fallback, consulte Suplemento do Office NodeJS SSO e o suplemento do Office ASP.NET SSO.

Desenvolver um suplemento com SSO

Esta seção descreve as tarefas envolvidas na criação de um suplemento do Office que usa SSO. Essas tarefas são descritas aqui independentemente do idioma ou da estrutura. Para obter instruções passo a passo, consulte:

Registre seu suplemento com o plataforma de identidade da Microsoft

Para trabalhar com o SSO, você precisa registrar seu complemento com a plataforma de identidade da Microsoft. Isso permitirá que a plataforma de identidade da Microsoft forneça serviços de autenticação e autorização ao seu suplemento. A criação do registro do aplicativo inclui as seguintes tarefas.

  • Obter uma ID de aplicativo (cliente) para identificar seu suplemento na plataforma de identidade da Microsoft.
  • Gere um segredo do cliente para atuar como uma senha para o seu suplemento ao solicitar um token.
  • Especifique as permissões que seu suplemento exige. As permissões do Microsoft Graph "perfil" e "openid" são sempre necessárias. É possível que você precise de permissões adicionais, dependendo do que seu suplemento precisa fazer.
  • Conceda a confiança dos aplicativos do Office ao suplemento.
  • Autorize previamente os aplicativos do Office ao suplemento com o escopo padrão access_as_user.

Para obter mais detalhes sobre esse processo, consulte Registrar um Suplemento do Office que usa o SSO com a plataforma de identidade da Microsoft.

Configurar o suplemento

Adicione novas marcações ao manifesto do suplemento.

  • <WebApplicationInfo> – o pai dos seguintes elementos.
  • <Id> – A ID do aplicativo (cliente) que você recebeu quando registrou o suplemento com o plataforma de identidade da Microsoft. Para obter mais informações, consulte Registrar um Suplemento do Office que usa o SSO com a plataforma de identidade da Microsoft.
  • <Recurso> – O URI do suplemento. Esse é o mesmo URI (incluindo api: o protocolo) que você usou ao registrar o suplemento com a plataforma de identidade da Microsoft. A parte de domínio desse URI deve corresponder ao domínio, incluindo quaisquer subdomínios, usados nas URLs na <seção Recursos> do manifesto do suplemento e o URI deve terminar com a ID do cliente especificada no <elemento Id> .
  • <Escopos> – o pai de um ou mais <elementos do Escopo> .
  • <Escopo> – especifica uma permissão que o suplemento precisa. As profile e openID permissões são sempre necessárias e podem ser as únicas permissões necessárias. Se o suplemento precisar de acesso ao Microsoft Graph ou a outros recursos do Microsoft 365, você precisará de elementos adicionais <do Escopo> . Por exemplo, para as permissões do Microsoft Graph você pode solicitar os escopos User.Read e Mail.Read. Bibliotecas que você usa no seu código para acessar o Microsoft Graph pode precisar de permissões adicionais. Para saber mais, confira autorizar o Microsoft Graph de um suplemento do Office.

Quanto ao suplemento do Word, Excel e PowerPoint, adicione a marcação ao final da <VersionOverrides ... xsi:type="VersionOverridesV1_0"> seção. Quanto aos suplementos do Outlook, adicione a marcação ao final da <VersionOverrides ... xsi:type="VersionOverridesV1_1"> seção.

Veja a seguir um exemplo da marcação.

<WebApplicationInfo>
    <Id>5661fed9-f33d-4e95-b6cf-624a34a2f51d</Id>
    <Resource>api://addin.contoso.com/5661fed9-f33d-4e95-b6cf-624a34a2f51d</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>files.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

Importante

Se o suplemento for implantado por um ou mais administradores em suas organizações, adicionar novos escopos ao manifesto exigirá que o administrador consenta com as atualizações. Os usuários serão bloqueados do suplemento até que o consentimento seja concedido.

Observação

Se você não seguir os requisitos de formato no manifesto do SSO, seu suplemento será rejeitado do AppSource até que ele atenda ao formato necessário.

Inclua o conjunto de requisitos da API de identidade

Para usar o SSO, seu complemento precisa do conjunto de requisitos da API de Identidade 1.3. Para obter mais informações, consulte IdentityAPI.

Adicionar código do lado do cliente

Adicione o JavaScript ao suplemento para:

  • Chamar getAccessToken.
  • Analisar o token de acesso ou encaminhá-lo ao código de servidor do suplemento.

O código a seguir mostra um exemplo simples de chamar getAccessToken e analisar o token no nome de usuário e outras credenciais.

Observação

Este exemplo lida explicitamente com apenas um tipo de erro. Para exemplos de tratamento de erro mais elaborados, confira SSO com Suplemento NodeJS do Office e SSO com Suplemento ASP.NET do Office.

async function getUserData() {
    try {
        let userTokenEncoded = await OfficeRuntime.auth.getAccessToken();
        let userToken = jwt_decode(userTokenEncoded); // Using the https://www.npmjs.com/package/jwt-decode library.
        console.log(userToken.name); // user name
        console.log(userToken.preferred_username); // email
        console.log(userToken.oid); // user id     
    }
    catch (exception) {
        if (exception.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // Microsoft 365 Education or work account, or a Microsoft account.
        } else {
            // Handle error
        }
    }
}

Quando chamar getAccessToken

Se o seu suplemento exigir um usuário conectado, você deverá ligar para getAccessToken do Office.initialize. Você também deve passar allowSignInPrompt: true no options parâmetro de getAccessToken. Por exemplo, OfficeRuntime.auth.getAccessToken( { allowSignInPrompt: true }); isso garantirá que, se o usuário ainda não estiver conectado, o Office solicitará que o usuário entre na interface do usuário agora.

Se o suplemento tiver alguma funcionalidade que não exija um usuário conectado, você poderá chamar getAccessTokenquando o usuário fizer uma ação que exija um usuário conectado. Não há degradação significativa de desempenho com as chamadas redundantes do getAccessToken porque o Office armazena em cache o token de acesso e o reusará até expirar, sem fazer outra chamada à plataforma de identidade da Microsoftsempre que getAccessToken for chamado. Portanto, você pode adicionar chamadas de getAccessToken para todas as funções e manipuladores que iniciam uma ação onde o token é necessário.

Importante

Como prática de segurança, sempre chame getAccessToken quando precisar de um token de acesso. O Office armazenará em cache para você. Não armazene ou armazene o token de acesso usando seu próprio código.

Passe o token de acesso para o código ao lado do servidor

Se você precisar acessar as APIs da Web no seu servidor ou serviços adicionais, como o Microsoft Graph, você precisará passar o token de acesso no seu código ao lado do servidor. O token de acesso fornece acesso (para o usuário autenticado) às suas APIs da Web. Além disso, o código ao lado do servidor pode analisar o token para obter informações de identidade, se precisar dele. (Consulte Usar o token de acesso como um token de identidade abaixo.) Há muitas bibliotecas disponíveis para diferentes idiomas e plataformas que podem ajudar a simplificar o código que você escreve. Para obter mais informações, consulte Visão geral da biblioteca de autenticação da Microsoft (MSAL).

Se você precisar acessar os dados do Microsoft Graph, seu código ao lado do servidor deve fazer o seguinte:

  • Validar o token de acesso (consulte validar o token de acesso abaixo).
  • Inicie o fluxo OAuth 2.0 On-Behalf-Of com uma chamada para a plataforma de identidade da Microsoft que inclui o token de acesso, alguns metadados do usuário e as credenciais do suplemento (sua ID e segredo). A plataforma de identidade da Microsoft retornará um novo token de acesso que pode ser usado para acessar o Microsoft Graph.
  • Obter os dados do Microsoft Graph usando o novo token.
  • Se você precisar armazenar em cache o novo token de acesso para várias chamadas, recomendamos usar a Serialização do cache de token em MSAL.NET.

Importante

Como prática de segurança, sempre use o código ao lado do servidor para fazer chamadas pelo Microsoft Graph ou outras chamadas que exigem a passagem de um token de acesso. Nunca retorne o token OBO ao cliente para permitir que o cliente faça chamadas diretas ao Microsoft Graph. Isso ajuda a proteger o token de ser interceptado ou vazado. Para obter mais informações sobre o fluxo de protocolo adequado, consulte o Diagrama de protocolo OAuth 2.0

O código a seguir mostra um exemplo de passagem do token de acesso para o lado do servidor. O token é passado em um Authorization cabeçalho ao enviar uma solicitação para uma API da Web do lado do servidor. Este exemplo envia dados JSON, portanto, ele usa o POSTmétodo, mas GETé suficiente para enviar o token de acesso quando você não estiver escrevendo no servidor.

$.ajax({
    type: "POST",
    url: "/api/DoSomething",
    headers: {
        "Authorization": "Bearer " + accessToken
    },
    data: { /* some JSON payload */ },
    contentType: "application/json; charset=utf-8"
}).done(function (data) {
    // Handle success
}).fail(function (error) {
    // Handle error
}).always(function () {
    // Cleanup
});

Para saber mais sobre como obter acesso autorizado aos dados do usuário Microsoft Graph, confira Autorizar o Microsoft Graph nos suplementos do Office.

Validar o token de acesso

As APIs da Web no seu servidor devem validar o token de acesso se ele for enviado do cliente. O token é um Token Web JSON (JWT) e isso significa que validação funciona como uma validação de token na maioria dos fluxos padrão do OAuth. Há diversas bibliotecas disponíveis que podem lidar com a validação de JWT. No entanto, as noções básicas incluem:

  • Verificar se o token foi bem formado
  • Verificar se o token foi emitido pela autoridade desejada
  • Verificar se o token está direcionado para a API Web

Tenha em mente as diretrizes a seguir ao validar o token.

  • Os tokens SSO válidos serão emitidos pela autoridade do Azure, https://login.microsoftonline.com. A declaração iss no token deve começar com esse valor.
  • O parâmetro do aud token será definido como a ID do aplicativo do registro do aplicativo do Azure do suplemento.
  • O parâmetro scp do token será definido como access_as_user.

Para obter mais informações sobre a validação do token, consulte Tokens de acesso da plataforma de identidade da Microsoft.

User o token de acesso como um token de identidade

Se o suplemento precisar verificar a identidade do usuário, o token de acesso retornado do getAccessToken() contém informações que podem ser usadas para estabelecer a identidade. As seguintes declarações no token estão relacionadas à identidade.

  • name – O nome para exibição do usuário.
  • preferred_usernameO endereço de email do usuário.
  • oid - Um GUID que representa a ID do usuário no sistema de identidade da Microsoft.
  • tid - Um GUID que representa o locatário no qual o usuário está entrando.

Para obter mais detalhes sobre essas e outras declarações, consulte Tokens da ID da plataforma de identidade da Microsoft. Se você precisar construir uma ID exclusiva para representar o usuário no seu sistema, consulte Usar as declarações para identificar um usuário de forma confiável para obter mais informações.

Token de acesso de exemplo

A seguir está uma carga decodificada típica do token de acesso. Para obter informações sobre as propriedades, consulte Tokens de acesso da plataforma de identidade da Microsoft.

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Usando o SSO com um suplemento do Outlook

Há algumas diferenças pequenas, mas importantes entre usar o SSO em um suplemento do Outlook e em um suplemento do Excel, PowerPoint ou Word. Não deixe de ler Autenticar o usuário com um token de logon único em um suplemento do Outlook e Cenário: implementar o logon único ao serviço em um suplemento do Outlook.

O Google Chrome está eliminando cookies de terceiros em 2024 e introduzindo um recurso chamado Prevenção de Rastreamento. Se a Prevenção de Rastreamento estiver habilitada no navegador Chrome, seu suplemento não poderá usar cookies de terceiros. Seu suplemento pode encontrar problemas ao autenticar o usuário, como várias solicitações de logon ou erros.

Para obter experiências de autenticação aprimoradas, consulte Usar o estado do dispositivo para obter uma experiência de SSO aprimorada em navegadores com cookies de terceiros bloqueados.

Para obter mais informações sobre a distribuição do Google Chrome, confira os seguintes recursos:

Confira também