WWW-Authenticate

Penggunaan

Ketika klien meminta sumber daya terlindungi tanpa kredensial yang valid, server merespons dengan kode status 401 dan menyertakan header WWW-Authenticate. Header ini membawa satu atau beberapa tantangan autentikasi, masing-masing menetapkan sebuah skema beserta parameter apa pun yang dibutuhkan klien untuk menyusun kredensial yang valid.

Setelah menerima tantangan tersebut, klien mengirim ulang permintaan dengan header Authorization yang berisi kredensial yang diformat sesuai skema yang dipilih. Server memvalidasi kredensial dan mengembalikan sumber daya yang diminta jika berhasil.

Beberapa tantangan dalam satu response memungkinkan server menawarkan beberapa skema sekaligus. Klien memilih skema terkuat yang didukung kedua pihak. Tantangan muncul pada baris header terpisah atau dalam satu baris yang dipisahkan koma.

Header setara untuk autentikasi di tingkat proxy adalah Proxy-Authenticate, yang memicu response 407 alih-alih 401.

scheme

scheme mengidentifikasi metode autentikasi. Skema yang terdaftar dikelola oleh IANA. Skema yang paling umum dalam praktik dijelaskan di bawah ini.

Basic mengirimkan pasangan username:password yang dienkode Base64. Skema ini menerima parameter realm dan parameter charset opsional (biasanya UTF-8).

Bearer melakukan autentikasi dengan access token yang bersifat opak, paling umum diterbitkan melalui alur OAuth. Skema ini mendukung parameter realm, scope, dan error. Parameter scope mencantumkan izin yang harus dibawa token tersebut. Parameter error menyampaikan alasan kegagalan spesifik seperti invalid_token atau insufficient_scope.

Digest menyempurnakan Basic dengan melakukan hashing terhadap kredensial menggunakan nonce yang disediakan server, sehingga kata sandi tidak berjalan dalam bentuk teks biasa. Parameter yang wajib mencakup realm, nonce, dan qop (quality of protection). Parameter opsional mencakup algorithm, opaque, dan stale.

Negotiate memulai autentikasi berbasis SPNEGO, biasanya didukung Kerberos atau NTLM di lingkungan enterprise. Skema ini membawa token SPNEGO berenkode Base64 ketika negosiasi sedang berlangsung.

realm

Parameter realm adalah string opsional yang mendefinisikan ruang perlindungan. Nilainya membantu pengguna mengenali kredensial mana yang dibutuhkan. Server yang melindungi beberapa area berbeda memberikan nilai realm yang berbeda untuk masing-masing area.

token68

Sintaks token68 adalah penyandian kredensial alternatif yang diizinkan oleh kerangka autentikasi HTTP. Nilainya menggunakan himpunan karakter terbatas (alfanumerik, -, ., _, ~, +, /) dengan padding = di bagian akhir yang bersifat opsional.

Contoh

Server yang melindungi sebuah sumber daya dengan autentikasi Basic mengembalikan tantangan yang menyertakan nama realm yang ditampilkan kepada pengguna.

WWW-Authenticate: Basic realm="Staging Environment"

Tantangan token Bearer menyampaikan scope yang dibutuhkan dan menandakan token yang kedaluwarsa melalui parameter error.

WWW-Authenticate: Bearer realm="api.example.re", scope="read write", error="invalid_token"

Tantangan Digest menyertakan nonce yang dihasilkan server dan pengaturan quality of protection.

WWW-Authenticate: Digest realm="admin@example.re", nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v", qop="auth", algorithm=SHA-256

Server yang menawarkan beberapa skema mencantumkan semuanya agar klien dapat memilih opsi terkuat.

WWW-Authenticate: Negotiate
WWW-Authenticate: Bearer realm="api.example.re"
WWW-Authenticate: Basic realm="api.example.re"

Satu handshake autentikasi Basic yang lengkap. Klien mula-mula meminta sumber daya terlindungi tanpa kredensial:

GET /admin HTTP/1.1
Host: example.re

Server merespons dengan 401 dan sebuah tantangan Basic:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="API"

Klien mencoba lagi dengan header Authorization yang berisi pasangan username:password berenkode Base64:

GET /admin HTTP/1.1
Host: example.re
Authorization: Basic dXNlcjpwYXNz

Server memvalidasi kredensial dan mengembalikan sumber daya tersebut:

HTTP/1.1 200 OK
Content-Type: text/html