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

APLICA-SE A: Todas as camadas de gerenciamento de API

As políticas de gerenciamento de API são um recurso poderoso do sistema que permite que o editor altere o comportamento da API por meio da configuração. As políticas são uma coleção de instruções que são executadas sequencialmente no pedido ou na resposta de uma API. As declarações de política podem ser construídas usando valores de texto literal, expressões de política e valores nomeados.

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

Tipos de valor

Tipo	Description
Simples	Cadeia de caracteres literal ou expressão de política
Segredo	Cadeia de caracteres literal ou expressão de política criptografada pelo Gerenciamento de API
Cofre de chaves	Identificador de um segredo armazenado em um cofre de chaves do Azure.

Valores simples ou segredos podem conter expressões de política. Por exemplo, a expressão @(DateTime.Now.ToString()) retorna uma cadeia de caracteres contendo a data e hora atuais.

Para obter detalhes sobre os atributos de valor nomeado, consulte a referência da API REST de 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 fazendo referência a segredos no Cofre de Chaves do Azure.

O uso de segredos do 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 em todos os serviços
• Políticas de acesso granulares podem ser aplicadas a segredos
• Os segredos atualizados no cofre de chaves são alternados automaticamente 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.

Nota

Os segredos armazenados no Cofre de Chaves do Azure devem ter entre 1 e 4096 caracteres, pois o Gerenciamento de API não pode recuperar valores que excedam esse limite.

Pré-requisitos

• Se você ainda não criou uma instância de serviço de Gerenciamento de API, consulte Criar uma instância de serviço de Gerenciamento de API.

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

Nota

Atualmente, esse recurso não está disponível em espaços de trabalho.

• Se ainda não tiver um cofre de chaves, crie um. Para conhecer as etapas para criar um cofre de chaves, consulte Guia de 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, consulte Guia de início rápido: definir e recuperar um segredo do Cofre de Chaves do Azure usando o portal do Azure.

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

Configurar o acesso ao cofre de chaves

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

2. No menu à esquerda, selecione Configuração do Access e anote o modelo de permissão que está configurado.

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

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

   1. No menu à esquerda, selecione Políticas de acesso.
   2. Na página Políticas de acesso , selecione + Criar.
   3. No separador Permissões, em Permissões secretas, selecione Obter e Listar e, em seguida, selecione Seguinte.
   4. No separador Principal, Selecione entidade de segurança, procure o nome do recurso da sua identidade gerida e, em seguida, selecione Seguinte. Se você estiver usando uma identidade atribuída ao sistema, o principal será o nome da sua instância de Gerenciamento de API.
   5. Selecione Avançar novamente. No separador Rever + criar, selecione Criar.

   Para configurar o acesso ao Azure RBAC:
   

   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 do Certificado do Cofre da Chave.
   4. Na guia Membros, selecione Identidade> gerenciada+ Selecionar membros.
   5. Na página Selecionar identidade gerenciada, selecione a identidade gerenciada atribuída ao sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância de Gerenciamento de API e selecione Selecionar.
   6. Selecione Rever + atribuir.

Requisitos para o firewall do Key Vault

Se o firewall do Cofre da Chave estiver habilitado no cofre de chaves, os seguintes requisitos são adicionais:

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

• No firewall do Cofre de Chaves, habilite a opção Permitir que Serviços Microsoft Confiáveis ignorem esse firewall .

• Certifique-se de que o endereço IP do cliente local tenha permissão para acessar o cofre de chaves temporariamente enquanto seleciona um certificado ou segredo para adicionar ao Gerenciamento de API do Azure. Para obter mais informações, consulte Configurar configurações de rede do Cofre da Chave do Azure.

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

Requisitos da rede virtual

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

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

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

Adicionar ou editar um valor nomeado

Adicionar um segredo do cofre de chaves ao Gerenciamento de API

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

Importante

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

Atenção

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 usados para acessar o cofre de chaves.

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

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

3. Insira um identificador Name e insira um Nome para exibição usado para fazer referência à propriedade em 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 de segredo do cofre de chaves, certifique-se de que ele não tenha informações de versão. Caso contrário, o segredo não será girado 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 pelo usuário. Saiba como adicionar ou modificar identidades gerenciadas em seu serviço de Gerenciamento de API.

   Nota

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

7. Adicione uma ou mais etiquetas opcionais para ajudar a organizar os seus valores nomeados e, em seguida , Guarde.

8. Selecione Criar.

   

Adicionar um valor simples ou secreto ao Gerenciamento de API

Portal

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

Depois que o valor nomeado for criado, você poderá editá-lo selecionando o nome. Se você alterar o nome para exibição, todas as políticas que fazem referência a esse valor nomeado serão atualizadas automaticamente para usar o novo nome para 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, 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.

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 seus 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	False
ContosoHeaderValue	••••••••••••••••••••••	True
ExpressionProperty	@(DateTime.Now.ToString())	False
ContosoHeaderValue2	This is a header value.	False

Para usar um valor nomeado em uma política, coloque seu nome para exibição dentro de um par duplo de chaves como , conforme {{ContosoHeader}}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 set-header política e ContosoHeaderValue é usado como o valor desse cabeçalho. Quando essa política é avaliada durante uma solicitação ou resposta ao gateway {{ContosoHeader}} de Gerenciamento de API e {{ContosoHeaderValue}} é substituída por seus respetivos valores.

Os valores nomeados podem ser usados como valores completos de atributos ou elementos, conforme mostrado no exemplo anterior, mas também podem ser inseridos ou combinados com parte de uma expressão de texto literal, conforme mostrado no 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 ExpressionProperty expressão é usada.

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

Quando esta política é 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 sua 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 as duas políticas de exemplo set-header anteriores com valores nomeados. Observe que a resposta contém dois cabeçalhos personalizados que foram configurados usando políticas com valores nomeados.

Se você examinar o rastreamento de API de saída para uma chamada que inclui as duas políticas de exemplo anteriores com valores nomeados, poderá ver as duas set-header políticas 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 de 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..

Atenção

Se uma política fizer referência a um segredo no Cofre de Chaves do Azure, o valor do cofre de chaves ficará visível para os usuários que têm acesso a assinaturas habilitadas para rastreamento de solicitações 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 referenciado por quaisquer políticas de Gerenciamento de API, você não poderá excluí-lo até remover o valor nomeado de todas as políticas que o usam.

Próximos passos

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