Acessar produtos e APIs com segurança com os aplicativos do Microsoft Entra

APLICA-SE A: Desenvolvedor | Básico | Padrão | Premium

O Gerenciamento de API agora dá suporte ao acesso interno baseado em aplicativo do OAuth 2.0 às APIs do produto usando o fluxo de credenciais do cliente. Esse recurso permite que os gerentes de API registrem os aplicativos do Microsoft Entra ID, simplificando o acesso seguro à API para desenvolvedores por meio da autorização do OAuth 2.0.

Com este recurso:

• Os gerentes de API definem uma propriedade de produto para habilitar o acesso baseado em aplicativo.
• Os gerentes de API registram aplicativos cliente no Microsoft Entra ID para limitar o acesso a produtos específicos.
• Os desenvolvedores podem acessar as credenciais do aplicativo cliente usando o portal do desenvolvedor do Gerenciamento de API.
• Usando o fluxo de credenciais do cliente OAuth 2.0, os desenvolvedores ou aplicativos obtêm tokens que podem incluir em solicitações de API
• Os tokens apresentados em solicitações de API são validados pelo gateway do Gerenciamento de API para autorizar o acesso às APIs do produto.

Pré-requisitos

• Uma instância do Gerenciamento de API implantada na camada Premium, Standard, Básico ou Desenvolvedor. Se você precisar implantar uma instância, veja Criar uma instância de serviço do Gerenciamento de API.

• Pelo menos um produto em sua instância do Gerenciamento de API, com pelo menos uma API atribuída a ele.

  • O produto deve estar no estado Publicado para que possa ser acessado pelos desenvolvedores por meio do portal do desenvolvedor.
  • Para testar, você pode usar o produto Starter padrão e a API de Eco que é adicionada a ele.
  • Se você quiser criar um produto, veja Criar e publicar um produto.

• Permissões suficientes em seu locatário do Microsoft Entra para atribuir a função Administrador de aplicativos, o que requer pelo menos a função Administrador de funções com privilégios.

• Opcionalmente, adicione um ou mais usuários em sua instância do Gerenciamento de API.

• Se você optar por usar o Azure PowerShell localmente:
  • Instale a versão mais recente do módulo do Az PowerShell.
  • Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
• Se você optar por usar o Azure Cloud Shell:
  • Confira Visão geral do Azure Cloud Shell para obter mais informações.

Configurar uma identidade gerenciada

1. Habilite uma identidade gerenciada atribuída pelo sistema parao Gerenciamento de API na sua instância do Gerenciamento de API.

2. Atribua a identidade à função RBAC do Administrador de aplicativos no Microsoft Entra ID. Para atribuir a função:

   1. Entre no portal e navegue até Microsoft Entra ID.
   2. No menu à esquerda, selecione Gerenciar>Funções e administradores.
   3. Selecione Administrador de aplicativos.
   4. No menu à esquerda, selecione Gerenciar>Atribuições>+ Adicionar atribuições.
   5. Na página Adicionar atribuições, pesquise a identidade gerenciada da instância do Gerenciamento de API pelo nome (o nome da instância do Gerenciamento de API). Selecione a identidade gerenciada e escolha Adicionar.

Habilitar o acesso baseado em aplicativo para o produto

Siga estas etapas para habilitar o Acesso baseado em aplicativo para um produto. Um produto deve ter essa configuração habilitada para ser associado a um aplicativo cliente em etapas posteriores.

O exemplo a seguir usa o produto Starter, mas escolha qualquer produto publicado que tenha pelo menos uma API atribuída a ele.

1. Entre no portal na seguinte URL personalizada para o recurso de aplicativos: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplicativos
2. Navegue até sua instância de Gerenciamento de API.
3. No menu à esquerda, em APIs, selecione Produtos.
4. Escolha o produto que você quer configurar, como o produto Starter.
5. No menu à esquerda, em Produto, selecione Propriedades.
6. Na seção Acesso baseado em aplicativo, habilite a configuração do Token do OAuth 2.0 (mais seguro).
7. Opcionalmente, habilite a configuração de Chave de assinatura. Se você habilitar o acesso baseado em aplicativo e um requisito de assinatura, o gateway do Gerenciamento de API poderá aceitar um token do OAuth 2.0 ou uma chave de assinatura para acesso às APIs do produto.
8. Clique em Salvar.

Habilitar o acesso baseado em aplicativo cria um aplicativo empresarial de back-end no Microsoft Entra ID para representar o produto. A ID do aplicativo de back-end é exibida na página Propriedades do produto.

(Opcional) Examinar as configurações do aplicativo de produto no Microsoft Entra ID

Opcionalmente, examine as configurações do aplicativo empresarial de back-end criado no Microsoft Entra ID para representar o produto.

O aplicativo é nomeado com o seguinte formato: APIMProductApplication<product-name>. Por exemplo, se o nome do produto for Starter, o nome do aplicativo será APIMProductApplicationStarter. O aplicativo tem uma Função de aplicativo definida.

Para examinar as configurações do aplicativo nos Registros de aplicativo:

1. Entre no portal e navegue até Microsoft Entra ID>Gerenciar>Registros de aplicativo.
2. Selecione Todos os aplicativos.
3. Pesquise e selecione o aplicativo criado pelo Gerenciamento de API.
4. No menu à esquerda, em Gerenciar, selecione Funções de aplicativo.
5. Confirme a função de aplicativo definida pelo Gerenciamento de API do Azure, conforme mostrado na seguinte captura de tela:

Registrar os aplicativo cliente para acessar o produto

Agora, registre um aplicativo cliente que limite o acesso a um ou mais produtos.

• Um produto deve ter o Acesso baseado em aplicativo habilitado para ser associado a um aplicativo cliente.
• Cada aplicativo cliente tem um único usuário (proprietário) na instância do Gerenciamento de API. Somente o proprietário pode acessar APIs do produto por meio do aplicativo.
• Um produto pode ser associado a mais de um aplicativo cliente.

Para registrar um aplicativo cliente:

1. Entre no portal na seguinte URL personalizada para o recurso de aplicativos: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplicativos

2. Navegue até sua instância de Gerenciamento de API.

3. No menu à esquerda, em APIs, selecione Aplicativos>+ Registrar aplicativo.

4. Na página Registrar um aplicativo, insira as seguintes configurações de aplicativo:

   • Nome: insira um nome para o aplicativo.
   • Proprietário: selecione o proprietário do aplicativo na lista suspensa de usuários na instância do Gerenciamento de API.
   • Conceder acesso a produtos selecionados: selecione um ou mais produtos na instância do Gerenciamento de API que foram habilitados anteriormente para Acesso baseado em aplicativo.
   • Descrição: opcionalmente, insira uma descrição.

   

5. Selecione Registrar.

O aplicativo é adicionado à lista de aplicativos na página Aplicativos. Selecione o aplicativo para exibir detalhes como a ID do cliente. Você precisa dessa ID para gerar um token para chamar a API do produto.

Gerar o segredo do cliente

Um segredo do cliente deve ser gerado para que o aplicativo cliente use o fluxo de credenciais do cliente do OAuth 2.0. O segredo é válido por um ano, mas pode ser regenerado a qualquer momento.

1. Na página Aplicativos, selecione o aplicativo que você criou.

2. Na página Visão geral do aplicativo, ao lado do Segredo do Cliente, selecione Adicionar segredo.

3. Na página Novo segredo do cliente, selecione Gerar.

   Um segredo do cliente é gerado e exibido no campo Segredo do cliente. Copie o valor do segredo e armazene-o com segurança. Você não poderá recuperá-lo novamente depois de fechar a página.

4. Selecione Fechar.

(Opcional) Examinar as configurações do aplicativo cliente no Microsoft Entra ID

Opcionalmente, examine as configurações do aplicativo cliente no Microsoft Entra ID.

O aplicativo é nomeado com o seguinte formato: APIMApplication<product-name>. Por exemplo, se o nome do produto for Starter, o nome do aplicativo será semelhante a APIMApplicationStarter.

Para examinar as configurações do aplicativo nos Registros de aplicativo:

1. Entre no portal e navegue até Microsoft Entra ID>Gerenciar>Registros de aplicativo.

2. Selecione Todos os aplicativos.

3. Pesquise e selecione o aplicativo cliente criado pelo Gerenciamento de API.

4. No menu à esquerda, em Gerenciar, selecione permissões de API.

5. Confirme se o aplicativo tem permissões para acessar o aplicativo ou aplicativos de produto de back-end.

   Por exemplo, se o aplicativo cliente conceder acesso ao produto Starter, o aplicativo terá as permissões Product.Starter.All para acessar o aplicativo APIMProductApplicationStarter.

   

Obter configurações de aplicativo no portal do desenvolvedor

Os usuários podem entrar no portal do desenvolvedor para exibir os aplicativos cliente que possuem.

1. Entre no portal do desenvolvedor (https://<your-apim-instance-name>.developer.azure-api.net) usando uma conta de usuário que foi definida como o proprietário de um aplicativo cliente.

2. No menu de navegação superior, selecione Aplicativos.

3. Os aplicativos que o usuário possui aparecem na lista.

4. Selecione um aplicativo para exibir seus detalhes, como o ID do cliente, o segredo do cliente e o escopo. Esses valores são necessários para gerar um token para chamar as APIs do produto.

   

Criar token e usar com a chamada à API

Depois de habilitar o acesso baseado em aplicativo para um produto e registrar um aplicativo cliente, um desenvolvedor ou aplicativo poderá gerar um token para chamar as APIs do produto. O token deve ser incluído no cabeçalho Authorization de uma solicitação.

Por exemplo, um desenvolvedor ou aplicativo pode executar os scripts do Azure PowerShell a seguir para chamar o aplicativo cliente para gerar um token e, em seguida, usar o token para chamar uma API de produto no Gerenciamento de API.

Chamar o aplicativo cliente para gerar token

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Chamar a API do produto usando o token

O token gerado na etapa anterior é usado para chamar uma API de produto. O token é passado no cabeçalho Autorização da solicitação. A instância do Gerenciamento de API valida o token e autoriza o acesso à API.

O script a seguir mostra uma chamada de exemplo para a API de eco.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Resolução de problemas

Erro interno do servidor ao registrar aplicativos no portal

Se você não conseguir listar aplicativos ou receber um erro interno do servidor ao registrar aplicativos no portal, verifique o seguinte:

• A função Administrador de Aplicativos é atribuída à identidade gerenciada da instância de Gerenciamento de API no Microsoft Entra ID.
• Você está conectado ao portal na seguinte URL personalizada para o recurso de aplicativos: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplicativos. Essa URL é necessária para acessar o recurso de aplicativos no Gerenciamento de API.

Conteúdo relacionado

• Criar e publicar um produto
• Autenticação e autorização em APIs no Gerenciamento de API