Halaman ini diterjemahkan oleh Cloud Translation API.

Kebijakan BasicAuthentication

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Apa

Memungkinkan Anda menggunakan Autentikasi Dasar ringan untuk keamanan tahap akhir. Kebijakan ini mengambil nama pengguna dan sandi, mengenkodenya dalam Base64, dan menulis nilai yang dihasilkan ke variabel. Nilai yang dihasilkan berupa 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.

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

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

Video: Video ini menunjukkan cara mendekode nama pengguna dan sandi yang dienkode 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 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 Operasi Peta Nilai Kunci.

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 encoding Base64.

Misalkan Anda memiliki peta kunci/nilai 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 kunci/nilai 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: Base64 mengenkode nama pengguna dan sandi yang disimpan dalam variabel
Decode: Mendekode nama pengguna dan sandi dari string yang dienkode 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 kunci/nilai, 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 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

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

T/A

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

Kehadiran Opsional

Jenis String

Elemen <Operation>

Menentukan apakah Base64 kebijakan mengenkode atau mendekode kredensial.

<Operation>Encode</Operation>

Default:

T/A

Kehadiran:

Wajib

Jenis:

String.

Nilai yang valid mencakup:

Encode
Dekode

Elemen <IgnoreUnresolvedVariables>

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Default:	benar
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 dekode, 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 tempat kebijakan 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 dekode, 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 tempat kebijakan 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 menimpa variabel jika variabel sudah ditetapkan. Jika "false", penetapan ke variabel hanya terjadi jika variabel saat ini tidak ditetapkan (null). Jika "true", penetapan ke variabel akan selalu terjadi. Anda biasanya menetapkan atribut ini ke "false" (default).	false	Opsional

Deskripsi

Default

Kehadiran

createNew

Menentukan apakah kebijakan harus menimpa variabel jika variabel sudah ditetapkan.

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

Jika "true", penetapan ke variabel akan selalu terjadi.

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

false

Opsional

Elemen <Source>

Untuk dekode, variabel yang berisi string yang dienkode 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 benar)

Referensi error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

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

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 dinamai.
`PasswordRequired`	Elemen `<Password>` harus ada untuk operasi yang dinamai.
`AssignToRequired`	Elemen `<AssignTo>` harus ada untuk operasi yang dinamai.
`SourceRequired`	Elemen `<Source>` harus ada untuk operasi yang dinamai.

Variabel error

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

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

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menangkap bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena teks tersebut dapat berubah.

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

Contoh aturan error

<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 Operasi Peta Nilai Kunci