Registrar um Suplemento do Office que usa o SSO (logon único) com o plataforma de identidade da Microsoft

  • Artigo

Este artigo explica como registrar um Suplemento do Office com o plataforma de identidade da Microsoft para que você possa usar o SSO. Registre o suplemento quando começar a desenvolvê-lo para que, ao progredir para o teste ou produção, você possa alterar o registro existente ou criar registros separados para versões de desenvolvimento, teste e produção do suplemento.

A tabela a seguir relaciona as informações necessárias para executar este procedimento e os espaços reservados correspondentes que aparecem nas instruções.

Informações Exemplos Espaço reservado
Um nome legível por humanos para o suplemento. (Recomenda-se exclusividade, mas não é obrigatória.) Contoso Marketing Excel Add-in (Prod) <add-in-name>
Uma ID do aplicativo que o Azure gera para você como parte do processo de registro. c6c1f32b-5e55-4997-881a-753cc1d563b7 <app-id>
O nome de domínio totalmente qualificado do suplemento (exceto para o protocolo). Use um domínio pertencente a você. Por esse motivo, você não pode usar determinados domínios conhecidos, como azurewebsites.net ou cloudapp.net. O domínio deve ser o mesmo, incluindo quaisquer subdomínios, como é usado nas URLs na <seção Recursos> do manifesto do suplemento. localhost:6789, addins.contoso.com <fully-qualified-domain-name>
As permissões para o plataforma de identidade da Microsoft e o Microsoft Graph que seu suplemento precisa. (profile é sempre obrigatório.) profile, Files.Read.All N/D

Cuidado

Informações confidenciais: o URI da ID do aplicativo (<fully-qualified-domain-name>) é registrado como parte do processo de autenticação quando um suplemento usando SSO é ativado no Office em execução dentro do Microsoft Teams. O URI não deve conter informações confidenciais.

Registrar o suplemento com plataforma de identidade da Microsoft

Você precisa criar um registro de aplicativo no Azure que represente seu servidor Web. Isso permite o suporte à autenticação para que tokens de acesso adequados possam ser emitidos para o código do cliente no JavaScript. Esse registro dá suporte ao SSO no cliente e à autenticação de fallback usando a MSAL (Biblioteca de Autenticação da Microsoft).

  1. Entre no portal do Azure com as credenciais de administrador para sua locação do Microsoft 365. Por exemplo, MyName@contoso.onmicrosoft.com.

  2. Selecione Registros de aplicativos. Se você não vir o ícone, pesquise por "registro de aplicativo" na barra de pesquisa.

    A página inicial portal do Azure.

    A página Registros de aplicativo é exibida.

  3. Selecione Novo registro.

    Novo registro no painel Registros de aplicativo.

    A página Registrar um aplicativo é exibida.

  4. Na página Registrar um aplicativo, defina os valores da seguinte forma.

    • Defina Nome para <add-in-name>.
    • Defina tipos de conta com suportecomo Contas em qualquer diretório organizacional (qualquer diretório Azure AD - multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).
    • Defina o URI de redirecionamento para usar o SPA (aplicativo de página única) da plataforma e o URI como https://<fully-qualified-domain-name>/dialog.html.

    Registre um painel de aplicativo com o nome e a conta com suporte concluída.

  5. Selecione Registrar. Uma mensagem é exibida informando que o registro do aplicativo foi criado.

    Mensagem informando que o registro do aplicativo foi criado.

  6. Copie e salve os valores da ID do Aplicativo (cliente) e da ID do Diretório (locatário). Use ambos os valores nos procedimentos posteriores.

    Painel de registro de aplicativo da Contoso que exibe a ID do cliente e a ID do diretório.

Adicionar um segredo do cliente

Às vezes chamado de senha de aplicativo, um segredo do cliente é um valor de cadeia de caracteres que seu aplicativo pode usar no lugar de um certificado para se identificar.

  1. No painel esquerdo, selecione Certificados & segredos. Em seguida, na guia Segredos do cliente , selecione Novo segredo do cliente.

    O painel Certificados & segredos.

    O painel Adicionar um segredo do cliente é exibido.

  2. Adicione uma descrição para o segredo do cliente.

  3. Selecione uma expiração para o segredo ou especifique um tempo de vida personalizado.

    • O tempo de vida do segredo do cliente é limitado a dois anos (24 meses) ou menos. Você não pode especificar uma vida útil personalizada com mais de 24 meses.
    • A Microsoft recomenda que você defina um valor de expiração inferior a 12 meses.

    Adicione um painel de segredo do cliente com a descrição e expira concluído.

  4. Selecione Adicionar. O novo segredo é criado e o valor é exibido temporariamente.

Importante

Registre o valor do segredo para uso no código do aplicativo cliente. Esse valor secreto nunca será exibido novamente depois que você sair deste painel.

Expor uma API Web

  1. No painel esquerdo, selecione Expor uma API.

    O painel Expor uma API é exibido.

    Um painel Expor uma API de um registro de aplicativo.

  2. Selecione Definir para gerar um URI de ID do aplicativo.

    Defina o botão no painel Expor uma API do registro do aplicativo.

    A seção para definir o URI de ID do aplicativo é exibida com um URI de ID de Aplicativo gerado no formulário api://<app-id>.

  3. Atualize o URI da ID do aplicativo para api://<fully-qualified-domain-name>/<app-id>.

    Edite o painel URI da ID do aplicativo com a porta localhost definida como 44355.

    • O URI da ID do aplicativo está preenchido previamente com a ID do aplicativo (GUID) no formato api://<app-id>.
    • O formato URI da ID do aplicativo deve ser: api://<fully-qualified-domain-name>/<app-id>
    • Insira o fully-qualified-domain-name entre api:// e <app-id> (que é um GUID). Por exemplo, api://contoso.com/<app-id>.
    • Se você estiver usando localhost, o formato deverá ser api://localhost:<port>/<app-id>. Por exemplo, api://localhost:3000/c6c1f32b-5e55-4997-881a-753cc1d563b7.

    Para obter detalhes adicionais do URI da ID do aplicativo, consulte Atributo identifierUris do manifesto do aplicativo.

    Observação

    Se você receber um erro dizendo que o domínio já pertence a alguém, mas você é o seu proprietário, siga o procedimento em Início Rápido: Adicionar um domínio personalizado ao Azure Active Directory para registrá-lo e, em seguida, repita esta etapa. (Esse erro também pode ocorrer se você não estiver conectado com credenciais de um administrador no locatário do Microsoft 365. Confira a etapa 2. Saia e entre novamente com credenciais de administrador e repita o processo da etapa 3.)

Adicionar um escopo

  1. Na página Expor uma API , selecione Adicionar um escopo.

    Selecione Adicionar um botão de escopo.

    O painel Adicionar um escopo é aberto.

  2. No painel Adicionar um escopo , especifique os atributos do escopo. A tabela a seguir mostra valores de exemplo para e o suplemento do Outlook que exige as profilepermissões , openid, Files.ReadWritee Mail.Read . Modifique o texto para corresponder às permissões que seu suplemento precisa.

    Campo Descrição Values
    Nome do Escopo O nome do escopo. Uma convenção de nomenclatura de escopo comum é resource.operation.constraint. Para SSO, isso deve ser definido como access_as_user.
    Quem pode consentir Determina se o consentimento do administrador é necessário ou se os usuários podem consentir sem uma aprovação de administrador. Para aprender SSO e exemplos, recomendamos que você defina isso como administradores e usuários.

    Selecione Administradores somente para permissões com privilégios mais altos.
    Administração nome de exibição de consentimento Uma breve descrição da finalidade do escopo visível apenas para administradores. Read/write permissions to user files. Read permissions to user mail and profiles.
    Administração descrição do consentimento Uma descrição mais detalhada da permissão concedida pelo escopo que somente os administradores veem. Allow Office to have read/write permissions to all user files and read permissions to all user mail. Office can call the app's web APIs as the current user.
    Nome de exibição de consentimento do usuário Uma breve descrição da finalidade do escopo. Mostrado aos usuários somente se você definir Quem pode consentir com administradores e usuários. Read/write permissions to your files. Read permissions to your mail and profile.
    Descrição do consentimento do usuário Uma descrição mais detalhada da permissão concedida pelo escopo. Mostrado aos usuários somente se você definir Quem pode consentir com administradores e usuários. Allow Office to have read/write permissions to your files, and read permissions to your mail and profile.

  3. Defina o Estado como Habilitado e selecione Adicionar escopo.

    Defina o estado como habilitado e selecione o botão adicionar escopo.

    O novo escopo definido é exibido no painel.

    O novo escopo exibido no painel Expor uma API.

    Observação

    A parte de domínio do Nome de escopo exibidos logo abaixo do campo de texto deve corresponder automaticamente ao URI de ID do aplicativo definidos na etapa anterior com /access_as_user acrescentado ao final; por exemplo, api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user.

  4. Selecione Adicionar um aplicativo cliente.

    Selecione adicionar um aplicativo cliente.

    O painel Adicionar um aplicativo cliente é exibido.

  5. Na ID do cliente, insiraea5a67f6-b6f3-4338-b240-c655ddc3cc8e. Esse valor autoriza previamente todos os pontos de extremidade do aplicativo do Microsoft Office. Se você também quiser pré-autorizar o Office quando usado dentro do Microsoft Teams, adicione 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Microsoft Teams desktop e Teams mobile) e 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams na Web).

    Observação

    A ea5a67f6-b6f3-4338-b240-c655ddc3cc8e ID pré-autoriza o Office em todas as plataformas a seguir. Como alternativa, você pode inserir um subconjunto adequado das seguintes IDs se, por qualquer motivo, desejar negar a autorização ao Office em algumas plataformas. Se você fizer isso, deixe de fora as IDs das plataformas das quais deseja reter a autorização. Os usuários do suplemento nessas plataformas não poderão chamar suas APIs Web, mas outras funcionalidades no suplemento ainda funcionarão.

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

  6. Em Escopos autorizados, selecione a caixa de seleção api://<fully-qualified-domain-name>/<app-id>/access_as_user .

  7. Selecione Adicionar aplicativo.

    O painel Adicionar um aplicativo cliente.

Adicionar permissões do Microsoft Graph

  1. No painel esquerdo, selecione permissões de API.

    O painel permissões de API.

    O painel de permissões de API é aberto.

  2. Selecione Adicionar uma permissão.

    Adicionando uma permissão no painel de permissões de API.

    O painel Solicitar permissões de API é aberto.

  3. Selecione Microsoft Graph.

    O painel Solicitar permissões de API com o botão Microsoft Graph.

  4. Selecione Permissões delegadas.

    O painel Solicitar permissões de API com o botão permissões delegadas.

  5. Na caixa de pesquisa Selecionar permissões, pesquise as permissões que seu suplemento precisa. Por exemplo, para um suplemento do Outlook, você pode usar profile, openid, Files.ReadWritee Mail.Read.

    Observação

    A permissão User.Read pode já estar listada por padrão. É uma boa prática solicitar apenas permissões necessárias, portanto, recomendamos que você desmarque a caixa para essa permissão se o suplemento realmente não precisar dela.

  6. Selecione a caixa de seleção para cada permissão conforme ela aparece. Observe que as permissões não permanecerão visíveis na lista enquanto você seleciona cada uma delas. Depois de selecionar as permissões que seu suplemento precisa, selecione Adicionar permissões.

    O painel Solicitar permissões de API com algumas permissões selecionadas.

  7. Selecione Conceder consentimento de administrador para [nome do locatário]. Selecione Sim para a confirmação exibida.

Configurar a versão do token de acesso

Você deve definir a versão do token de acesso aceitável para seu aplicativo. Essa configuração é feita no manifesto do aplicativo do Azure Active Directory.

Definir a versão do token de acesso

A versão do token de acesso poderá ser alterada se você escolher um tipo de conta diferente de Contas em qualquer diretório organizacional (Qualquer diretório Azure AD – Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox). Use as etapas a seguir para garantir que a versão do token de acesso esteja correta para o uso do SSO do Office.

  1. No painel esquerdo, selecione Manifesto.

    Selecione Manifesto do Azure.

    O manifesto do aplicativo do Azure Active Directory é exibido.

  2. Insira 2 como o valor da propriedade accessTokenAcceptedVersion.

    Valor para a versão do token de acesso aceito.

  3. Selecione Salvar.

    Uma mensagem é exibida no navegador informando que o manifesto foi atualizado com êxito.

    Mensagem atualizada de manifesto.

Parabéns! Você concluiu o registro do aplicativo para habilitar o SSO para seu suplemento do Office.