Kebijakan BasicAuthentication

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Apa

Memungkinkan Anda menggunakan Autentikasi Dasar ringan untuk keamanan kilometer terakhir. Kebijakan ini mengambil nama pengguna dan sandi, mengenkodenya dalam Base64, dan menulis nilai yang dihasilkan ke variabel. Nilai yang dihasilkan dalam bentuk Basic Base64EncodedString. Biasanya, Anda menulis nilai ini ke header HTTP, seperti header Authorization.

Kebijakan ini juga memungkinkan Anda mendekode kredensial yang disimpan dalam string berenkode Base64 menjadi nama pengguna dan sandi.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Catatan: Kebijakan ini tidak menerapkan Autentikasi Dasar pada permintaan ke proxy API. Sebagai gantinya, Anda menggunakannya untuk mengenkode/mendekode kredensial Base64, biasanya saat terhubung ke server backend atau menggunakan kebijakan panggilan layanan, seperti kebijakan Panggilan Layanan, yang memerlukan Autentikasi Dasar.

Catatan: Video berikut menunjukkan Editor Proxy klasik di UI Apigee. Apigee memperkenalkan versi baru Editor Proxy, yang memiliki desain berbeda dengan versi klasik yang ditampilkan dalam video.

Video: Video ini menunjukkan cara mengenkode nama pengguna dan sandi dengan base64 menggunakan kebijakan Autentikasi Dasar.

Video: Video ini menunjukkan cara mendekode nama pengguna dan sandi berenkode base64 menggunakan kebijakan Autentikasi Dasar.

Sampel

Encoding keluar

<BasicAuthentication name="ApplyBasicAuthHeader">
   <DisplayName>ApplyBasicAuthHeader</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="BasicAuth.credentials.username" />
   <Password ref="BasicAuth.credentials.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
</BasicAuthentication>

Dalam konfigurasi kebijakan contoh di atas, nama pengguna dan sandi yang akan dienkode berasal dari variabel yang ditentukan oleh atribut ref pada elemen <User> dan <Password>. Variabel harus ditetapkan sebelum kebijakan ini dijalankan. Biasanya, variabel diisi dengan nilai yang dibaca dari peta nilai kunci. Lihat Kebijakan operasi Key Value Map.

Konfigurasi ini menghasilkan header HTTP bernama Authorization, seperti yang ditentukan oleh elemen <AssignTo>, yang ditambahkan ke pesan permintaan keluar yang dikirim ke server backend:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Nilai <User> dan <Password> digabungkan dengan titik dua sebelum dienkode dengan Base64.

Pertimbangkan bahwa Anda memiliki peta key/value dengan entri berikut:

{
  "encrypted" : true,
  "entry" : [ {
    "name" : "username",
    "value" : "MyUsername
  }, {
    "name" : "password",
    "value" : "MyPassword
  } ],
  "name" : "BasicAuthCredentials"
}
      

Lampirkan kebijakan KeyValueMapOperations berikut sebelum kebijakan BasicAuthentication agar dapat mengekstrak nilai untuk elemen <User> dan <Password> dari penyimpanan nilai kunci dan mengisinya ke variabel credentials.username dan credentials.password.

<KeyValueMapOperations name="getCredentials" mapIdentifier="BasicAuthCredentials">
  <Scope>apiproxy</Scope>
  <Get assignTo="credentials.username" index='1'>
    <Key>
      <Parameter>username</Parameter>
    </Key>
  </Get>
  <Get assignTo="credentials.password" index='1'>
    <Key>
      <Parameter>password</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
      

Decoding masuk

<BasicAuthentication name="DecodeBaseAuthHeaders">
   <DisplayName>Decode Basic Authentication Header</DisplayName>
   <Operation>Decode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.header.username" />
   <Password ref="request.header.password" />
   <Source>request.header.Authorization</Source>
</BasicAuthentication>

Dalam contoh kebijakan ini, kebijakan mendekode nama pengguna dan sandi dari header HTTP Authorization, seperti yang ditentukan oleh elemen <Source>. String berenkode Base64 harus dalam bentuk Basic Base64EncodedString.

Kebijakan ini menulis nama pengguna yang didekode ke variabel request.header.username dan sandi yang didekode ke variabel request.header.password.

---

Tentang kebijakan Autentikasi Dasar

Kebijakan ini memiliki dua mode operasi:

• Encode: Mengenkode nama pengguna dan sandi yang disimpan dalam variabel Base64
• Decode: Mendekode nama pengguna dan sandi dari string berenkode Base64

Nama pengguna dan sandi biasanya disimpan di penyimpanan nilai kunci, lalu dibaca dari penyimpanan nilai kunci saat runtime. Untuk mengetahui detail tentang penggunaan penyimpanan key/value, lihat kebijakan Operasi Peta Nilai Kunci.

Peringatan: Autentikasi dasar tidak memberikan kerahasiaan. Selalu kirim kredensial melalui koneksi yang mendukung TLS (HTTPS) ke layanan backend Anda.

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut kebijakan BasicAuthentication.

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">
   <DisplayName>Basic Authentication 1</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.queryparam.username" />
   <Password ref="request.queryparam.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
   <Source>request.header.Authorization</Source> 
</BasicAuthentication>

Atribut <BasicAuthentication>

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">

Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:

Atribut	Deskripsi	Default	Kehadiran
name	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.	T/A	Wajib
continueOnError	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini	false	Opsional
enabled	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.	benar	Opsional
async	Atribut ini tidak digunakan lagi.	false	Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Default	T/A Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran	Opsional
Jenis	String

Elemen <Operation>

Menentukan apakah kebijakan mengenkode atau mendekode kredensial Base64.

<Operation>Encode</Operation>

Default:	T/A
Kehadiran:	Wajib
Jenis:	String. Nilai yang valid mencakup: Encode Dekode

Elemen <IgnoreUnresolvedVariables>

Jika disetel ke true, kebijakan tidak akan menampilkan error jika variabel tidak dapat diselesaikan. Jika digunakan dalam konteks kebijakan BasicAuthentication, setelan ini biasanya disetel ke false karena umumnya bermanfaat untuk memunculkan error jika nama pengguna atau sandi tidak dapat ditemukan dalam variabel yang ditentukan.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Default:	true
Kehadiran:	Opsional
Jenis:	Boolean

Elemen <User>

• Untuk encoding, gunakan elemen <User> untuk menentukan variabel yang berisi nama pengguna. Nilai nama pengguna dan sandi digabungkan dengan titik dua sebelum enkode Base64.
• Untuk mendekode, tentukan variabel tempat nama pengguna yang didekode ditulis.

<User ref="request.queryparam.username" /> 

Default:	T/A
Kehadiran:	Wajib
Jenis:	T/A

Atribut

Atribut	Deskripsi	Default	Kehadiran
ref	Variabel yang digunakan kebijakan untuk membaca nama pengguna secara dinamis (encode) atau menulis nama pengguna (decode).	T/A	Wajib

Elemen <Password>

• Untuk encoding, gunakan elemen <Password> untuk menentukan variabel yang berisi sandi.
• Untuk mendekode, tentukan variabel tempat sandi yang didekode ditulis.

<Password ref="request.queryparam.password" />

Default:	T/A
Kehadiran:	Wajib
Jenis:	T/A

Atribut

Atribut	Deskripsi	Default	Kehadiran
ref	Variabel yang digunakan kebijakan untuk membaca sandi secara dinamis (encode) atau menulis sandi (decode).	T/A	Wajib

Elemen <AssignTo>

Menentukan variabel target yang akan ditetapkan dengan nilai yang dienkode atau didekode yang dihasilkan oleh kebijakan ini.

Contoh berikut menunjukkan bahwa kebijakan harus menetapkan header Authorization pesan ke nilai yang dihasilkan:

<AssignTo createNew="false">request.header.Authorization</AssignTo>

Default:	T/A
Kehadiran:	Wajib
Jenis:	String

Atribut

Atribut	Deskripsi	Default	Kehadiran
createNew	Menentukan apakah kebijakan harus mengganti variabel jika variabel sudah ditetapkan. Jika "false", penetapan ke variabel terjadi hanya jika variabel saat ini belum ditetapkan (null). Jika "true", penetapan ke variabel selalu terjadi. Biasanya, Anda menetapkan atribut ini ke "false" (default).	false	Opsional

Elemen <Source>

Untuk mendekode, variabel yang berisi string berenkode Base64, dalam bentuk Basic Base64EncodedString. Misalnya, tentukan request.header.Authorization, yang sesuai dengan header Authorization.

<Source>request.header.Authorization</Source>

Default:	T/A
Kehadiran:	Diperlukan untuk operasi Decode.
Jenis:	T/A

Variabel alur

Variabel alur berikut ditetapkan saat kebijakan gagal:

• BasicAuthentication.{policy_name}.failed (dengan nilai benar)

Catatan: Jika Anda melihat variabel yang disebut BasicAuthentication.{policy_name}.fault.cause dan BasicAuthentication.{policy_name}.fault.name, variabel tersebut saat ini tidak digunakan oleh Apigee.

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
steps.basicauthentication.InvalidBasicAuthenticationSource	500	On a decode when the incoming Base64 encoded string does not contain a valid value or the header is malformed (for example, does not start with Basic).
steps.basicauthentication.UnresolvedVariable	500	The required source variables for the decode or encode are not present. This error can only occur if IgnoreUnresolvedVariables is false.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Occurs when	Fix
UserNameRequired	The <User> element must be present for the named operation.
PasswordRequired	The <Password> element must be present for the named operation.
AssignToRequired	The <AssignTo> element must be present for the named operation.
SourceRequired	The <Source> element must be present for the named operation.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	BasicAuthentication.BA-Authenticate.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

Example fault rule

<FaultRule name="Basic Authentication Faults">
    <Step>
        <Name>AM-UnresolvedVariable</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Step>
        <Name>AM-AuthFailedResponse</Name>
        <Condition>(fault.name = "InvalidBasicAuthenticationSource")</Condition>
    </Step>
    <Condition>(BasicAuthentication.BA-Authentication.failed = true) </Condition>
</FaultRule>

Skema

Contoh: Lihat contoh repositori GitHub kami untuk mengetahui skema terbaru.

Topik terkait

Kebijakan operasi Key Value Map