Registrar um Suplemento do Office que usa o SSO (logon único) com o plataforma de identidade da Microsoft
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).
Entre no portal do Azure com as credenciais de administrador para sua locação do Microsoft 365. Por exemplo, MyName@contoso.onmicrosoft.com.
Selecione Registros de aplicativos. Se você não vir o ícone, pesquise por "registro de aplicativo" na barra de pesquisa.
A página Registros de aplicativo é exibida.
Selecione Novo registro.
A página Registrar um aplicativo é exibida.
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
.
- Defina Nome para
Selecione Registrar. Uma mensagem é exibida informando que o registro do aplicativo foi criado.
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.
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.
No painel esquerdo, selecione Certificados & segredos. Em seguida, na guia Segredos do cliente , selecione Novo segredo do cliente.
O painel Adicionar um segredo do cliente é exibido.
Adicione uma descrição para o segredo do cliente.
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.
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
No painel esquerdo, selecione Expor uma API.
O painel Expor uma API é exibido.
Selecione Definir para gerar um URI de ID 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>
.Atualize o URI da ID do aplicativo para
api://<fully-qualified-domain-name>/<app-id>
.- 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
entreapi://
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.)
- O URI da ID do aplicativo está preenchido previamente com a ID do aplicativo (GUID) no formato
Adicionar um escopo
Na página Expor uma API , selecione Adicionar um escopo.
O painel Adicionar um escopo é aberto.
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
profile
permissões ,openid
,Files.ReadWrite
eMail.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.
Defina o Estado como Habilitado e selecione Adicionar escopo.
O novo escopo definido é exibido no painel.
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
.Selecione Adicionar um aplicativo cliente.
O painel Adicionar um aplicativo cliente é exibido.
Na ID do cliente, insira
ea5a67f6-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, adicione1fec8e78-bce4-4aaf-ab1b-5451cc387264
(Microsoft Teams desktop e Teams mobile) e5e3ce6c0-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)
-
Em Escopos autorizados, selecione a caixa de seleção
api://<fully-qualified-domain-name>/<app-id>/access_as_user
.Selecione Adicionar aplicativo.
Adicionar permissões do Microsoft Graph
No painel esquerdo, selecione permissões de API.
O painel de permissões de API é aberto.
Selecione Adicionar uma permissão.
O painel Solicitar permissões de API é aberto.
Selecione Microsoft Graph.
Selecione Permissões delegadas.
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.ReadWrite
eMail.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.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.
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.
No painel esquerdo, selecione Manifesto.
O manifesto do aplicativo do Azure Active Directory é exibido.
Insira 2 como o valor da propriedade
accessTokenAcceptedVersion
.Selecione Salvar.
Uma mensagem é exibida no navegador informando que o manifesto foi atualizado com êxito.
Parabéns! Você concluiu o registro do aplicativo para habilitar o SSO para seu suplemento do Office.