Visão geral da autenticação e autorização nos Suplementos do Office

Os Suplementos do Office permitem o acesso anônimo por padrão, mas você pode exigir que os usuários se conectem para usar seu suplemento com um conta Microsoft, uma conta corporativa ou do Microsoft 365 Education ou outra conta comum. Essa tarefa é chamada de autenticação do usuário, pois permite que o suplemento saiba quem é o usuário.

O seu suplemento também pode obter o consentimento do utilizador para aceder aos respetivos dados do Microsoft Graph (como o respetivo perfil do Microsoft 365, ficheiros do OneDrive e dados do SharePoint) ou dados noutras origens externas, como Google, Facebook, LinkedIn, SalesForce e GitHub. Esta tarefa é denominada autorização de suplemento (ou aplicação), porque é o suplemento que está a ser autorizado e não o utilizador.

Principais recursos da autenticação e da autorização

Esta documentação explica como criar e configurar Suplementos do Office para implementar a autenticação e a autorização com êxito. No entanto, muitos conceitos e tecnologias de segurança mencionados estão fora do escopo desta documentação. Por exemplo, conceitos gerais de segurança como fluxos OAuth, cache de token ou gerenciamento de identidades não são explicados aqui. Esta documentação também não documenta nada específico do Microsoft Azure ou do plataforma de identidade da Microsoft. Recomendamos que você confira os recursos a seguir se precisar de mais informações nessas áreas.

• Plataforma de identidade da Microsoft
• Suporte à plataforma de identidade da Microsoft e opções de ajuda para desenvolvedores
• Protocolos OAuth 2.0 e OpenID Connect na plataforma de identidade da Microsoft

Cenários de SSO

Usar o SSO (logon único) é conveniente para o usuário porque ele só precisa entrar no Office uma vez. Não precisam de iniciar sessão separadamente no seu suplemento. O SSO não é suportado em todas as versões do Office, pelo que ainda terá de implementar uma abordagem alternativa de início de sessão com o plataforma de identidade da Microsoft. Para obter mais informações sobre as versões compatíveis do Office, confira os Conjuntos de requisitos da API de Identidade

Obter a identidade do usuário por meio do SSO

Geralmente, seu suplemento precisa apenas da identidade do usuário. Por exemplo, talvez você queira apenas personalizar seu suplemento e exibir o nome do usuário no painel de tarefas. Ou talvez você queira uma ID exclusiva para associar o usuário aos dados em seu banco de dados. Isso pode ser feito ao obter o token de acesso do usuário do Office.

Para obter a identidade do usuário por meio do SSO, chame o método getAccessToken. O método retorna um token de acesso que também é um token de identidade que contém várias declarações exclusivas do usuário conectado no momento, incluindo preferred_username, name, sub e oid. Para obter mais informações sobre essas propriedades, confira os Tokens de ID da plataforma de identidade da Microsoft. Para obter um exemplo do token retornado por getAccessToken, confira o Exemplo de token de acesso.

Se o utilizador não tiver sessão iniciada, o Office abrirá uma caixa de diálogo e utilizará a plataforma de identidade da Microsoft para pedir ao utilizador para iniciar sessão. Em seguida, o método retornará um token de acesso ou gerará um erro se não for possível conectar o usuário.

Em um cenário em que você precisa armazenar dados do usuário, confira Tokens de ID da plataforma de identidade da Microsoft para saber como obter um valor do token para identificar o usuário de forma exclusiva. Use esse valor para pesquisar o usuário em uma tabela de usuário ou banco de dados de usuário que você mantém. Use o banco de dados para armazenar informações relativas ao usuário, como as preferências do usuário ou o estado da conta do usuário. Uma vez que está a utilizar o SSO, os seus utilizadores não iniciam sessão separadamente no seu suplemento, pelo que não precisa de armazenar uma palavra-passe para o utilizador.

Antes de começar a implementar a autenticação de utilizador com o SSO, certifique-se de que está completamente familiarizado com o artigo Ativar o início de sessão único para Suplementos do Office.

Acessar suas APIs Web por meio do SSO

Se seu suplemento tiver APIs no servidor que exigem um usuário autorizado, chame o método getAccessToken para obter um token de acesso. O token de acesso fornece acesso ao seu próprio servidor Web (configurado através de um registo de aplicação no Microsoft Entra ID). Quando chama APIs no servidor Web, também transmite o token de acesso para autorizar o utilizador.

O código a seguir mostra como construir uma solicitação HTTPS GET para a API do servidor Web do suplemento para obter alguns dados. O código é executado do lado do cliente, como em um painel de tarefas. Primeiro, ele obtém o token de acesso chamando getAccessToken. Em seguida, ele constrói uma chamada AJAX com a URL e o cabeçalho de autorização corretos para a API do servidor.

function getOneDriveFileNames() {

    let accessToken = await Office.auth.getAccessToken();

    $.ajax({
        url: "/api/data",
        headers: { "Authorization": "Bearer " + accessToken },
        type: "GET"
    })
        .done(function (result) {
            //... work with data from the result...
        });
}

O código a seguir mostra um exemplo de manipulador /api/data para a chamada REST do exemplo de código anterior. O código é um ASP.NET executado em um servidor Web. O [Authorize] atributo exigirá que seja transmitido um token de acesso válido a partir do cliente ou devolverá um erro ao cliente.

    [Authorize]
    // GET api/data
    public async Task<HttpResponseMessage> Get()
    {
        //... obtain and return data to the client-side code...
    }

Acessar o Microsoft Graph por meio do SSO

Em alguns cenários, não só precisa da identidade do utilizador, como também tem de aceder aos recursos do Microsoft Graph em nome do utilizador. Por exemplo, talvez seja necessário enviar um email ou criar um chat no Teams em nome do usuário. Estas ações e muito mais podem ser realizadas através do Microsoft Graph. Você precisará seguir essas etapas:

1. Obtenha o token de acesso para o usuário atual por meio do SSO chamando getAccessToken. Se o utilizador não tiver sessão iniciada, o Office abrirá uma caixa de diálogo e iniciará sessão no utilizador com o plataforma de identidade da Microsoft. Após o usuário entrar ou se o usuário já tiver entrado, o método retorna um token de acesso.
2. Passe o token de acesso para o código do servidor.
3. No servidor, use o Fluxo On-Behalf-Of do OAuth 2.0 para trocar o token de acesso por um novo token de acesso que contém a identidade de usuário delegada necessária e as permissões para chamar o Microsoft Graph.

Antes de começar a implementar o SSO para aceder ao Microsoft Graph no seu suplemento, certifique-se de que está completamente familiarizado com os seguintes artigos.

• Habilitar o logon único para Suplementos do Office
• Autorizar o Microsoft Graph com SSO

Também deve ler pelo menos um dos seguintes artigos que irá guiá-lo ao longo da criação de um Suplemento do Office para utilizar o SSO e aceder ao Microsoft Graph. Mesmo que você não execute as etapas, elas contêm informações valiosas sobre a implementação do SSO e o fluxo On-Behalf-Of.

• Criar um Suplemento do Office com ASP.NET que usa logon único que orienta você pelo exemplo em Suplemento do Office com ASP.NET e SSO.
• Criar um Suplemento do Office com Node.js que usa logon único que orienta você pelo exemplo em Suplemento do Office com Node.js e SSO.

Cenários sem SSO

Em alguns cenários, poderá não querer utilizar o SSO. Por exemplo, talvez seja necessário autenticar usando um provedor de identidade diferente da plataforma de identidade da Microsoft. Além disso, o SSO não é suportado em todos os cenários. Por exemplo, as versões mais antigas do Office não são compatíveis com o SSO. Neste caso, terá de reverter para um sistema de autenticação alternativo para o seu suplemento.

Autenticar com a plataforma de identidade da Microsoft

Seu suplemento pode conectar usuários usando a plataforma de identidade da Microsoft como provedor de autenticação. Depois de iniciar sessão no utilizador, pode utilizar o plataforma de identidade da Microsoft para autorizar o suplemento no Microsoft Graph ou noutros serviços geridos pela Microsoft. Use essa abordagem como um método de entrada alternativo quando o SSO por meio do Office não estiver disponível. Além disso, existem cenários em que pretende que os seus utilizadores iniciem sessão no seu suplemento separadamente, mesmo quando o SSO está disponível; por exemplo, se quiser que tenham a opção de iniciar sessão no suplemento com um ID diferente do que tem atualmente sessão iniciada no Office.

É importante ter em atenção que o plataforma de identidade da Microsoft não permite que a página de início de sessão seja aberta num iframe. Quando um Suplemento do Office está em execução no Office na Web, o painel de tarefas é um iframe. Isso significa que será necessário abrir a página de entrada usando uma caixa de diálogo aberta com a API de diálogo do Office. Isso afeta o modo como você usa bibliotecas auxiliares de autenticação. Para saber mais, confira Autenticação com a API de diálogo do Office.

Para obter informações sobre como implementar a autenticação com a plataforma de identidade da Microsoft, confira a Visão geral da plataforma de Identidade da Microsoft (v 2.0). A documentação contém muitos tutoriais e guias, bem como links para exemplos e bibliotecas relevantes. Conforme explicado em Autenticação com a API de diálogo do Office, talvez seja necessário ajustar o código nos exemplos para executar na caixa de diálogo do Office.

Acesso ao Microsoft Graph sem SSO

Você pode obter autorização para os dados do Microsoft Graph para seu suplemento obtendo um token de acesso ao Microsoft Graph a partir da plataforma de identidade da Microsoft. Pode fazê-lo sem depender do SSO através do Office (ou se o SSO falhou ou não for suportado). Para obter mais informações, confira Acesse o Microsoft Graph sem o SSO que tem mais detalhes e links para os exemplos.

Acesso a fontes de dados que não são da Microsoft:

Serviços online populares, incluindo o Google, o Facebook, o LinkedIn, o SalesForce e o GitHub, permitem que os desenvolvedores forneçam acesso para os usuários a suas contas em outros aplicativos. Isso dá a você a capacidade de incluir esses serviços no seu Suplemento do Office. Para obter uma visão geral das maneiras como seu suplemento pode fazer isso, confira Autorizar serviços externos em seu Suplemento do Office.

Confira também

• Documentação da plataforma de identidade da Microsoft
• Tokens de acesso da plataforma de identidade da Microsoft
• Protocolos OAuth 2.0 e OpenID Connect na plataforma de identidade da Microsoft
• Plataforma de identidade da Microsoft e Fluxo On-Behalf-Of do OAuth 2.0
• Token Web JSON (JWT)
• Visualizador de Token Web JSON