Menyamarkan dan menyembunyikan data

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Saat Anda men-debug panggilan API di Apigee, konten terkadang dapat berisi data sensitif, seperti kartu kredit atau informasi kesehatan identitas pribadi (PHI) yang harus disamarkan.

Apigee menyediakan berbagai cara untuk menyamarkan atau menyembunyikan data sensitif dari sesi Trace dan debug.

Menyamarkan data sensitif

Apigee memungkinkan Anda menentukan konfigurasi mask untuk menyamarkan data tertentu dalam sesi trace dan debug. Jika disamarkan, data akan diganti dengan tanda bintang di output rekaman aktivitas. Anda dapat menyamarkan data sensitif dan mempertahankan data non-sensitif agar tidak berubah. Contoh:

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

Konfigurasi mask adalah resource singleton yang Anda tentukan di tingkat lingkungan. Secara default, tidak ada penyamaran data yang diterapkan.

Penyamaran data hanya berlaku untuk data yang diambil dalam sesi debug untuk proxy API. Penyamaran data tidak memengaruhi data yang dikirim ke target atau aplikasi klien. Jika mengubah konfigurasi masking data, Anda harus memulai sesi debug baru untuk melihat efek perubahan.

Struktur konfigurasi mask

Konfigurasi mask adalah file berformat JSON yang memungkinkan Anda mengidentifikasi data sensitif di sumber berikut:

  • Payload XML: Dengan XPath, Anda mengidentifikasi elemen XML yang akan difilter dari payload pesan permintaan atau respons.
  • Payload JSON: Dengan JSONPath, Anda mengidentifikasi properti JSON yang akan difilter dari payload pesan permintaan atau respons.
  • Variabel alur: Anda dapat menentukan daftar variabel yang harus disamarkan dalam output debug. Saat Anda menentukan variabel alur request.content, response.content, atau message.content, isi permintaan/respons juga disamarkan.

Berikut adalah contoh struktur dasar konfigurasi mask dalam format JSON. Untuk mengetahui informasi selengkapnya tentang kolom konfigurasi mask yang ditampilkan dalam contoh, lihat 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"
  ]
}

Melihat konfigurasi mask di lingkungan menggunakan API

Untuk melihat konfigurasi mask di lingkungan, berikan GET ke resource berikut: 

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

Contoh:

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

Dengan $TOKEN ditetapkan ke token akses OAuth 2.0 Anda, seperti yang dijelaskan dalam Mendapatkan token akses OAuth 2.0. Untuk mengetahui informasi tentang opsi curl yang digunakan dalam contoh ini, lihat Menggunakan curl. Untuk deskripsi variabel lingkungan yang digunakan, lihat Menetapkan variabel lingkungan untuk permintaan Apigee API.

Berikut adalah contoh responsnya: 

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

Memperbarui konfigurasi mask di lingkungan menggunakan API

Untuk memperbarui resource singleton konfigurasi mask di lingkungan, berikan PATCH ke resource berikut:

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

Secara opsional, Anda dapat meneruskan parameter kueri berikut:

  • Tetapkan parameter kueri updateMask untuk menentukan mask kolom yang menyertakan daftar yang dipisahkan koma berisi nama kolom yang sepenuhnya memenuhi syarat dalam mask debug. Contoh: "requestJSONPaths"
  • Tetapkan parameter kueri replaceRepeatedFields untuk menentukan apakah akan mengganti nilai yang ada di mask debug saat melakukan update. Secara default, nilai ditambahkan (false)

Contoh: 

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

Dengan $TOKEN ditetapkan ke token akses OAuth 2.0 Anda, seperti yang dijelaskan dalam Mendapatkan token akses OAuth 2.0. Untuk mengetahui informasi tentang opsi curl yang digunakan dalam contoh ini, lihat Menggunakan curl. Untuk deskripsi variabel lingkungan yang digunakan, lihat Menetapkan variabel lingkungan untuk permintaan Apigee API.

Menyamarkan XML cakupan namespace

Jika Anda ingin menyamarkan data XML dan data tersebut menggunakan namespace XML, konfigurasi mask harus mereferensikan namespace tersebut dengan elemen namespaces. Hal ini berlaku baik jika payload XML menggunakan namespace default, atau awalan namespace.

Misalnya, Anda ingin menyamarkan nama karyawan dalam payload permintaan, dan XML tidak menggunakan namespace XML:

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

Oleh karena itu, konfigurasi debugmask tidak memerlukan elemen namespaces:

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

Jika payload XML menggunakan namespace dengan awalan:

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

Kemudian, konfigurasi mask harus berisi elemen namespaces. Anda dapat memilih awalan namespace yang valid dalam konfigurasi debugmask; awalan namespace dalam konfigurasi debugmask mungkin sama dengan awalan namespace yang digunakan dalam XML, tetapi hal itu tidak diperlukan.

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

Jika Payload XML menggunakan namespace tanpa awalan, yang berarti namespace default:

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

Kemudian, konfigurasi debugmask masih harus menentukan awalan dalam elemen namespaces yang sesuai dengan namespace default tersebut. Anda dapat menggunakan awalan unik apa pun yang Anda suka.

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

Catatan Konfigurasi Lainnya

  • Dengan elemen konfigurasi *XPaths dan *JSONPaths, Anda dapat menyamarkan data yang muncul dalam pesan request, response, atau fault. Namun, konten pesan lengkap juga dapat direkam oleh sesi debug. Anda juga dapat mengonfigurasi request.content atau response.content di bagian variables untuk mencegah data sensitif ditampilkan.

  • Jika Anda menggunakan kebijakan ServiceCallout untuk membuat permintaan, informasi dalam permintaan dan respons untuk info tersebut tidak akan disamarkan menggunakan elemen konfigurasi seperti requestXPaths atau responseJSONPaths. Jika ingin menyamarkan data tersebut, Anda harus menentukan nama variabel untuk pesan permintaan dan respons dalam kebijakan ServiceCallout, lalu menentukan variabel tersebut di bagian variables dari debugmask. Misalnya, jika kebijakan ServiceCallout Anda menggunakan:

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

    Kemudian, Anda harus menyertakan rbacRequest.content dalam elemen variables untuk konfigurasi debugmask.

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

Menyembunyikan data sensitif

Selain menyamarkan, Anda dapat mencegah data sensitif muncul di alat Trace dan sesi debug dengan memilih nama yang diawali dengan private. untuk variabel kustom Anda.

Misalnya, saat menggunakan kebijakan Operasi Peta Nilai Kunci untuk mengambil nilai dari peta nilai kunci, Anda dapat memilih nama variabel sebagai berikut untuk memastikan nilai tidak muncul dalam sesi Pelacakan atau 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>

Variabel tanpa awalan private. ditampilkan dalam teks biasa di sesi Trace dan debug meskipun data berasal dari penyimpanan data terenkripsi seperti peta nilai kunci. Gunakan masking jika Anda ingin menyamarkan nilai ini.