Publicar um suplemento que requer o consentimento do administrador para os âmbitos do Microsoft Graph

Neste artigo, irá aprender a publicar atualizações num Suplemento do Office para utilizar âmbitos do Microsoft Graph e exigir o consentimento do administrador. Este é um cenário comum se tiver movido o seu suplemento do Outlook de tokens de Exchange Online legados para a utilização da biblioteca de autenticação da Microsoft (MSAL) com a autenticação de aplicações aninhadas (NAA) e tokens de Entra ID com as APIs do Microsoft Graph.

Para publicar atualizações, existem três aspetos a considerar.

1. Como implementar as alterações efetuadas no código do suplemento no servidor Web.
2. Como obter o consentimento do administrador para os âmbitos do Microsoft Graph.
3. Como implementar atualizações no seu manifesto.

Implementar atualizações no código do suplemento

Depois de atualizar e testar o código do suplemento, terá de implementá-los no servidor Web. Siga o seu próprio processo de atualização (como teste e produção). Depois de implementado, todos os utilizadores do seu suplemento verão as alterações e começarão a utilizar o código do suplemento atualizado. Não é necessário que os administradores ou utilizadores tomem medidas para ver as atualizações.

Todos os âmbitos do Microsoft Graph utilizados pelo seu suplemento requerem o consentimento do utilizador ou do administrador de um inquilino. Se o administrador não consentir, será pedido ao utilizador que dê consentimento quando o suplemento pedir um token de acesso através da MSAL. Para obter a melhor experiência de utilizador, evite pedir autorização aos utilizadores. Em vez disso, peça ao seu administrador para dar consentimento a todo o inquilino.

Existem duas formas de obter o consentimento do administrador: utilizar um URI de consentimento do administrador ou utilizar o manifesto unificado.

Obter consentimento do administrador através do URI de consentimento do administrador

Pode obter o consentimento do administrador ao fornecer um URI de consentimento do administrador. Fornece uma ligação que um administrador pode selecionar. Uma caixa de diálogo pede-lhes para iniciarem sessão com credenciais de administrador e dar consentimento aos âmbitos do Microsoft Graph necessários para o seu suplemento.

Para construir o URI de administrador, utilize o seguinte padrão.

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}

em que:

• client_id: o ID do registo da aplicação.
• scope: cada âmbito (como âmbitos do Microsoft Graph) requer o consentimento do administrador através do espaço como delimitador. Uma vez que a biblioteca de autenticação da Microsoft (MSAL) pede sempre um ID e um token de atualização, deve incluir sempre os openidâmbitos , profilee offline_access . Estes são pedidos por predefinição pela MSAL, mesmo que o seu suplemento não os solicite.
• redirect_uri: uma página de redirecionamento para quando o consentimento for concluído. O plataforma de identidade da Microsoft redirecionará para esta página após o consentimento de um administrador. A página de redirecionamento é enviada com êxito ou falha na mensagem JSON, conforme especificado no Administração consentimento no plataforma de identidade da Microsoft. Na página, pode indicar o consentimento status ao administrador, bem como fornecer mais informações ou passos seguintes sobre o seu suplemento.

Importante

A página de redirecionamento tem de ser adicionada à lista de redirecionamentos de aplicação de página única (SPA) no registo da aplicação, juntamente com o brk-multihub redirecionamento ou o URI de consentimento do administrador falhará.

O seguinte exemplo de URI de administrador mostra como especificar os âmbitos , profile, user.readoffline_accesse files.read e redirecionar para uma página no servidor Web com o openidnome consentRedirect.html.

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=63e62b68-c5c7-48f9-82bf-8c41d5637b49&scope=offline_access openid profile user.read files.read&redirect_uri=https://localhost:3000/consentRedirect.html

Observação

Se o identificador do recurso for omitido no parâmetro de âmbito, assume-se que o recurso é o Microsoft Graph. Por exemplo, User.Read é equivalente a https://graph.microsoft.com/User.Read.

Obter consentimento do administrador através do manifesto unificado

Também pode obter o consentimento do administrador como parte automática do fluxo de trabalho de implementação quando o suplemento é implementado. Para tal, adicione a webApplicationInfo propriedade ao manifesto unificado. Em seguida, o administrador implementa o manifesto atualizado, seja através da implementação central ou de uma atualização através do Microsoft AppSource. Quando o administrador implementa o manifesto atualizado, é-lhe pedido automaticamente que consoante os âmbitos exigidos pelo suplemento. Se não consentirem, o suplemento atualizado não será implementado.

Adicionar âmbitos do Graph ao registo de aplicações

Quando o administrador implementar o manifesto atualizado do seu suplemento, o processo de consentimento irá ler o registo da aplicação para os âmbitos a exigir o consentimento do administrador. Certifique-se de que adiciona todas as permissões necessárias para o suplemento através dos seguintes passos.

1. Inicie sessão no Portal do Azure e abra o registo da aplicação.

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

   

   O painel permissões da API é aberto.

3. Selecione Adicionar uma permissão.

   

   O painel Pedir permissões da API é aberto.

4. Selecione Microsoft Graph.

   

5. Selecione Permissões delegadas.

   

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

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

   

Adicionar a propriedade webApplicationInfo

Para obter o consentimento do administrador como parte do fluxo de trabalho de implementação, adicione a webApplicationInfo propriedade ao manifesto unificado. Defina a propriedade para o id ID de registo da aplicação. Defina a resource propriedade como o valor do seu domínio. O exemplo seguinte mostra a webApplicationInfo propriedade de um registo de aplicação para contoso.com.

    "webApplicationInfo": {
        "id": "a92ace55-9daf-47bc-84e9-065e9a6e70e3",
        "resource": "https://contoso.com"
    },

Implementar o manifesto atualizado

Se tiver implementado o suplemento através do Microsoft AppSource, terá de submeter o seu manifesto unificado atualizado para aprovação. Para obter mais informações, veja FAQ sobre submissão do Microsoft AppSource.

Se tiver implementado o suplemento ao fornecer o manifesto aos administradores para a implementação central, terá de fornecer aos administradores um pacote de aplicações atualizado que contenha o manifesto atualizado.

Conteúdo relacionado

• Perguntas Frequentes sobre o envio ao Microsoft AppSource
• Administração consentimento no plataforma de identidade da Microsoft
• Pedir permissões através do consentimento
• propriedade webApplicationInfo
• FAQ sobre a descontinuação da autenticação de aplicações aninhadas e tokens legados do Outlook