Usar valores nomeados nas políticas de Gerenciamento de API do Azure

APLICA-SE A: todas as camadas do Gerenciamento de API

As políticas de Gerenciamento de API representam um recurso poderoso do sistema e permitem ao editor alterar o comportamento da API por meio de configuração. As políticas são um conjunto de instruções executadas em sequência, na solicitação ou na resposta de uma API. É possível construir declarações de política usando valores de texto literais, expressões de política e valores nomeados.

Os valores nomeados são uma coleção global de pares de nome/valor em cada instância de Gerenciamento de API. Não há limite imposto sobre o número de itens na coleção. Os valores nomeados podem ser usados para gerenciar valores de cadeia de caracteres constantes e segredos em todas as configurações e políticas de API.

Tipos de valor

Tipo	Descrição
Sem formatação	Cadeia de caracteres literal ou expressão de política
Segredo	A cadeia de caracteres literal ou a expressão de política que é criptografada pelo Gerenciamento de API
Key vault	Identificador de um segredo armazenado em um cofre de chaves do Azure.

Os valores ou segredos sem formatação podem conter expressões de política. Por exemplo, a expressão @(DateTime.Now.ToString()) retorna uma cadeia de caracteres que contém a data e a hora atuais.

Para obter detalhes sobre os atributos de valor nomeado, veja a Referência da API REST do Gerenciamento de API.

Segredos do cofre de chaves

Os valores secretos podem ser armazenados como cadeias de caracteres criptografadas no Gerenciamento de API (segredos personalizados) ou referenciando segredos no Azure Key Vault.

O uso de segredos de cofre de chaves é recomendado porque ajuda a melhorar a segurança do Gerenciamento de API:

• Os segredos armazenados nos cofres de chaves podem ser reutilizados entre os serviços
• As políticas de acesso granular podem ser aplicadas aos segredos
• Os segredos atualizados no cofre de chaves são automaticamente trocados no Gerenciamento de API. Após a atualização no cofre de chaves, um valor nomeado no Gerenciamento de API é atualizado dentro de 4 horas. Você também pode atualizar manualmente o segredo usando o portal do Azure ou por meio da API REST de gerenciamento.

Pré-requisitos

• Se você ainda não tiver criado uma instância de serviço do Gerenciamento de API, veja Criar uma instância de serviço do Gerenciamento de API.

Pré-requisitos para a integração do cofre de chaves

• Se você ainda não tiver um cofre de chaves, crie um. Para obter as etapas para criar um cofre de chaves, veja Início Rápido: Criar um cofre de chaves usando o portal do Azure.

  Para criar ou importar um segredo para o cofre de chaves, confira Início rápido: definir e recuperar um segredo do Azure Key Vault usando o portal do Azure.

• Habilite uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário na instância de Gerenciamento de API.

Configurar o acesso ao Key Vault

1. No portal, navegue até o cofre de chaves.

2. No menu à esquerda, selecione Configuração de acesso e anote o Modelo de permissão configurado.

3. Dependendo do modelo de permissão, configure uma política de acesso do cofre de chaves ou o acesso do RBAC do Azure para uma identidade gerenciada do Gerenciamento de API.

   Para adicionar uma política de acesso do cofre de chaves:
   

   1. No menu à esquerda, selecione Políticas de acesso.
   2. Na página Políticas de acesso, selecione + Criar.
   3. Na guia Permissões, em Permissões em Permissões de segredo, escolha Obter e Listar. Clique em Avançar.
   4. Na guia Entidade de segurança, Selecionar entidade de segurança, procure o nome do recurso da identidade gerenciada e selecione Avançar. Se você estiver usando uma identidade atribuída pelo sistema, a entidade de segurança será o nome da instância de Gerenciamento de API.
   5. Selecione novamente Avançar. Na guia Revisar + criar, selecione Criar.

   Para configurar o acesso ao RBAC do Azure:
   

   1. No menu à esquerda, selecione Controle de acesso (IAM) .
   2. Na página Controle de acesso (IAM), selecione Adicionar atribuição de função.
   3. Na guia Função, selecione Usuário de Segredos do Key Vault.
   4. Na guia Membros, selecione Identidade gerenciada>+ Selecionar membros.
   5. Na página Selecionar identidade gerenciada, escolha a identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância do Gerenciamento de API e clique em Selecionar.
   6. Selecione Examinar + atribuir.

Requisitos para firewall do Key Vault

Se o firewall do Key Vault estiver habilitado no seu cofre de chaves, os itens a seguir serão requisitos adicionais:

• Você deve usar a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API para acessar o cofre de chaves.

• No firewall do Key Vault, habilite a opção Permitir que os serviços confiáveis da Microsoft ignorem esse firewall.

• Verifique se o endereço IP do cliente local tem permissão para acessar o cofre de chaves temporariamente enquanto você seleciona um certificado ou segredo a ser adicionado ao Gerenciamento de API do Azure. Para obter mais informações, confira Definir configurações de rede do Azure Key Vault.

  Depois de concluir a configuração, você pode bloquear o endereço do cliente no firewall do cofre de chaves.

Requisitos de rede virtual

Se a instância do Gerenciamento de API for implantada em uma rede virtual, defina também as configurações de rede a seguir:

• Habilite um ponto de extremidade de serviço para o Azure Key Vault na sub-rede do Gerenciamento de API.
• Configure uma regra de NSG (grupo de segurança de rede) para permitir tráfego de saída para as marcas de serviço AzureKeyVault e AzureActiveDirectory.

Para obter detalhes, confira Configuração de rede ao configurar o Gerenciamento de API do Azure em uma VNet.

Adicionar ou editar um valor nomeado

Adicionar um segredo de cofre de chaves ao Gerenciamento de API

Veja Pré-requisitos para integração do cofre de chaves.

Importante

Ao adicionar um segredo do cofre de chaves à instância do Gerenciamento de API, você deve ter permissões para listar segredos do cofre de chaves.

Cuidado

Ao usar um segredo do cofre de chaves no Gerenciamento de API, tenha cuidado para não excluir o segredo, o cofre de chaves ou a identidade gerenciada usada para acessar o cofre de chaves.

1. No portal do Azure, navegue até a instância do Gerenciamento de API.

2. Em APIs, selecione Valores nomeados>+Adicionar.

3. Insira um identificador de Nome e insira um Nome de exibição usado para fazer referência à propriedade nas políticas.

4. Em Tipo de valor, selecione Cofre de chaves.

5. Insira o identificador de um segredo do cofre de chaves (sem versão) ou escolha Selecionar para selecionar um segredo de um cofre de chaves.

   Importante

   Se você mesmo inserir um identificador do segredo do cofre de chaves, verifique se ele não tem informações de versão. Caso contrário, o segredo não será trocado automaticamente no Gerenciamento de API após uma atualização no cofre de chaves.

6. Em Identidade do cliente, selecione uma identidade gerenciada atribuída pelo sistema ou uma existente atribuída pelo usuário. Saiba como adicionar ou modificar identidades gerenciadas no serviço de Gerenciamento de API.

   Observação

   A identidade precisa de permissões para obter e listar segredos do cofre de chaves. Se você ainda não tiver configurado o acesso ao cofre de chaves, o Gerenciamento de API perguntará se ele pode configurar automaticamente a identidade com as permissões necessárias.

7. Adicione uma ou mais marcas opcionais para ajudar a organizar os valores nomeados e, em seguida, clique em Salvar.

8. Selecione Criar.

   

Adicione um valor simples ou secreto ao Gerenciamento de API

Portal

1. No portal do Azure, navegue até a instância do Gerenciamento de API.
2. Em APIs, selecione Valores nomeados>+Adicionar.
3. Insira um identificador de Nome e insira um Nome de exibição usado para fazer referência à propriedade nas políticas.
4. Em Tipo de valor, selecione Sem formatação ou Segredo.
5. Em Valor, insira uma expressão de cadeia de caracteres ou de política.
6. Adicione uma ou mais marcas opcionais para ajudar a organizar os valores nomeados e, em seguida, clique em Salvar.
7. Selecione Criar.

Quando o valor nomeado é criado, você pode editá-lo selecionando o nome. Se você alterar o nome de exibição, todas as políticas que fizerem referência a esse valor nomeado serão automaticamente atualizadas para usar o novo de exibição.

CLI do Azure

Para começar a usar a CLI 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.

Para adicionar um valor nomeado, use o comando az apim nv create:

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

Depois de criar um valor nomeado, você pode atualizá-lo usando o comando az apim nv update. Para ver todos os valores nomeados, execute o comando az apim nv list:

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Para ver os detalhes do valor nomeado que você criou para este exemplo, execute o comando az apim nv show:

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Este exemplo é um valor secreto. O comando anterior não retorna o valor. Para ver o valor, execute o comando az apim nv show-secret:

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Para excluir um valor nomeado, use o comando az apim nv delete:

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Usar um valor nomeado

Os exemplos nesta seção usam os valores nomeados mostrados na tabela a seguir.

Nome	Valor	Segredo
ContosoHeader	TrackingId	Falso
ContosoHeaderValue	••••••••••••••••••••••	True
ExpressionProperty	@(DateTime.Now.ToString())	Falso
ContosoHeaderValue2	This is a header value.	Falso

Para usar um valor nomeado em uma política, coloque o nome entre chaves como {{ContosoHeader}}, conforme mostrado no exemplo a seguir:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

Neste exemplo, ContosoHeader é usado como o nome de um cabeçalho em uma política set-header e ContosoHeaderValue é usado como o valor desse cabeçalho. Quando essa política é avaliada durante uma solicitação ou uma resposta para o gateway de Gerenciamento de API, {{ContosoHeader}} e {{ContosoHeaderValue}} são substituídos por seus respectivos valores.

Os valores nomeados podem ser usados como valores de atributo ou de elemento, como mostra o exemplo anterior, mas também podem ser inseridos ou combinados com parte de uma expressão de texto literal, como mostra o exemplo a seguir:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Os valores nomeados também podem conter expressões de política. No exemplo a seguir, a expressão ExpressionProperty é usada.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Quando essa política for avaliada, {{ExpressionProperty}} é substituída pelo seu valor, @(DateTime.Now.ToString()). Como o valor é uma expressão de política, a expressão é avaliada e a política prossegue com a execução.

Você pode testar isso no portal do Azure ou no portal do desenvolvedor chamando uma operação que tenha uma política com valores nomeados no escopo. No exemplo a seguir, uma operação é chamada com os dois exemplos de políticas set-header anteriores com valores nomeados. Observe que a resposta contém dois cabeçalhos personalizados configurados usando políticas com valores nomeados.

Se você analisar o Rastreamento de API de uma chamada que inclui os dois exemplos de política anteriores com valores nomeados, será possível ver as duas políticas set-header com os valores nomeados inseridos, bem como a avaliação da expressão de política para o valor nomeado que continha a expressão de política.

A interpolação da cadeia de caracteres também pode ser usada com valores nomeados.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

O valor para CustomHeader será The URL encoded value is This+is+a+header+value..

Cuidado

Se uma política fizer referência a um segredo no Azure Key Vault, o valor do cofre de chaves ficará visível para os usuários que têm acesso às assinaturas habilitadas para Rastreamento da solicitação de API.

Embora os valores nomeados possam conter expressões de política, eles não podem conter outros valores nomeados. Se o texto que contém uma referência de valor nomeado for usado para um valor, como Text: {{MyProperty}}, essa referência não será resolvida e substituída.

Excluir um valor nomeado

Para excluir um valor nomeado, selecione o nome e, em seguida, selecione Excluir no menu de contexto ( ... ).

Importante

Se o valor nomeado for consultado por quaisquer políticas do Gerenciamento de API, não será possível excluí-lo até que você remova o valor nomeado de todas as políticas que o utilizam.

Próximas etapas

• Saiba mais sobre como trabalhar com políticas
  • Políticas no Gerenciamento de API
  • Referência de política
  • Expressões de política