Kebijakan BasicAuthentication

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X.
info

Apa

Memungkinkan Anda menggunakan Autentikasi Dasar ringan untuk keamanan kilometer terakhir. Kebijakan ini menggunakan nama pengguna dan sandi, Base64 mengenkodenya, dan menulis nilai yang dihasilkan ke suatu variabel. Nilai yang dihasilkan akan memiliki format Basic Base64EncodedString. Anda biasanya 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.

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

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

Contoh

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 contoh konfigurasi kebijakan 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 oleh nilai yang dibaca dari peta kunci/nilai. Lihat kebijakan Key Value Map Operations.

Konfigurasi ini menghasilkan header HTTP yang 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> disambungkan dengan titik dua sebelum encoding Base64.

Pertimbangkan bahwa Anda memiliki peta kunci/nilai dengan entri berikut:

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

Tambahkan kebijakan KeyValueMapOperations berikut sebelum kebijakan BasicAuthentication agar dapat mengekstrak nilai untuk elemen <User> dan <Password> dari penyimpanan kunci/nilai lalu isi 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>
      

Dekode 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 yang dienkode Base64 harus dalam format Basic Base64EncodedString.

Kebijakan ini akan menuliskan 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: Base64 mengenkode nama pengguna dan sandi yang disimpan dalam variabel
  • Decode: Mendekode nama pengguna dan sandi dari string berenkode Base64

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

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 sama untuk semua elemen induk kebijakan:

Atribut Deskripsi Default Ketersediaan
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.

Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

T/A Wajib
continueOnError

Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal.

false Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.

true Opsional
async

Atribut ini sudah tidak digunakan lagi.

false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.

Ketersediaan Opsional
Jenis String

Elemen <Operation>

Menentukan apakah kebijakan Base64 mengenkode atau mendekode kredensial.

<Operation>Encode</Operation>
Default: T/A
Kehadiran: Wajib
Jenis:

String.

Nilai yang valid meliputi:

  • Encoding
  • Decode

Elemen <IgnoreUnresolvedVariables>

Jika ditetapkan ke true, kebijakan tidak akan menampilkan error jika variabel tidak dapat diselesaikan. Saat digunakan dalam konteks kebijakan BasicAuthentication, setelan ini biasanya ditetapkan ke false karena umumnya ada baiknya untuk menampilkan 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 encoding Base64.
  • Untuk decoding, 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 Ketersediaan
referensi

Variabel tempat kebijakan membaca nama pengguna (mengenkode) atau menulis nama pengguna (dekode) secara dinamis.

T/A Wajib

Elemen <Password>

  • Untuk encoding, gunakan elemen <Password> untuk menentukan variabel yang berisi sandi.
  • Untuk decoding, tentukan variabel tempat sandi yang didekode ditulis.
<Password ref="request.queryparam.password" />
Default: T/A
Kehadiran: Wajib
Jenis:

T/A

Atribut

Atribut Deskripsi Default Ketersediaan
referensi

Variabel tempat kebijakan membaca sandi (mengenkode) atau menulis sandi (dekode) secara dinamis.

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 Ketersediaan
createNew Menentukan apakah kebijakan harus menimpa variabel jika variabel sudah ditetapkan.

Jika "false", penetapan ke variabel hanya terjadi jika variabel tersebut saat ini belum ditetapkan (null).

Jika "true", penetapan ke variabel selalu terjadi.

Anda biasanya menetapkan atribut ini ke "false" (default).

false Opsional

Elemen <Source>

Untuk decoding, 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 Dekode.
Jenis:

T/A

Variabel alur

Variabel alur berikut ditetapkan saat kebijakan gagal:

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

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda sedang mengembangkan aturan fault untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab Perbaiki
steps.basicauthentication.InvalidBasicAuthenticationSource 500 Pada dekode saat string berenkode Base64 yang masuk tidak berisi nilai yang valid atau format header salah (misalnya, tidak dimulai dengan "Basic").
steps.basicauthentication.UnresolvedVariable 500 Variabel sumber yang diperlukan untuk dekode atau enkode tidak ada. Error ini hanya dapat terjadi jika IgnoreUnresolvedVariables bernilai salah (false).

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error Terjadi saat Perbaiki
UserNameRequired Elemen <User> harus ada untuk operasi yang diberi nama.
PasswordRequired Elemen <Password> harus ada untuk operasi yang diberi nama.
AssignToRequired Elemen <AssignTo> harus ada untuk operasi yang diberi nama.
SourceRequired Elemen <Source> harus ada untuk operasi yang diberi nama.

Variabel kesalahan

Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Dari mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. BasicAuthentication.BA-Authenticate.failed = true

Contoh respons error

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

Contoh aturan kesalahan

<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

Topik terkait

Kebijakan Key Value Map Operations