Come mascherare e nascondere i dati

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Quando esegui il debug delle chiamate alle API in Apigee, a volte i contenuti possono contenere dati sensibili, come carte di credito o informazioni sanitarie che consentono l'identificazione personale (PHI), che devono essere mascherati.

Apigee offre diversi modi per mascherare o nascondere i dati sensibili dalle sessioni di Trace e di debug.

Mascheramento di dati sensibili

Apigee consente di definire configurazioni di maschera per mascherare dati specifici nelle sessioni di traccia e debug. Quando i dati sono mascherati, vengono sostituiti da asterischi nell'output della traccia. Puoi mascherare i dati sensibili e mantenere invariati quelli non sensibili. Ad esempio:

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

La configurazione della maschera è una risorsa singleton che definisci a livello di ambiente. Per impostazione predefinita, non è attivo alcun mascheramento dei dati.

Il mascheramento dei dati si applica solo ai dati acquisiti in una sessione di debug per un proxy API. Il mascheramento dei dati non influisce sui dati che vengono inviati alle destinazioni o alle applicazioni client. Se modifichi la configurazione del mascheramento dei dati, devi avviare una nuova sessione di debug per vedere l'effetto della modifica.

Struttura della configurazione di una maschera

Le configurazioni delle maschere sono file in formato JSON che consentono di identificare dati sensibili nelle seguenti origini:

  • Payload XML: utilizzando XPath, identifichi gli elementi XML da filtrare dai payload dei messaggi di richiesta o risposta.
  • Payload JSON: utilizzando JSONPath, puoi identificare le proprietà JSON da filtrare dai payload dei messaggi di richiesta o risposta.
  • Variabili di flusso: puoi specificare un elenco di variabili da mascherare nell'output di debug. Quando specifichi le variabili di flusso request.content, response.content o message.content, anche il corpo della richiesta/risposta viene mascherato.

Di seguito è riportato un esempio della struttura di base di una configurazione di maschera in formato JSON. Per ulteriori informazioni sui campi di configurazione della maschera mostrati nell'esempio, consulta 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"
  ]
}

Visualizzazione della configurazione della maschera in un ambiente utilizzando l'API

Per visualizzare la configurazione della maschera in un ambiente, invia un comando GET alla risorsa seguente: 

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

Ad esempio:

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

Dove $TOKEN è impostato sul token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

Di seguito è riportato un esempio della risposta: 

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

Aggiornamento della configurazione della maschera in un ambiente mediante l'API

Per aggiornare la risorsa singleton della configurazione della maschera in un ambiente, rilascia un PATCH per la risorsa seguente:

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

Facoltativamente, puoi trasmettere i seguenti parametri di ricerca:

  • Imposta il parametro di query updateMask per specificare una maschera di campo che includa un elenco separato da virgole di nomi completi dei campi nella maschera di debug. Ad esempio: "requestJSONPaths"
  • Imposta il parametro di query replaceRepeatedFields per specificare se sostituire i valori esistenti nella maschera di debug quando esegui un aggiornamento. Per impostazione predefinita, i valori vengono aggiunti (false)

Ad esempio: 

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"
     ]
   }'

Dove $TOKEN è impostato sul token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

Mascheramento del file XML con ambito dello spazio dei nomi

Se vuoi mascherare i dati XML e questi dati utilizzano spazi dei nomi XML, la configurazione della maschera deve fare riferimento a questi spazi dei nomi con l'elemento namespaces. Questo vale se il payload XML utilizza uno spazio dei nomi predefinito o un prefisso dello spazio dei nomi.

Ad esempio, supponiamo di voler mascherare il nome del dipendente nel payload della richiesta e che l'XML non utilizzi spazi dei nomi XML:

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

Pertanto, la configurazione di debugmask non richiede l'elemento namespaces:

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

Se il payload XML utilizza spazi dei nomi con prefissi:

<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>

Quindi la configurazione della maschera dovrebbe contenere l'elemento namespaces. Puoi scegliere qualsiasi prefisso dello spazio dei nomi valido nella configurazione della maschera di debug. Il prefisso dello spazio dei nomi nella configurazione della maschera di debug potrebbe essere lo stesso del prefisso dello spazio dei nomi utilizzato nel file XML, ma non è obbligatorio.

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

Se il payload XML utilizza uno spazio dei nomi senza prefisso, ovvero lo spazio dei nomi predefinito:

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

A questo punto, la configurazione della maschera di debug deve comunque definire un prefisso nell'elemento namespaces corrispondente a quello spazio dei nomi predefinito. Puoi utilizzare qualsiasi prefisso univoco che preferisci.

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

Altre note di configurazione

  • Con gli elementi di configurazione *XPaths e *JSONPaths, puoi mascherare i dati visualizzati nei messaggi request, response o fault. Tuttavia, l'intero contenuto del messaggio può essere acquisito anche dalle sessioni di debug. Puoi anche configurare request.content o response.content nella sezione variables per impedire la visualizzazione dei dati sensibili.

  • Se utilizzi le norme relative ai callout di servizio per effettuare una richiesta, le informazioni contenute nella richiesta e nella risposta per tale callout non verranno mascherate utilizzando gli elementi di configurazione come requestXPaths o responseJSONPaths. Se vuoi mascherare questi dati, devi specificare un nome di variabile per i messaggi di richiesta e risposta nel criterio ServiceCallout e poi specificare queste variabili nella sezione variables della debugmask. Ad esempio, se il criterio Callout di servizio utilizza:

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

    Devi quindi includere rbacRequest.content nell'elemento variables per la configurazione della maschera di debug.

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

Nascondere i dati sensibili

Oltre al mascheramento, puoi impedire la visualizzazione dei dati sensibili anche nello strumento Trace e nelle sessioni di debug scegliendo un nome che inizi con private. per le variabili personalizzate.

Ad esempio, se utilizzi il criterio relativo alle operazioni sulle mappe chiave-valore per recuperare un valore da una mappa chiave-valore, puoi scegliere il nome della variabile come segue per assicurarti che il valore non venga visualizzato nelle sessioni di Trace o di debug:

<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>

Le variabili senza il prefisso private. vengono visualizzate in testo in chiaro nelle sessioni di Trace e di debug anche se i dati provengono da un datastore criptato, ad esempio una mappa chiave-valore. Per mascherare questi valori, utilizza il mascheramento.