Como mascarar e ocultar dados

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Ao depurar chamadas de APIs na Apigee, o conteúdo às vezes pode conter dados confidenciais, como cartões de crédito ou informações de saúde pessoais (PHI, na sigla em inglês) que precisam ser mascarados.

A Apigee fornece maneiras diferentes de mascarar ou ocultar dados confidenciais do Trace e de sessões de depuração.

Como mascarar dados confidenciais

A Apigee permite definir configurações de máscara para mascarar dados específicos nas sessões de rastreamento e depuração. Quando os dados são mascarados, eles são substituídos por asteriscos na saída de trace. É possível mascarar dados sensíveis e manter os não confidenciais inalterados. Por exemplo:

<ServiceRequest>
  <request-id>B540A938-F551</request-id>
  <customer-name>**********</customer-name>
</ServiceRequest>

A configuração da máscara é um recurso singleton que você define no nível do ambiente. Por padrão, nenhuma máscara de dados está em vigor.

O mascaramento de dados se aplica apenas aos dados capturados em uma sessão de depuração para um proxy de API. O mascaramento de dados não afeta os dados enviados aos destinos ou aplicativos clientes. Se você mudar a configuração de mascaramento de dados, será preciso iniciar uma nova sessão de depuração para conferir o efeito da mudança.

Estrutura de uma configuração de máscara

As configurações de máscara são arquivos com formatação JSON que permitem identificar dados confidenciais nas seguintes fontes:

  • Payloads XML: usando o XPath, é possível identificar elementos XML que serão filtrados dos payloads das mensagens de solicitação ou resposta.
  • Payloads JSON: usando o JSONPath, é possível identificar propriedades JSON a serem filtradas dos payloads das mensagens de solicitação ou resposta.
  • Variáveis de fluxo: é possível especificar uma lista de variáveis que precisam ser mascarados na saída de depuração. Quando você especifica as variáveis de fluxo request.content, response.content ou message.content, o corpo da solicitação/resposta também é mascarado.

Veja a seguir um exemplo da estrutura básica de uma configuração de máscara no formato JSON. Para saber mais sobre os campos de configuração de máscara mostrados no exemplo, consulte DebugMask. 

{
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "faultXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "requestJSONPaths": [
    "$.store.book[*].author"
  ],
  "responseJSONPaths": [
    "$.store.book[*].author"
  ],
  "faultJSONPaths": [
    "$.store.book[*].author"
  ],
  "variables": [
    "request.header.user-name",
    "request.formparam.password",
    "myCustomVariable"
  ]
}

Como visualizar a configuração da máscara em um ambiente usando a API

Para visualizar a configuração de máscara em um ambiente, emita um GET para o seguinte recurso: 

/organizations/{org}/environments/{env}/debugmask

Por exemplo:

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/debugmask" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Veja a seguir um exemplo de resposta:

{
  "name": "organizations/myorg/environments/test/debugmask"
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ]
}

Como atualizar a configuração da máscara em um ambiente usando a API

Para atualizar o recurso singleton da configuração de máscara em um ambiente, emita um PATCH para o seguinte recurso:

/organizations/{org}/environments/{env}/debugmask

Opcionalmente, é possível passar os seguintes parâmetros de consulta:

  • Defina o parâmetro de consulta updateMask para especificar uma máscara de campo que inclua uma lista separada por vírgulas de nomes de campos totalmente qualificados na máscara de depuração. Por exemplo: "requestJSONPaths"
  • Defina o parâmetro de consulta replaceRepeatedFields para especificar se os valores atuais serão substituídos na máscara de depuração durante uma atualização. Por padrão, os valores são anexados (false)

Por exemplo:

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/debugmask" \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d \
  '{
     "namespaces": {
       "ns1": "http://example.com"
     },
     "requestXPaths": [
       "/ns1:employee/ns1:name"
     ]
   }'

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Como mascarar XML com escopo de namespace

Se você quiser mascarar dados XML e esses dados usarem namespaces XML, a configuração da máscara precisará referenciar esses namespaces com o elemento namespaces. Isso ocorre independentemente de o payload do XML usar um namespace padrão ou um prefixo de namespace.

Por exemplo, suponha que você queira mascarar o nome do funcionário no payload da solicitação e o XML não use namespaces XML:

<employee>
  <name>Shanmu Tharman</name>
  <age>50</age>
</employee>

Portanto, a configuração da máscara de depuração não exige o elemento namespaces:

{
  "requestXPaths": [
    "/employee/name"
  ]
}

Se o payload do XML usar namespaces com prefixos:

<cym:employee xmlns:cym="http://cymbalgroup.com" xmlns:id="http://cymbalgroup.com/identity">
  <id:name>Shanmu Tharman</id:name>
  <id:age>50</id:age>
</cym:employee>

A configuração da máscara precisa conter o elemento namespaces: Você pode escolher qualquer prefixo de namespace válido na configuração de debugmask. O prefixo de namespace na configuração de debugmask pode ser igual ao usado no XML, mas isso não é obrigatório.

{
  "namespaces": {
    "cym": "http://cymbalgroup.com",
    "idns": "http://cymbalgroup.com/identity"
  },
  "requestXPaths": [
    "/cym:employee/idns:name"
  ]
}

Se o payload do XML usar um namespace sem prefixo, ou seja, o namespace padrão:

<employee xmlns="http://cymbalgroup.com" xmlns:id="http://cymbalgroup.com/identity">
  <id:name>Shanmu Tharman</id:name>
  <id:age>50</id:age>
</employee>

A configuração de debugmask ainda precisa definir um prefixo no elemento namespaces correspondente a esse namespace padrão. Você pode usar qualquer prefixo exclusivo que quiser.

{
  "namespaces": {
    "p1": "http://cymbalgroup.com",
    "id": "http://cymbalgroup.com/identity"
  },
  "requestXPaths": [
    "/p1:employee/id:name"
  ]
}

Outras observações de configuração

  • Com os elementos de configuração *XPaths e *JSONPaths, é possível mascarar dados que aparecem nas mensagens request, response ou fault. No entanto, o conteúdo completo da mensagem também pode ser capturado por sessões de depuração. Também é possível configurar request.content ou response.content na seção variables para evitar que dados confidenciais sejam exibidos.

  • Se você usar a política ServiceCallout para fazer uma solicitação, as informações na solicitação e na resposta para essa chamada não serão mascaradas usando os elementos de configuração como requestXPaths ou responseJSONPaths. Se você quiser mascarar esses dados, especifique um nome de variável para as mensagens de solicitação e resposta na política ServiceCallout e, em seguida, especifique essas variáveis na seção variables da debugmask. Por exemplo, se a política ServiceCallout usar:

    <ServiceCallout name='SC-1'>
  <Request variable='rbacRequest'>
    <Set>
      <Payload contentType='application/json'>{ ... }</Payload>
       ...

    Inclua rbacRequest.content no elemento variables para a configuração da máscara de depuração.

    {
  ...
  "variables": [
    "request.content",
    "response.content",
    "rbacRequest.content"
  ]
}

Como ocultar dados confidenciais

Além do mascaramento, é possível impedir que dados confidenciais apareçam na ferramenta Trace e em sessões de depuração. Para isso, escolha um nome que comece com private. para as variáveis personalizadas.

Por exemplo, ao usar a Política de operações do mapa de chaves-valor Para recuperar um valor de um mapa de chave-valor, escolha o nome da variável da seguinte maneira para garantir que o valor não apareça nas sessões de rastreamento ou de depuração:

<KeyValueMapOperations name='KVM-Get-1'>
    <Scope>environment</Scope>
    <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
    <MapName>settings</MapName>
    <Get assignTo='private.privatekey'>
      <Key>
        <Parameter>rsa_private_key</Parameter>
      </Key>
    </Get>
  </KeyValueMapOperations>

As variáveis sem o prefixo private. são exibidas em texto não criptografado nas sessões de rastreamento e depuração, mesmo que os dados sejam originados de um repositório de dados criptografado, como um mapa de chave-valor. Use o mascaramento se quiser mascarar esses valores.