Compartilhar via

Utilizar o SSO para obter a identidade do utilizador com sessão iniciada

  • Artigo

Utilize a getAccessToken API para obter um token de acesso que contenha a identidade do utilizador atual com sessão iniciada no Office. O token de acesso também é um token de ID porque contém afirmações de identidade sobre o utilizador com sessão iniciada, como o respetivo nome e e-mail. Também pode utilizar o token de ID para identificar o utilizador ao chamar os seus próprios serviços Web. Para ligar getAccessTokenpara o , tem de configurar o seu Suplemento do Office para utilizar o SSO com o Office.

Neste artigo, irá criar um Suplemento do Office que obtém o token de ID e apresenta o nome, o e-mail e o ID exclusivo do utilizador no painel de tarefas.

Observação

O SSO com o Office e a getAccessToken API não funciona em todos os cenários. Implemente sempre uma caixa de diálogo de contingência para iniciar sessão do utilizador quando o SSO está indisponível. Para obter mais informações, consulte Autenticar e autorizar com a API de caixa de diálogo do Office.

Criar um registo de aplicações

Para utilizar o SSO com o Office, tem de criar um registo de aplicação no portal do Azure para que o plataforma de identidade da Microsoft possa fornecer serviços de autenticação e autorização para o seu Suplemento do Office e os respetivos utilizadores.

  1. Para registar a sua aplicação, aceda à página portal do Azure - Registros de aplicativo.

  2. Inicie sessão com as credenciais de administrador para o seu inquilino do Microsoft 365. Por exemplo, MyName@contoso.onmicrosoft.com.

  3. Selecione Novo registro. Na página Registrar um aplicativo, defina os valores da seguinte forma.

    • Defina Nome para Office-Add-in-SSO.
    • Defina Tipos de conta com suporte para Contas em qualquer diretório organizacional e contas pessoais da Microsoft (por exemplo, Skype, Xbox, Outlook.com).
    • Defina o tipo de aplicação como Web e, em seguida, defina o URI de Redirecionamento como https://localhost:[port]/dialog.html. Substitua [port] pelo número de porta correto para a sua aplicação Web. Se tiver criado o suplemento com o Yo Office, o número da porta é normalmente 3000 e encontra-se no ficheiro package.json. Se tiver criado o suplemento com o Visual Studio 2019, a porta encontra-se na propriedade URL de SSL do projeto Web.
    • Escolha Registrar.

  4. Na página Office-Add-in-SSO, copie e guarde os valores do ID da Aplicação (cliente) e do ID do Diretório (inquilino). Use ambos os valores nos procedimentos posteriores.

    Observação

    Este ID de Aplicação (cliente) é o valor de "audiência" quando outras aplicações, como a aplicação cliente do Office (por exemplo, PowerPoint, Word, Excel), procuram acesso autorizado à aplicação. É também o "ID de cliente" da aplicação quando, por sua vez, procura acesso autorizado ao Microsoft Graph.

  5. Selecione Autenticação em Gerenciar. Na secção Concessão implícita , ative as caixas de verificação para token de acesso e token de ID.

  6. Na parte superior da página, selecione Salvar.

  7. Selecionar Expor uma API em Gerenciar. Selecione a ligação Definir . Isto irá gerar o URI do ID da Aplicação no formulário api://[app-id-guid], em que [app-id-guid] é o ID da Aplicação (cliente).

  8. No ID gerado, insira localhost:[port]/ (tenha em atenção a barra "/" anexada ao fim) entre as barras duplas e o GUID. Substitua [port] pelo número de porta correto para a sua aplicação Web. Se tiver criado o suplemento com o Yo Office, o número da porta é normalmente 3000 e encontra-se no ficheiro package.json. Se tiver criado o suplemento com o Visual Studio 2019, a porta encontra-se na propriedade URL de SSL do projeto Web.

    Quando tiver terminado, todo o ID deverá ter o formulário api://localhost:[port]/[app-id-guid]; por exemplo api://localhost:44355/c6c1f32b-5e55-4997-881a-753cc1d563b7.

  9. Selecione o botão Adicionar um escopo. No painel que é aberto, introduza access_as_user como o Nome do <âmbito> .

  10. Definir Quem pode consentir? aos Administradores e usuários.

  11. Preencha os campos para configurar os pedidos de consentimento do administrador e do utilizador com valores adequados para o access_as_user âmbito que permite à aplicação cliente do Office utilizar as APIs Web do seu suplemento com os mesmos direitos que o utilizador atual. Sugestões:

    • Administração o nome a apresentar do consentimento: o Office pode atuar como utilizador.
    • Descrição de autorização de administrador: Permite ao Office chamar os APIs de suplemento da web com os mesmos direitos que o usuário atual.
    • Nome a apresentar do consentimento do utilizador: o Office pode agir como você.
    • Descrição do consentimento do utilizador: ative o Office para chamar as APIs Web do suplemento com os mesmos direitos que tem.

  12. Verifique se o Estado está definido como Habilitado.

  13. Selecione Adicionar escopo.

    Observação

    A parte do domínio do Nome do <âmbito> apresentada imediatamente abaixo do campo de texto deve corresponder automaticamente ao URI do ID da Aplicação que definiu anteriormente, com /access_as_user anexado ao fim; por exemplo, api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user.

  14. Na secção Aplicações cliente autorizadas , introduza o seguinte ID para pré-autorizar todos os pontos finais de aplicações do Microsoft Office.

    • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Todos os pontos finais de aplicações do Microsoft Office)

    Observação

    O ea5a67f6-b6f3-4338-b240-c655ddc3cc8e ID pré-autoriza o Office em todas as seguintes plataformas. Em alternativa, pode introduzir um subconjunto adequado dos seguintes IDs se, por algum motivo, quiser negar a autorização ao Office em algumas plataformas. Basta deixar de fora os IDs das plataformas a partir das quais pretende reter a autorização. Os utilizadores do seu suplemento nessas plataformas não poderão chamar as suas APIs Web, mas outras funcionalidades no seu suplemento continuarão a funcionar.

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
    • 93d53678-613d-4013-afc1-62e9e444a0a5(Office na Web)
    • bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook na Web)

  15. Selecione o botão Adicionar uma aplicação cliente e, em seguida, no painel que é aberto, defina o [app-id-guid] para o ID da Aplicação (cliente) e marcar a caixa para api://localhost:44355/[app-id-guid]/access_as_user.

  16. Selecione Adicionar aplicativo.

  17. Selecione Permissões para API em Gerenciar e selecione Adicionar uma permissão. No painel que se abre, escolha Microsoft Graph e, em seguida, escolha Permissões delegadas.

  18. Use a caixa de pesquisa Selecionar permissões para procurar as permissões que o seu suplemento precisa. Procure e selecione a permissão de perfil . A profile permissão é necessária para que a aplicação do Office obtenha um token para a sua aplicação Web de suplemento.

    • perfil

    Observação

    A permissão User.Read pode já estar listada por padrão. É uma boa prática não pedir permissões que não são necessárias, pelo que recomendamos que desmarque a caixa para esta permissão se o seu suplemento não precisar realmente dela.

  19. Selecione a botão Adicionar seleção na parte inferior do painel.

  20. Na mesma página, selecione o botão Conceder consentimento do administrador para <nome> de inquilino e, em seguida, selecione Sim para a confirmação apresentada.

Criar o Suplemento do Office

  1. Inicie o Visual Studio 2019 e escolha Criar um novo projeto.
  2. Procure e selecione o modelo de projeto do Suplemento Web do Excel . Depois clique em Próximo. Nota: o SSO funciona com qualquer aplicação do Office, mas o Excel é a aplicação que está a ser utilizada com este artigo.
  3. Introduza um nome de projeto, como sso-display-user-info e selecione Criar. Pode deixar os outros campos nos valores predefinidos.
  4. Na caixa de diálogo Escolher o tipo de suplemento , selecione Adicionar nova funcionalidade ao Excel e selecione Concluir.

O projeto é criado e conterá dois projetos na solução.

  • sso-display-user-info: contém o manifesto e os detalhes do sideload do suplemento para o Excel.
  • sso-display-user-infoWeb: o projeto ASP.NET que aloja as páginas Web do suplemento.

Configurar o manifesto

No Gerenciador de Soluções, abra sso-display-user-info>sso-display-user-infoManifest>sso-display-user-info.xml.

  1. Junto à parte inferior do manifesto encontra-se um elemento de fecho </Resources> . Insira o seguinte XML imediatamente abaixo do </Resources> elemento, mas antes do elemento de fecho </VersionOverrides> . Para aplicações do Office que não o Outlook, adicione a marcação ao final da <VersionOverrides ... xsi:type="VersionOverridesV1_0"> secção. Para o Outlook, adicione a marcação no final da seção <VersionOverrides ... xsi:type="VersionOverridesV1_1">.

    <WebApplicationInfo>
    <Id>[application-id]</Id>
    <Resource>api://localhost:[port]/[application-id]</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

  2. Substitua [port] pelo número de porta correto para o projeto. Se tiver criado o suplemento com o Yo Office, o número da porta é normalmente 3000 e encontra-se no ficheiro package.json. Se tiver criado o suplemento com o Visual Studio 2019, a porta encontra-se na propriedade URL de SSL do projeto Web.

  3. Substitua ambos os [application-id] marcadores de posição pelo ID de aplicação real do registo da aplicação.

  4. Salve o arquivo.

O XML que inseriu contém os seguintes elementos e informações.

  • <WebApplicationInfo> – o elemento principal dos seguintes elementos.
  • <ID> - O ID de cliente do suplemento Este é um ID de aplicação que obtém como parte do registo do suplemento. Confira Registrar um Suplemento do Office que usa SSO com o ponto de extremidade do Azure AD v2.0.
  • <Recurso> – o URL do suplemento. Esse é o mesmo URI (incluindo o protocolo api:) que você usou ao registrar o suplemento no AAD. A parte do domínio deste URI tem de corresponder ao domínio, incluindo quaisquer subdomínios, utilizados nos URLs na <secção Recursos> do manifesto do suplemento e o URI tem de terminar com o ID de cliente no <ID>.
  • <Âmbitos> – o elemento principal de um ou mais <elementos de Âmbito> .
  • <Âmbito> – especifica uma permissão de que o suplemento precisa para o AAD. As profile permissões e openID são sempre necessárias e podem ser as únicas permissões necessárias se o seu suplemento não aceder ao Microsoft Graph. Se for o caso, também precisa de elementos de <Âmbito> para as permissões necessárias do Microsoft Graph; por exemplo, , User.ReadMail.Read. Bibliotecas que você usa no seu código para acessar o Microsoft Graph pode precisar de permissões adicionais. Por exemplo, a Biblioteca de Autenticação da Microsoft (MSAL) para .NET requer a offline_access permissão. Para saber mais, confira autorizar o Microsoft Graph de um suplemento do Office.

Adicionar o pacote jwt-decode

Pode ligar para a getAccessToken API para obter o token de ID do Office. Primeiro, vamos adicionar o pacote jwt-decode para facilitar a descodificar e ver o token de ID.

  1. Abra a solução visual Studio.

  2. No menu, selecione Ferramentas> Consolado Gestor de Pacotes nuGet>Gestor de Pacotes.

  3. Introduza o seguinte comando na Consola do Gestor de Pacotes.

    Install-Package jwt-decode -Projectname sso-display-user-infoWeb

Adicionar IU ao painel de tarefas

Modifique o painel de tarefas para que possa apresentar as informações de utilizador que obterá do token de ID.

  1. Abra o ficheiro Home.html.

  2. Adicione a seguinte etiqueta de script à <head> secção da página. Isto incluirá que o pacote jwt-decode foi adicionado anteriormente.

    <script src="Scripts/jwt-decode-2.2.0.js" type="text/javascript"></script>

  3. Substitua a <body> secção pelo seguinte HTML.

    <body>
  <h1>Welcome</h1>
  <p>
    Sign in to Office, then choose the <b>Get ID Token</b> button to see your
    ID token information.
  </p>
  <button id="getIDToken">Get ID Token</button>
  <div>
    <span id="userInfo"></span>
  </div>
</body>

Chamar a API getAccessToken

O passo final é obter o token de ID ao chamar getAccessToken.

  1. Abra o ficheiro Home.js .

  2. Substitua todo o conteúdo do arquivo pelo código a seguir.

    (function () {
  "use strict";

  // The initialize function must be run each time a new page is loaded.
  Office.initialize = function (reason) {
    $(document).ready(function () {
      $("#getIDToken").on("click", getIDToken);
    });
  };

  async function getIDToken() {
    try {
      let userTokenEncoded = await OfficeRuntime.auth.getAccessToken({
        allowSignInPrompt: true,
      });
      let userToken = jwt_decode(userTokenEncoded);
      document.getElementById("userInfo").innerHTML =
        "name: " +
        userToken.name +
        "<br>email: " +
        userToken.preferred_username +
        "<br>id: " +
        userToken.oid;
      console.log(userToken);
    } catch (error) {
      document.getElementById("userInfo").innerHTML =
        "An error occurred. <br>Name: " +
        error.name +
        "<br>Code: " +
        error.code +
        "<br>Message: " +
        error.message;
      console.log(error);
    }
  }
})();

  3. Salve o arquivo.

Execute o suplemento

Selecione Depurar>Iniciar Depuração ou prima F5.

  1. Quando o Excel é iniciado, inicie sessão no Office com a mesma conta de inquilino que utilizou para criar o registo de aplicações.
  2. No friso Base , selecione Mostrar Painel de Tarefas para abrir o suplemento.
  3. No painel de tarefas do suplemento, selecione Obter token de ID.

O suplemento apresentará o nome, o e-mail e o ID da conta com a qual iniciou sessão.

Observação

Se encontrar erros, veja os passos de registo neste artigo para o registo de aplicações. A falta de um detalhe ao configurar o registo de aplicações é uma causa comum de problemas ao trabalhar com o SSO. Se, mesmo assim, não conseguir executar o suplemento com êxito, veja Resolver problemas de mensagens de erro para o início de sessão único (SSO).

Parar o suplemento

Selecione Parar Depuração ou prima Shift+F5.

Confira também

Utilizar afirmações para identificar de forma fiável um utilizador (ID do Assunto e do Objeto)