Acesse produtos e APIs com segurança com aplicativos Microsoft Entra

APLICA-SE A: Desenvolvedor | Básico | Padrão | Avançado

A Gestão de API agora oferece suporte integrado a acesso baseado em aplicações OAuth 2.0 às APIs de produtos usando fluxo de credenciais do cliente. Esse recurso permite que os gerentes de API registrem aplicativos Microsoft Entra ID, simplificando o acesso seguro à API para desenvolvedores por meio da autorização 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 de Gerenciamento de API para autorizar o acesso às APIs do produto.

Pré-requisitos

• Uma instância de Gerenciamento de API implantada na camada Premium, Standard, Basic ou Developer . Se você precisar implantar uma instância, consulte Criar uma instância de serviço de Gerenciamento de API.

• Pelo menos um produto em sua instância de 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 através do portal do desenvolvedor.
  • Para testes, você pode usar o produto Starter padrão e a API Echo adicionada a ele.
  • Se quiser criar um produto, consulte Criar e publicar um produto.

• Permissões suficientes no Microsoft Entra tenant para atribuir a função Application Administrator, que requer pelo menos a função Privileged Role Administrator.

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

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

Configurar identidade gerenciada

1. Habilite uma identidade gerenciada atribuída ao sistema para o Gerenciamento de API em sua instância de Gerenciamento de API.

2. Atribua a identidade à função RBAC do Administrador de Aplicativos na ID do Microsoft Entra. 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 do aplicativo.
   4. No menu à esquerda, selecione Gerenciar>atribuições>.
   5. Na página Adicionar atribuições , procure a identidade gerenciada da instância de Gerenciamento de API pelo nome (o nome da instância de Gerenciamento de API). Selecione a identidade gerenciada e, em seguida, selecione Adicionar.

Habilitar o acesso baseado em aplicativos 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. Inicie sessão no portal no seguinte URL personalizado para a funcionalidade de aplicações: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplicações
2. Navegue até sua instância de Gerenciamento de API.
3. No menu à esquerda, em APIs, selecione Produtos.
4. Escolha o produto que deseja 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 de token OAuth 2.0 (mais seguro).
7. Opcionalmente, habilite a configuração Chave de assinatura . Se você habilitar o acesso baseado em aplicativo e um requisito de assinatura, o gateway de Gerenciamento de API poderá aceitar um token OAuth 2.0 ou uma chave de assinatura para acessar as APIs do produto.
8. Selecione Guardar.

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

(Opcional) Revise as configurações do aplicativo do produto na ID do Microsoft Entra

Opcionalmente, revise 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 rever as definições da aplicação em Registos de aplicações:

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

Registrar aplicativo cliente para acessar o produto

Agora registre um aplicativo cliente que limita 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 de 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. Inicie sessão no portal no seguinte URL personalizado para a funcionalidade de aplicações: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplicações

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 do aplicativo:

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

   

5. Selecione Register.

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

Gerar segredo do cliente

Um segredo de cliente deve ser gerado para que o aplicativo cliente use o fluxo de credenciais do cliente 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 de 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 . Certifique-se de copiar o valor secreto e armazená-lo com segurança. Você não poderá recuperá-lo novamente depois de fechar a página.

4. Selecione Fechar.

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

Opcionalmente, revise 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 ao APIMApplicationStarter.

Para rever as definições da aplicação em Registos de aplicações:

1. Entre no portal e navegue até Gerir Microsoft Entra ID>Registos de aplicações.

2. Selecione Todos os aplicativos.

3. Procure 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(s) aplicativo(s) do produto de back-end.

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

   

Obter configurações do 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 Aplicações.

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

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

   

Criar token e usar com chamada de API

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

Por exemplo, um desenvolvedor ou aplicativo pode executar os seguintes scripts do Azure PowerShell 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 token

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

O script a seguir mostra um exemplo de chamada para a API echo.

# 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

Soluçã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 de Administrador de Aplicativos é atribuída à identidade gerenciada da instância de Gerenciamento de API na ID do Microsoft Entra.
• Você está conectado ao portal na seguinte URL personalizada para o recurso de aplicativos: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplicações. 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 para APIs no Gerenciamento de API