Autorizar as contas de programador ao utilizar o Microsoft Entra ID no API Management do Azure

Artigo
12/09/2023

Neste artigo, vai aprender a:

Habilite o acesso ao portal do desenvolvedor para usuários a partir do Microsoft Entra ID.
Gerencie grupos de usuários do Microsoft Entra adicionando grupos externos que contenham os usuários.

Para obter uma descrição geral das opções para proteger o portal do programador, veja Proteger o acesso ao portal do programador na Gestão de API.

Importante

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

Pré-requisitos

Conclua o início rápido Criar uma instância de Gerenciamento de API do Azure.
Importe e publique uma API na instância de Gerenciamento de API do Azure.

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

APLICA-SE A: Developer | Padrão | Prémio

Vá para a sua instância de Gestão de API

No portal do Azure, procure e selecione serviços de Gerenciamento de API.
Na página Serviços de Gerenciamento de API, selecione sua instância de Gerenciamento de API.

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

Habilitar automaticamente o aplicativo Microsoft Entra e o provedor de identidade

No menu esquerdo da instância de Gerenciamento de API, em Portal do desenvolvedor, selecione Visão geral do portal.
Na página Visão geral do Portal, role para baixo até Habilitar entrada do usuário com a ID do Microsoft Entra.
Selecione Ativar ID do Microsoft Entra.
Na página Ativar ID do Microsoft Entra, selecione Ativar ID do Microsoft Entra.
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ê pode gerenciar a configuração do Microsoft Entra na página Identidades do portal>do desenvolvedor no portal.
Opcionalmente, configure outras configurações de entrada selecionando Configurações de identidades>. 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 Microsoft Entra e o provedor de identidade

No menu esquerdo da instância de Gerenciamento de API, em Portal do desenvolvedor, selecione Identidades.
Selecione +Adicionar na parte superior para abrir o painel Adicionar provedor de identidade à direita.
Em Tipo, selecione ID do Microsoft Entra no menu suspenso. Uma vez selecionado, você poderá inserir outras informações necessárias.
- Na lista suspensa Biblioteca de clientes, selecione MSAL.
- Para adicionar ID do cliente e segredo do cliente, consulte as etapas mais adiante no artigo.
Salve o URL de redirecionamento para mais tarde.
Nota

Existem dois URLs de redirecionamento:
- A URL de redirecionamento aponta para o portal do desenvolvedor mais recente do Gerenciamento de API.
- URL de redirecionamento (portal preterido) aponta para o portal do desenvolvedor preterido do Gerenciamento de API.
Recomendamos que você use a URL de redirecionamento mais recente do portal do desenvolvedor.
No navegador, abra o portal do Azure em uma nova guia.
Navegue até Registros de aplicativo para registrar um aplicativo no Ative Directory.
Selecione Novo registo. Na página Registrar um aplicativo, defina os valores da seguinte maneira:
- Definir Nome como um nome significativo, como developer-portal
- Defina Tipos de conta suportados como Contas em qualquer diretório organizacional.
- Em URI de redirecionamento, selecione Aplicativo de página única (SPA) e cole a URL de redirecionamento salva de uma etapa anterior.
- Selecione Registar.
Depois de registrar o aplicativo, copie o ID do aplicativo (cliente) na página Visão geral.
Alterne para a guia do navegador com sua instância de Gerenciamento de API.
Na janela Adicionar provedor de identidade, cole o valor da ID do aplicativo (cliente) na caixa ID do cliente.
Mude para o separador do navegador com o registo da aplicação.
Selecione o registro de aplicativo apropriado.
Na seção Gerenciar do menu lateral, selecione Certificados & segredos.
Na página Certificados & segredos, selecione o botão Novo segredo do cliente em Segredos do cliente.
- Insira uma descrição.
- Selecione qualquer opção para Expira.
- Escolha Adicionar.
Copie o valor Secret do cliente antes de sair da página. Precisará dele mais tarde.
Em Gerenciar no menu lateral, selecione Autenticação.
1. Na seção Concessão implícita e fluxos híbridos, marque a caixa de seleção Tokens de ID.
2. Selecione Guardar.
Em Gerenciar no menu lateral, selecione Configuração de token>+ Adicionar declaração opcional.
1. Em Tipo de token, selecione ID.
2. Selecione (verifique) as seguintes declarações: e-mail, family_name given_name.
3. Selecione Adicionar. Se solicitado, selecione Ativar o email do Microsoft Graph, permissão de perfil.
Alterne para a guia do navegador com sua instância de Gerenciamento de API.
Cole o segredo no campo Segredo do cliente no painel Adicionar provedor de identidade.

Importante

Atualize o segredo do cliente antes que a chave expire.
No campo Adicionar locatários permitidos do painel do provedor de identidade, especifique os domínios da instância do Microsoft Entra aos quais você deseja conceder acesso às APIs da instância do serviço de Gerenciamento de API.
- Você pode separar vários domínios com novas linhas, espaços ou vírgulas.
Nota

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 em 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 ele deseja conceder acesso.
3. Selecione Submeter.
Depois de especificar a configuração desejada, selecione Adicionar.
Republique o portal do desenvolvedor para que a configuração do Microsoft Entra entre em vigor. No menu à esquerda, em Portal do desenvolvedor, selecione 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ê pode gerenciar a configuração do Microsoft Entra na página Identidades do portal>do desenvolvedor no portal.
Opcionalmente, configure outras configurações de entrada selecionando Configurações de identidades>. 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ê configurou anteriormente um aplicativo Microsoft Entra para entrada de usuário usando a ADAL, poderá usar o portal para migrar o aplicativo para MSAL e atualizar o provedor de identidade no Gerenciamento de API.

Atualizar o aplicativo Microsoft Entra para compatibilidade com MSAL

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

Atualizar a configuração do provedor de identidade

No menu esquerdo da instância de Gerenciamento de API, em Portal do desenvolvedor, selecione Identidades.
Selecione Microsoft Entra ID na lista.
Na lista suspensa Biblioteca de clientes, selecione MSAL.
Selecione Atualizar.
Republique seu 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:

Adicione grupos do Microsoft Entra ao Gerenciamento de API.
Controle a visibilidade do produto usando grupos do Microsoft Entra.

Navegue até a página Registro do aplicativo para o aplicativo que você registrou na seção anterior.
Selecione Permissões da API.
Adicione as seguintes permissões mínimas de aplicativo para a API do Microsoft Graph:
- User.Read.All permissão de aplicativo – 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.All permissã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.
Selecione Conceder consentimento de administrador para {tenantname} para que você conceda acesso a todos os usuários neste diretório.

Agora você pode adicionar grupos externos do Microsoft Entra na guia Grupos da sua instância de Gerenciamento de API.

Em Portal do desenvolvedor , no menu lateral, selecione Grupos.
Selecione o botão Adicionar grupo do Microsoft Entra.
Selecione o Locatário na lista suspensa.
Procure e selecione o grupo que pretende adicionar.
Pressione o botão Select (Selecionar ).

Depois de adicionar um grupo externo do Microsoft Entra, você pode revisar e configurar suas propriedades:

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

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

Faça login no portal do desenvolvedor.
Veja e inscreva-se em quaisquer grupos para os quais eles tenham visibilidade.

Nota

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

Sincronizar grupos do Microsoft Entra com o Gerenciamento de API

Os grupos configurados no Microsoft Entra devem ser sincronizados 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 aciona a sincronização de grupos.
Certifique-se de que o locatário de entrada do Microsoft Entra seja especificado da mesma maneira (usando um ID de locatário ou nome de domínio) em suas definições de configuração no Gerenciamento de API. Você especifica o locatário de entrada no provedor de identidade do Microsoft Entra ID para o portal do desenvolvedor e quando adiciona 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 entrada do conteúdo padrão do portal do desenvolvedor.

Captura de tela mostrando o widget OAuth no portal do desenvolvedor.

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