Bagikan melalui

Mengelola token OAuth di Azure App Service

Artikel ini memperlihatkan kepada Anda cara mengelola token OAuth untuk autentikasi dan otorisasi bawaan di Azure App Service.

Mengambil token dalam kode aplikasi

Azure App Service menyuntikkan token khusus penyedia Anda ke header permintaan sehingga Anda dapat dengan mudah mengaksesnya. Untuk mendapatkan token khusus penyedia, penyimpanan token harus diaktifkan untuk aplikasi.

Kirim permintaan HTTP GET ke /.auth/me dari kode klien Anda, seperti aplikasi seluler atau JavaScript di browser. JSON yang dikembalikan berisi token khusus penyedia.

Catatan

Token akses adalah untuk mengakses sumber daya penyedia, jadi hanya ada jika Anda mengonfigurasi penyedia Anda dengan rahasia klien.

Tabel berikut mencantumkan nama header token OAuth untuk beberapa penyedia bawaan App Service:

Penyedia Nama header
Microsoft Entra X-MS-TOKEN-AAD-ID-TOKEN
X-MS-TOKEN-AAD-ACCESS-TOKEN
X-MS-TOKEN-AAD-EXPIRES-ON
X-MS-TOKEN-AAD-REFRESH-TOKEN
Facebook X-MS-TOKEN-FACEBOOK-ACCESS-TOKEN
X-MS-TOKEN-FACEBOOK-EXPIRES-ON
Google X-MS-TOKEN-GOOGLE-ID-TOKEN
X-MS-TOKEN-GOOGLE-ACCESS-TOKEN
X-MS-TOKEN-GOOGLE-EXPIRES-ON
X-MS-TOKEN-GOOGLE-REFRESH-TOKEN
X X-MS-TOKEN-TWITTER-ACCESS-TOKEN
X-MS-TOKEN-TWITTER-ACCESS-TOKEN-SECRET

Catatan

Kerangka kerja bahasa yang berbeda mungkin menyajikan header ini ke kode aplikasi dalam format yang berbeda, seperti huruf kecil atau huruf besar/kecil.

Perbarui token otentikasi

Informasi berikut mengacu pada token penyedia. Untuk token sesi, lihat Memperpanjang masa tenggang kedaluwarsa token sesi.

Jika token akses penyedia Anda kedaluwarsa, Anda harus mengautentikasi ulang pengguna sebelum Anda dapat menggunakan token tersebut lagi. Anda dapat menghindari kedaluwarsa token dengan melakukan panggilan GET ke titik akhir /.auth/refresh aplikasi Anda.

Untuk memperbarui token akses Anda kapan saja, panggil /.auth/refresh dalam bahasa apapun. Cuplikan berikut menggunakan jQuery untuk menyegarkan token akses Anda dari klien JavaScript.

function refreshTokens() {
  let refreshUrl = "/.auth/refresh";
  $.ajax(refreshUrl) .done(function() {
    console.log("Token refresh completed successfully.");
  }) .fail(function() {
    console.log("Token refresh failed. See application logs for details.");
  });
}

Saat dipanggil, App Service secara otomatis menyegarkan token akses di penyimpanan token untuk pengguna yang diautentikasi. Permintaan berikutnya untuk token mendapatkan token yang telah diperbarui. Anda dapat melihat token refresh dan waktu kedaluwarsa untuk token dengan menggunakan header yang tercantum dalam Mengambil token dalam kode aplikasi.

Catatan

Jika pengguna mencabut hak akses yang mereka berikan kepada aplikasi milik Anda, panggilan Anda ke /.auth/me mungkin gagal dengan tanggapan 403 Forbidden. Untuk mendiagnosis kesalahan, periksa detail log aplikasi Anda.

Mengonfigurasi penyedia untuk menyediakan token refresh

Agar refresh token berfungsi, penyimpanan token harus berisi token refresh dari penyedia Anda. Setiap penyedia mendokuensikan cara mendapatkan token refresh mereka. Tabel berikut ini menyediakan ringkasan singkat:

Penyedia Token penyegaran
Microsoft Ikuti prosedur di Mengonfigurasi penyedia Microsoft Entra untuk menyediakan token refresh.
Facebook Tidak menyediakan token refresh. Token berumur panjang kedaluwarsa dalam 60 hari. Untuk informasi selengkapnya, lihat Long-Lived Token Akses.
Google Tambahkan parameter string kueri access_type=offline ke panggilan API /.auth/login/google Anda. Untuk informasi selengkapnya, lihat Token Google Refresh.
X Token akses tidak kedaluwarsa. Untuk informasi selengkapnya, lihat FAQ OAuth.

Mengonfigurasi penyedia Microsoft Entra untuk menyediakan token refresh

  1. Di portal Microsoft Azure, buka API Playground (pratinjau), dan pilih Permintaan baru jika perlu.
  2. Di bidang Masukkan jalur relatif ARM di sini termasuk versi API , masukkan string berikut, ganti tempat penampung dengan ID langganan, nama grup sumber daya, dan nama aplikasi Anda:
    subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>/config/authsettingsV2?api-version=2024-11-01
  3. Pilih Jalankan.
  4. Pilih PUT di kiri atas, dan pilih tab Isi permintaan .
  5. GET Salin konten respons dari bidang Isi respons dan tempelkan ke tab Isi permintaan.
  6. Dalam kode, temukan bagian "identityProviders":>>"azureActiveDirectory":"login": , dan tambahkan baris berikut:
    "loginParameters": ["scope=openid profile email offline_access"]
  7. Pilih Jalankan. Bidang Isi respons memperlihatkan perubahan Anda.

Offline_access adalah cakupan yang menyediakan token refresh. App Service sudah meminta cakupan lain secara default. Untuk informasi selengkapnya, lihat Cakupan OpenID Connect dan Web Apps - Perbarui Pengaturan Autentikasi V2.

Memperpanjang masa tenggang kedaluwarsa token sesi

Sesi yang diautentikasi kedaluwarsa setelah 8 jam, dan masa tenggang default 72 jam mengikutinya. Dalam masa tenggang ini, Anda dapat me-refresh token sesi dengan App Service tanpa mengautentikasi ulang pengguna. Anda cukup memanggil /.auth/refresh ketika token sesi Anda menjadi tidak valid, dan Anda tidak perlu melacak kedaluwarsa token sendiri.

Ketika masa tenggang 72 jam berakhir, pengguna harus masuk lagi untuk mendapatkan token sesi yang valid. Jika Anda memerlukan jendela kedaluwarsa yang lebih lama dari 72 jam, Anda dapat memperpanjangnya, tetapi memperpanjang kedaluwarsa untuk jangka waktu yang lama dapat memiliki implikasi keamanan yang signifikan jika token autentikasi bocor atau dicuri. Sebaiknya biarkan pengaturan pada 72 jam default atau atur periode ekstensi ke nilai sekecil mungkin.

Untuk memperluas jendela kedaluwarsa default, jalankan perintah Azure CLI berikut ini di Azure Cloud Shell:

az webapp auth update --resource-group <group_name> --name <app_name> --token-refresh-extension-hours <hours>

Catatan

Masa tenggang hanya berlaku untuk sesi terautentikasi App Service, bukan ke token akses dari penyedia identitas. Tidak ada masa tenggang untuk token penyedia yang kedaluwarsa.

Konten terkait