Compartilhar via

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

  • Artigo

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.

Valores registrados no portal do Azure

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.

Observação

Os segredos armazenados no Azure Key Vault devem ter entre 1 e 4.096 caracteres, pois o Gerenciamento de API não pode recuperar valores que excedam esse limite.

Pré-requisitos

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

Observação

Atualmente, esse recurso não está disponível em workspaces.

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 do Certificado 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.

    Adicionar valor do segredo do cofre de chaves

Adicione um valor simples ou secreto ao Gerenciamento de API

  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.

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.

Testar a resposta da API

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.

Rastreamento do Inspetor de API

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