Partilhar via

Registe um Suplemento do Office que utilize o início de sessão único (SSO) com o plataforma de identidade da Microsoft

  • Artigo

Este artigo explica como registar um Suplemento do Office no plataforma de identidade da Microsoft para que possa utilizar o SSO. Registe o suplemento quando começar a desenvolvê-lo para que, quando progredir para testes ou produção, possa alterar o registo existente ou criar registos 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>
Um ID de aplicação que o Azure gera automaticamente como parte do processo de registo. 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 tem de ser o mesmo, incluindo os subdomínios, tal como é utilizado nos URLs na <secçã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 de que o seu suplemento precisa. (profile é sempre obrigatório.) profile, Files.Read.All N/D

Cuidado

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

Registar o suplemento com plataforma de identidade da Microsoft

Tem de criar um registo de aplicações no Azure que represente o servidor Web. Isto permite o suporte de autenticação para que os tokens de acesso adequados possam ser emitidos para o código de cliente no JavaScript. Este registo suporta o SSO no cliente e a autenticação de contingência com a Biblioteca de Autenticação da Microsoft (MSAL).

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

  2. Selecione Registros de aplicativos. Se não vir o ícone, procure "registo de aplicações" na barra de pesquisa.

    A home page portal do Azure.

    A página Registros de aplicativo é exibida.

  3. Selecione Novo registro.

    Novo registo 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 suportados como Contas em qualquer diretório organizacional (qualquer diretório Azure AD - multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox).
    • Defina o URI de Redirecionamento para utilizar a aplicação de página única (SPA) da plataforma e o URI como https://<fully-qualified-domain-name>/dialog.html.

    Registar um painel de aplicação com o nome e a conta suportada concluídas.

  5. Selecione Registrar. É apresentada uma mensagem a indicar que o registo da aplicação foi criado.

    Mensagem a indicar que o registo da aplicação foi criado.

  6. 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.

    Painel de registo de aplicações da Contoso a apresentar o ID de cliente e o ID do diretório.

Adicionar um segredo do cliente

Por vezes denominado palavra-passe de aplicação, um segredo do cliente é um valor de cadeia que a sua aplicação pode utilizar em vez de um certificado para identificar a própria identidade.

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

    O painel Certificados & segredos.

    É apresentado o painel Adicionar um segredo do cliente .

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

  3. Selecione uma expiração para o segredo ou especifique uma duração personalizada.

    • A duração do segredo do cliente está limitada a dois anos (24 meses) ou menos. Não pode especificar uma duração personalizada superior a 24 meses.
    • A Microsoft recomenda que defina um valor de expiração inferior a 12 meses.

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

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

Importante

Registe o valor do segredo para utilização no código da aplicação cliente. Este valor secreto nunca mais é apresentado depois de sair deste painel.

Expor uma API Web

  1. No painel esquerdo, selecione Expor uma API.

    É apresentado o painel Expor uma API .

    Um registo de aplicação expõe um painel de API.

  2. Selecione Definir para gerar um URI de ID de aplicação.

    Botão Definir no painel Expor uma API do registo de aplicações.

    A secção para definir o URI do ID da aplicação é apresentada com um URI de ID da Aplicação gerado no formulário api://<app-id>.

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

    Edite o painel URI do ID da Aplicação 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 do URI do ID da aplicação deve ser: api://<fully-qualified-domain-name>/<app-id>
    • Insira entre fully-qualified-domain-nameapi:// e <app-id> (que é um GUID). Por exemplo, api://contoso.com/<app-id>.
    • Se estiver a utilizar 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 do ID da aplicação, veja Atributo identifierUris do manifesto da aplicação.

    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. (Este erro também pode ocorrer se não tiver sessão iniciada com credenciais de um administrador no inquilino do Microsoft 365. Veja o passo 2. Termine sessão e inicie sessão novamente com as credenciais de administrador e repita o processo no passo 3.)

Adicionar um âmbito

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

    Selecione Adicionar um botão de âmbito.

    O painel Adicionar um âmbito é aberto.

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

    Campo Descrição Values
    Nome do Escopo O nome do âmbito. Uma convenção de nomenclatura de âmbito comum é resource.operation.constraint. Para O SSO, tem de ser definido como access_as_user.
    Quem pode consentir Determina se o consentimento do administrador é necessário ou se os utilizadores podem consentir sem uma aprovação de administrador. Para aprender SSO e exemplos, recomendamos que defina esta opção para Administradores e utilizadores.

    Selecione Administradores apenas para permissões com privilégios mais elevados.
    Administração o nome a apresentar do consentimento Uma breve descrição da finalidade do âmbito visível apenas para os administradores. Read/write permissions to user files. Read permissions to user mail and profiles.
    descrição do consentimento do Administração Uma descrição mais detalhada da permissão concedida pelo âmbito que apenas 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 a apresentar do consentimento do utilizador Uma breve descrição da finalidade do âmbito. Mostrado aos utilizadores apenas se definir Quem pode dar consentimento a Administradores e utilizadores. Read/write permissions to your files. Read permissions to your mail and profile.
    Descrição do consentimento do utilizador Uma descrição mais detalhada da permissão concedida pelo âmbito. Mostrado aos utilizadores apenas se definir Quem pode dar consentimento a Administradores e utilizadores. Allow Office to have read/write permissions to your files, and read permissions to your mail and profile.

  3. Defina o Estado como Ativado e, em seguida, selecione Adicionar âmbito.

    Defina o estado como ativado e selecione o botão adicionar âmbito.

    O novo âmbito que definiu é apresentado no painel.

    O novo âmbito apresentado 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 uma aplicação cliente.

    É apresentado o painel Adicionar uma aplicação cliente .

  5. No ID de Cliente, introduza ea5a67f6-b6f3-4338-b240-c655ddc3cc8e. Este valor pré-autoriza todos os pontos finais de aplicações do Microsoft Office. Se também pretender pré-autorizar o Office quando utilizado no Microsoft Teams, adicione 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Ambiente de trabalho do Microsoft Teams e Teams para dispositivos móveis) e 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams na Web).

    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 qualquer motivo, quiser negar a autorização ao Office em algumas plataformas. Se o fizer, deixe 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)

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

  7. Selecione Adicionar aplicativo.

    O painel Adicionar uma aplicação cliente.

Adicionar permissões do Microsoft Graph

  1. No painel esquerdo, selecione Permissões da API.

    O painel permissões da API.

    O painel permissões da API é aberto.

  2. Selecione Adicionar uma permissão.

    Adicionar uma permissão no painel de permissões da API.

    O painel Pedir permissões da API é aberto.

  3. Selecione Microsoft Graph.

    O painel Pedir permissões da API com o botão Microsoft Graph.

  4. Selecione Permissões delegadas.

    O painel Pedir permissões da API com o botão permissões delegadas.

  5. Na caixa de pesquisa Selecionar permissões , procure as permissões de que o suplemento precisa. Por exemplo, para um suplemento do Outlook, pode utilizar profile, openid, Files.ReadWritee Mail.Read.

    Observação

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

  6. Selecione a caixa de verificação para cada permissão tal como é apresentada. Tenha em atenção que as permissões não permanecerão visíveis na lista à medida que seleciona cada uma delas. Depois de selecionar as permissões de que o suplemento precisa, selecione Adicionar permissões.

    O painel Pedir permissões da API com algumas permissões selecionadas.

  7. Selecione Conceder consentimento do administrador para [nome do inquilino]. Selecione Sim para a confirmação apresentada.

Configurar a versão do token de acesso

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

Definir a versão do token de acesso

A versão do token de acesso pode ser alterada se escolher um tipo de conta diferente de Contas em qualquer diretório organizacional (Qualquer diretório Azure AD - Multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox). Utilize os seguintes passos para garantir que a versão do token de acesso está correta para a utilização do SSO do Office.

  1. No painel esquerdo, selecione Manifesto.

    Selecione Manifesto do Azure.

    É apresentado o manifesto da aplicação do Azure Active Directory.

  2. Introduza 2 como o valor da requestedAccessTokenVersion propriedade (no api objeto).

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

  3. Selecione Salvar.

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

    Mensagem atualizada do manifesto.

Parabéns! Concluiu o registo de aplicações para ativar o SSO para o seu suplemento do Office.