Autorize contas de desenvolvedor usando o ID do Microsoft Entra no Gerenciamento de API do Azure

Neste artigo, você aprenderá a:

• Habilite o acesso ao portal do desenvolvedor para usuários do Microsoft Entra ID.
• Gerencie grupos de usuários do Microsoft Entra adicionando grupos externos que contêm os usuários.

Para obter uma visão geral das opções para proteger o portal do desenvolvedor, consulte Proteger o acesso ao portal do desenvolvedor do Gerenciamento de API.

Importante

• Esse artigo foi atualizado com as etapas para configurar um aplicativo Microsoft Entra usando a Biblioteca de Autenticação da Microsoft (MSAL).
• Se você configurou anteriormente um aplicativo Microsoft Entra para que o usuário entre usando a Biblioteca de Autenticação do Azure AD (ADAL), recomendamos que você migre para a MSAL.

Pré-requisitos

• Conclua o guia de início rápido Criar uma instância do Gerenciamento de API do Azure.

• Importar e publicar uma instância do Gerenciamento de API do Azure.

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

APLICA-SE A: Desenvolvedor | Standard | Premium

Navegar até a instância de Gerenciamento de API

1. No portal do Azure, pesquise e selecione serviços de Gerenciamento de API.

   

2. Na página Serviços de Gerenciamento de API, selecione a sua instância de Gerenciamento de API.

   

Habilitar a entrada do usuário usando o Microsoft Entra ID: portal

Para simplificar a configuração, o Gerenciamento de API pode habilitar automaticamente um provedor de aplicativo e de identidade do Microsoft Entra para usuários do portal do desenvolvedor. Como alternativa, você pode habilitar manualmente o provedor de identidade e de aplicativo Microsoft Entra.

Habilitar automaticamente o aplicativo e o provedor de identidade do Microsoft Entra

1. No menu à esquerda da instância do Gerenciamento de API, no Portal do desenvolvedor, selecione Visão geral do portal.

2. Na página Visão geral do portal, role para baixo até Habilitar a entrada do usuário com o Microsoft Entra ID.

3. Selecione Habilitar o Microsoft Entra ID.

4. Na página Habilitar o Microsoft Entra ID, selecione Habilitar o Microsoft Entra ID.

5. Selecione Fechar.

   

Depois que o provedor do Microsoft Entra estiver habilitado:

• Os usuários na instância especificada do Microsoft Entra podem entrar no portal do desenvolvedor usando uma conta do Microsoft Entra.
• Você poderá gerenciar a configuração do Microsoft Entra na página Portal do desenvolvedor>Identidades no portal.
• Opcionalmente, defina outras configurações de entrada selecionando Identidades>Configurações. Por exemplo, talvez você queira redirecionar usuários anônimos para a página de entrada.
• Republique o portal do desenvolvedor após qualquer alteração de configuração.

Habilitar manualmente o aplicativo e o provedor de identidade do Microsoft Entra

1. No menu à esquerda da instância do Gerenciamento de API, no Portal do desenvolvedor, selecione Identidades.

2. Selecione +Adicionar na parte superior para abrir o painel Adicionar provedor de identidade à direita.

3. Em Tipo, selecione Microsoft Entra ID no menu suspenso. Depois de selecionado, você poderá inserir outras informações necessárias.

   • Na lista suspensa Biblioteca de clientes, selecione MSAL.
   • Para adicionar a ID do cliente e o Segredo do cliente, consulte as etapas mais adiante no artigo.

4. Salve a URL de redirecionamento para depois.

   

   Observação

   Há duas URLs de redirecionamento:
   

   • A URL de redirecionamento aponta para o portal do desenvolvedor mais recente do API Management.
   • A URL de redirecionamento (portal preterido) aponta para o portal do desenvolvedor preterido do API Management.

   Recomendamos usar a URL de Redirecionamento do portal do desenvolvedor mais recente.

5. No navegador, abra o portal do Azure em uma nova guia.

6. Navegue até o Registros de aplicativo para registrar um aplicativo no Active Directory.

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

   • Defina Nome como um nome significativo, como developer-portal
   • Defina os Tipos de conta com suporte para Contas em qualquer diretório organizacional.
   • No URI de redirecionamento, selecione SPA (aplicativo de página única) e cole a URL de redirecionamento salva em uma etapa anterior.
   • Selecione Registrar.

8. Depois de ter registrado o aplicativo cliente, copie a ID do aplicativo (cliente) da página Visão geral.

9. Alterne para a guia do navegador com a instância do API Management.

10. Na janela Adicionar provedor de identidade, cole o valor ID do Aplicativo (cliente) na caixa ID do Cliente.

11. Alterne para a guia do navegador com o registro do Aplicativo.

12. Selecione o registro de aplicativo apropriado.

13. Na seção Gerenciar do menu lateral, selecione Certificados e segredos.

14. Na página Certificados e segredos, selecione Novo segredo do cliente na seção Segredos do cliente.

    • Insira uma Descrição.
    • Selecione uma opção para Expira.
    • Escolha Adicionar.

15. Copie o valor do segredo do cliente mostrado antes de deixar a página. Você precisará dela mais tarde.

16. Em Gerenciar no menu lateral, selecione Autenticação.

    1. Nas seções Concessão implícita e fluxos híbridos, marque a caixa de seleção Tokens de ID.
    2. Selecione Save.

17. Em Gerenciar no menu lateral, selecione Configuração de token>+ Adicionar declaração opcional.

    1. Em Tipo de token, selecione ID.
    2. Selecione (marque) as seguintes declarações: email, family_name, given_name.
    3. Selecione Adicionar. Se solicitado, selecione Ativar a permissão de perfil e email do Microsoft Graph.

18. Alterne para a guia do navegador com a instância do API Management.

19. Cole o segredo no campo Segredo do cliente no painel Adicionar provedor de identidade.

    Importante

    Atualize o Segredo do cliente antes de a chave expirar.

20. No campo Locatários permitidos do painel Adicionar provedor de identidade, especifique os domínios das instâncias do Microsoft Entra aos quais você deseja permitir acesso às APIs de instância de serviço do Gerenciamento de API.

    • Você pode separar múltiplos domínios com novas linhas, espaços ou vírgulas.

    Observação

    Você pode especificar vários domínios na seção Locatários Permitidos. Uma administração global deve conceder ao aplicativo acesso aos dados do diretório antes que os usuários possam entrar de um domínio diferente do domínio de registro do aplicativo original. Para conceder permissão, o administrador global deve:

    1. Vá para https://<URL of your developer portal>/aadadminconsent (por exemplo, https://contoso.portal.azure-api.net/aadadminconsent).
    2. Insira o nome de domínio do locatário do Microsoft Entra ao qual deseja conceder acesso.
    3. Selecione Enviar.

21. Depois de especificar a configuração desejada, selecione Adicionar.

22. Republique o portal do desenvolvedor para que a configuração da Microsoft Entra entre em vigor. No menu à esquerda, em Portal do desenvolvedor, escolha Visão geral do portal>Publicar.

Depois que o provedor do Microsoft Entra estiver habilitado:

• Os usuários na instância especificada do Microsoft Entra podem entrar no portal do desenvolvedor usando uma conta do Microsoft Entra.
• Você poderá gerenciar a configuração do Microsoft Entra na página Portal do desenvolvedor>Identidades no portal.
• Opcionalmente, defina outras configurações de entrada selecionando Identidades>Configurações. Por exemplo, talvez você queira redirecionar usuários anônimos para a página de entrada.
• Republique o portal do desenvolvedor após qualquer alteração de configuração.

Migrar para o MSAL

Se você tiver configurado anteriormente um aplicativo Microsoft Entra para que o usuário entre usando a ADAL, poderá usar o portal para migrar o aplicativo para a MSAL e atualizar o provedor de identidade em Gerenciamento de API.

Atualizar o aplicativo Microsoft Entra para compatibilidade com MSAL

Para obter as etapas, consulte Alternar URIs de redirecionamento para o tipo de aplicativo de página única.

Atualizar a configuração do provedor de identidade

1. No menu à esquerda da instância do Gerenciamento de API, no Portal do desenvolvedor, selecione Identidades.
2. Selecione Microsoft Entra ID na lista.
3. Na lista suspensa Biblioteca de clientes, selecione MSAL.
4. Selecione Atualizar.
5. Republique o portal do desenvolvedor.

Adicionar um grupo externo do Microsoft Entra

Agora que você habilitou o acesso para usuários em um locatário do Microsoft Entra, você pode:

• Adicionar grupos do Microsoft Entra ao Gerenciamento de API.
• Controlar a visibilidade do produto usando grupos do Microsoft Entra.

1. Navegue até a página Registro de Aplicativo para o aplicativo registrado na seção anterior.
2. Selecione Permissões de API.
3. Adicione as seguintes permissões mínimas de aplicativo para o API do Microsoft Graph:
   • Permissão de aplicativo User.Read.All – para que o Gerenciamento de API possa ler a associação de grupo do usuário para executar a sincronização de grupo no momento em que o usuário fizer login.
   • Group.Read.AllPermissão de aplicativo: para que o Gerenciamento de API possa ler os grupos do Microsoft Entra quando um administrador tentar adicionar o grupo ao Gerenciamento de API usando a folha Grupos no portal.
4. Selecione Conceder consentimento de administrador para {tenantname} para que você conceda acesso a todos os usuários neste diretório.

Você adiciona grupos externos do Microsoft Entra na guia Grupos da instância do Gerenciamento de API.

1. Em Portal do desenvolvedor no menu lateral, selecione Grupos.

2. Selecione o botão Adicionar grupo do Microsoft Entra.

   

3. Selecione o Locatário na lista suspensa.

4. Procure e selecione o grupo que você quer adicionar.

5. Pressione o botão Selecionar.

Depois de adicionar um grupo externo do Microsoft Entra, você poderá revisar e configurar as propriedades:

1. Selecione o nome do grupo na guia Grupos.
2. Edite as informações de Nome e Descrição do grupo.

Os usuários da instância configurada do Microsoft Entra agora podem:

• Conectar-se ao portal do desenvolvedor.
• Exibir e se inscrever em todos os grupos para os quais têm visibilidade.

Observação

Saiba mais sobre a diferença entre os tipos de permissões Delegadas e de Aplicativo no artigo Permissões e consentimento da plataforma de identidade da Microsoft.

Sincronizar os grupos do Microsoft Entra com o Gerenciamento de API

Os grupos configurados no Microsoft Entra devem sincronizar com o Gerenciamento de API para que você possa adicioná-los à sua instância. Se os grupos não sincronizarem automaticamente, siga um destes procedimentos para sincronizar as informações do grupo manualmente:

• Saia e entre no Microsoft Entra ID. Essa atividade geralmente dispara a sincronização de grupos.
• Verifique se o locatário de entrada do Microsoft Entra é especificado da mesma maneira (usando uma ID de locatário ou nome de domínio) em suas configurações no Gerenciamento de API. Especifique o locatário de entrada no provedor de identidade do Microsoft Entra ID para o portal do desenvolvedor e quando adicionar um grupo do Microsoft Entra ao Gerenciamento de API.

Portal do Desenvolvedor: Adicionar autenticação de conta do Microsoft Entra

No portal do desenvolvedor, você pode entrar com o Microsoft Entra ID usando o botão Entrar: widget OAuth incluído na página de logon do conteúdo padrão do portal do desenvolvedor.

Embora uma nova conta seja criada automaticamente quando um novo usuário entrar com o Microsoft Entra ID, você pode considerar adicionar o mesmo widget à página de inscrição. O formulário de inscrição: o widget OAuth representa um formulário usado para se inscrever com o OAuth.

Importante

Você precisa republicar o portal para que as alterações do Microsoft Entra ID entrem em vigor.

Conteúdo relacionado

• Saiba mais sobre o Microsoft Entra ID e o OAuth2.0.
• Saiba mais sobre a MSAL e a migração para a MSAL.
• Solucionar problemas de conectividade de rede com o Microsoft Graph de dentro de uma VNet.