Share via

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

  • Artigo

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.

Valores nomeados no portal do Azure

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.

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

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:

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 valor secreto do cofre da chave

Adicionar um valor simples ou secreto ao Gerenciamento de API

  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.

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.

Resposta da API de teste

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.

Rastreamento do Inspetor de API

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