Bagikan melalui

Platform identitas Microsoft dan alur kredensial klien OAuth 2.0

Alur pemberian kredensial klien OAuth 2.0 mengizinkan layanan web (klien rahasia) untuk menggunakan kredensialnya sendiri, alih-alih meniru pengguna, untuk mengautentikasi saat memanggil layanan web lain. Pemberian yang disebutkan dalam RFC 6749, terkadang disebut OAuth dua kaki , dapat digunakan untuk mengakses sumber daya yang dihosting di web dengan menggunakan identitas aplikasi. Jenis ini biasanya digunakan untuk interaksi server-ke-server yang harus berjalan di latar belakang, tanpa interaksi langsung dengan pengguna, dan sering disebut sebagai daemon atau akun layanan .

Dalam alur kredensial klien, izin diberikan langsung ke aplikasi itu sendiri oleh administrator. Ketika aplikasi menyajikan token ke sumber daya, sumber daya memberlakukan bahwa aplikasi itu sendiri memiliki otorisasi untuk melakukan tindakan karena tidak ada pengguna yang terlibat dalam autentikasi. Artikel ini membahas kedua langkah yang diperlukan untuk:

Artikel ini menjelaskan cara memprogram secara langsung terhadap protokol dalam aplikasi Anda. Jika memungkinkan, kami sarankan Anda menggunakan Microsoft Authentication Libraries (MSAL) yang didukung sebagai gantinya untuk memperoleh token dan memanggil API web aman. Anda juga dapat merujuk ke aplikasi sampel yang menggunakan MSAL. Sebagai catatan samping, token refresh tidak akan pernah diberikan dengan alur ini sebagai client_id dan client_secret (yang akan diperlukan untuk mendapatkan token refresh) dapat digunakan untuk mendapatkan token akses sebagai gantinya.

Untuk tingkat jaminan yang lebih tinggi, platform identitas Microsoft juga memungkinkan layanan panggilan untuk mengautentikasi menggunakan sertifikat atau kredensial federasi alih-alih rahasia bersama. Karena kredensial aplikasi sendiri sedang digunakan, kredensial ini harus tetap aman. Jangan Pernah menerbitkan kredensial tersebut dalam kode sumber Anda, menyematkannya di halaman web, atau menggunakannya dalam aplikasi asli yang didistribusikan secara luas.

Diagram protokol

Seluruh alur kredensial klien terlihat mirip dengan diagram berikut. Kami menjelaskan masing-masing langkah nanti di artikel ini.

diagram memperlihatkan alur kredensial klien

Mendapatkan otorisasi langsung

Aplikasi biasanya menerima otorisasi langsung untuk mengakses sumber daya dengan salah satu dari dua cara:

Kedua metode ini adalah yang paling umum dalam ID Microsoft Entra dan kami merekomendasikannya untuk klien dan sumber daya yang melakukan alur kredensial klien. Sumber daya juga dapat memilih untuk mengotorisasi kliennya dengan cara lain. Setiap server sumber daya dapat memilih metode yang paling masuk akal untuk aplikasinya.

Daftar kontrol akses

Penyedia sumber daya mungkin memberlakukan pemeriksaan otorisasi berdasarkan daftar ID aplikasi (klien) yang diketahuinya dan memberikan tingkat akses tertentu. Ketika sumber daya menerima token dari platform identitas Microsoft, sumber daya dapat mendekode token dan mengekstrak ID aplikasi klien dari klaim appid dan iss. Kemudian membandingkan aplikasi dengan daftar kontrol akses (ACL) yang dikelolanya. Granularitas dan metode ACL mungkin bervariasi secara substansial antara sumber daya.

Kasus penggunaan umum adalah menggunakan ACL untuk menjalankan pengujian untuk aplikasi web atau untuk API web. API web mungkin hanya memberikan subset izin penuh kepada klien tertentu. Untuk menjalankan pengujian end-to-end pada API, Anda dapat membuat klien pengujian yang memperoleh token dari platform identitas Microsoft lalu mengirimkannya ke API. API kemudian memeriksa ACL untuk ID aplikasi klien pengujian untuk akses penuh ke seluruh fungsionalitas API. Jika Anda menggunakan ACL jenis ini, pastikan untuk memvalidasi tidak hanya nilai appid dari pemanggil tetapi juga memverifikasi bahwa nilai iss dari token tersebut dapat dipercaya.

Jenis otorisasi ini umum untuk daemon dan akun layanan yang perlu mengakses data yang dimiliki oleh pengguna konsumen yang memiliki akun Microsoft pribadi. Untuk data yang dimiliki oleh organisasi, kami sarankan Anda mendapatkan otorisasi yang diperlukan melalui izin aplikasi.

Mengontrol token tanpa klaim roles

Untuk mengaktifkan pola otorisasi berbasis ACL ini, ID Microsoft Entra tidak mengharuskan aplikasi diotorisasi untuk mendapatkan token untuk aplikasi lain. Dengan demikian, token khusus aplikasi dapat dikeluarkan tanpa klaim roles. Aplikasi yang mengekspos API harus menerapkan pemeriksaan izin untuk menerima token.

Jika Anda ingin mencegah aplikasi mendapatkan token akses khusus aplikasi tanpa peran untuk aplikasi Anda, memastikan bahwa persyaratan penugasan diaktifkan untuk aplikasi Anda. Ini akan memblokir pengguna dan aplikasi tanpa peran yang ditetapkan agar tidak bisa mendapatkan token untuk aplikasi ini.

Izin aplikasi

Alih-alih menggunakan ACL, Anda dapat menggunakan API untuk mengekspos sekumpulan izin aplikasi . Ini diberikan ke aplikasi oleh administrator organisasi, dan hanya dapat digunakan untuk mengakses data yang dimiliki oleh organisasi tersebut dan karyawannya. Misalnya, Microsoft Graph memaparkan beberapa izin aplikasi untuk melakukan hal berikut:

  • Membaca email di semua kotak surat
  • Membaca dan menulis email di semua kotak surat
  • Kirim email sebagai pengguna mana pun
  • Membaca data direktori

Untuk menggunakan peran aplikasi (izin aplikasi) dengan API Anda sendiri (dibandingkan dengan Microsoft Graph), Anda harus terlebih dahulu mengekspos peran aplikasi dalam pendaftaran aplikasi API di pusat admin Microsoft Entra. Kemudian, mengonfigurasi peran aplikasi yang diperlukan dengan memilih izin tersebut di pendaftaran aplikasi klien Anda. Jika Anda belum mengekspos peran aplikasi apa pun dalam pendaftaran aplikasi API, Anda tidak akan dapat menentukan izin aplikasi ke API tersebut di pendaftaran aplikasi aplikasi klien Anda di pusat admin Microsoft Entra.

Saat mengautentikasi sebagai aplikasi (dibandingkan dengan pengguna), Anda tidak dapat menggunakan izin yang didelegasikan karena tidak ada pengguna untuk aplikasi Anda bertindak atas nama. Anda harus menggunakan izin aplikasi, juga dikenal sebagai peran aplikasi, yang diberikan oleh admin atau oleh pemilik API.

Untuk informasi selengkapnya tentang izin aplikasi, lihat Izin dan persetujuan.

Biasanya, saat Anda membuat aplikasi yang menggunakan izin aplikasi, aplikasi memerlukan halaman atau tampilan tempat admin menyetujui izin aplikasi. Halaman ini dapat menjadi bagian dari proses masuk aplikasi, bagian dari pengaturan aplikasi, atau proses sambungan khusus. Seringkali logis bagi aplikasi untuk menampilkan tampilan terhubung ini hanya setelah pengguna masuk dengan akun Microsoft untuk kantor atau sekolah.

Jika Anda memasukkan pengguna ke aplikasi, Anda dapat mengidentifikasi organisasi tempat pengguna berada sebelum meminta pengguna untuk menyetujui izin aplikasi. Meskipun tidak benar-benar diperlukan, ini dapat membantu Anda menciptakan pengalaman yang lebih intuitif bagi pengguna Anda. Untuk memasukkan pengguna, ikuti tutorial protokol platform identitas Microsoft .

Meminta izin dari admin direktori

Saat Anda siap untuk meminta izin dari admin organisasi, Anda dapat mengalihkan pengguna ke platform identitas Microsoft titik akhir persetujuan admin.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Tips pro: Coba tempelkan permintaan berikut di browser.

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
Pengaturan Keadaan Deskripsi
tenant Diperlukan Penyewa direktori dari mana Anda ingin meminta izin. Ini bisa dalam format GUID atau nama yang mudah diingat. Jika Anda tidak tahu penyewa mana yang dimiliki pengguna dan Anda ingin mengizinkan mereka masuk dengan penyewa apa pun, gunakan common.
client_id Diperlukan ID Aplikasi (klien) yang ditetapkan oleh pusat admin Microsoft Entra – Pendaftaran Aplikasi kepada aplikasi Anda.
redirect_uri Diperlukan URI pengalihan tempat Anda ingin respons dikirim untuk ditangani aplikasi Anda. Ini harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di portal, kecuali bahwa itu harus dikodekan URL, dan dapat memiliki segmen jalur tambahan.
state Direkomendasikan Nilai yang disertakan dalam permintaan yang juga dikembalikan dalam respons token. Ini bisa menjadi string konten apa pun yang Anda inginkan. Status digunakan untuk mengodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi terjadi, seperti halaman atau tampilan tempat mereka berada.

Pada titik ini, MICROSOFT Entra ID memberlakukan bahwa hanya administrator penyewa yang dapat masuk untuk menyelesaikan permintaan. Administrator akan diminta untuk menyetujui semua izin aplikasi langsung yang telah Anda minta untuk aplikasi Anda di portal pendaftaran aplikasi.

Respons berhasil

Jika admin menyetujui izin untuk aplikasi Anda, respons yang berhasil terlihat seperti ini:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Pengaturan Deskripsi
tenant Penyewa direktori yang memberi aplikasi Anda izin yang dimintanya, dalam format GUID.
state Nilai yang disertakan dalam permintaan dan dikembalikan lagi dalam respon token. Ini bisa menjadi string konten apa pun yang Anda inginkan. Status digunakan untuk mengodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi terjadi, seperti halaman atau tampilan tempat mereka berada.
admin_consent Atur ke True.
Tanggapan kesalahan

Jika admin tidak menyetujui izin untuk aplikasi Anda, respons yang gagal terlihat seperti ini:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Pengaturan Deskripsi
error String kode kesalahan yang dapat Anda gunakan untuk mengklasifikasikan jenis kesalahan, dan yang dapat Anda gunakan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan.

Setelah Anda menerima respons yang berhasil dari titik akhir provisi aplikasi, aplikasi Anda telah mendapatkan izin aplikasi langsung yang dimintanya. Sekarang Anda dapat meminta token untuk sumber daya yang Anda inginkan.

Mendapatkan token

Setelah Anda memperoleh otorisasi yang diperlukan untuk aplikasi Anda, lanjutkan dengan memperoleh token akses untuk API. Untuk mendapatkan token dengan menggunakan pemberian kredensial klien, kirim permintaan POST ke platform identitas Microsoft /token. Ada beberapa kasus yang berbeda:

Kasus pertama: Permintaan token akses dengan rahasia bersama

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
Pengaturan Keadaan Deskripsi
tenant Diperlukan Aplikasi ini akan beroperasi terhadap penyewa direktori, dalam format GUID atau nama domain.
client_id Diperlukan ID aplikasi yang ditetapkan ke aplikasi milik Anda. Anda dapat menemukan informasi ini di portal tempat Anda mendaftarkan aplikasi.
scope Diperlukan Nilai yang diteruskan untuk parameter scope dalam permintaan ini harus menjadi pengidentifikasi sumber daya (URI ID aplikasi) dari sumber daya yang Anda inginkan, diakhiri dengan .default. Semua cakupan yang tercakup harus untuk satu sumber daya. Menyertakan cakupan untuk beberapa sumber daya akan mengakibatkan kesalahan.
Untuk contoh Microsoft Graph, nilainya https://graph.microsoft.com/.default. Nilai ini memberi tahu platform identitas Microsoft bahwa dari semua izin aplikasi langsung yang telah Anda konfigurasi untuk aplikasi Anda, titik akhir harus mengeluarkan token untuk yang terkait dengan sumber daya yang ingin Anda gunakan. Untuk mempelajari selengkapnya tentang cakupan /.default, lihat dokumentasi persetujuan .
client_secret Diperlukan Rahasia klien yang Anda buat untuk aplikasi Anda di portal pendaftaran aplikasi. Rahasia klien harus dikodekan URL sebelum dikirim. Pola otentikasi Basic yang memberikan kredensial di header Otorisasi, sesuai dengan RFC 6749, juga didukung.
grant_type Diperlukan Harus diatur ke client_credentials.

Kasus kedua: Permintaan token akses dengan sertifikat

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Pengaturan Keadaan Deskripsi
tenant Diperlukan Aplikasi ini akan beroperasi terhadap penyewa direktori, dalam format GUID atau nama domain.
client_id Diperlukan ID aplikasi (klien) yang ditetapkan ke aplikasi Anda.
scope Diperlukan Nilai yang diteruskan untuk parameter scope dalam permintaan ini harus menjadi pengidentifikasi sumber daya (URI ID aplikasi) dari sumber daya yang Anda inginkan, diakhiri dengan .default. Semua cakupan yang tercakup harus untuk satu sumber daya. Menyertakan cakupan untuk beberapa sumber daya akan mengakibatkan kesalahan.
Untuk contoh Microsoft Graph, nilainya https://graph.microsoft.com/.default. Nilai ini memberi tahu platform identitas Microsoft bahwa dari semua izin aplikasi langsung yang telah Anda konfigurasi untuk aplikasi Anda, titik akhir harus mengeluarkan token untuk yang terkait dengan sumber daya yang ingin Anda gunakan. Untuk mempelajari selengkapnya tentang cakupan /.default, lihat dokumentasi persetujuan .
client_assertion_type Diperlukan Nilai harus diatur ke urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Diperlukan Pernyataan (token web JSON) yang perlu Anda buat dan tanda tangani dengan sertifikat yang Anda daftarkan sebagai kredensial untuk aplikasi Anda. Baca tentang kredensial sertifikat untuk mempelajari cara mendaftarkan sertifikat Anda dan format pernyataan otentikasinya.
grant_type Diperlukan Harus diatur ke client_credentials.

Parameter untuk permintaan berbasis sertifikat hanya berbeda dalam satu cara dari permintaan berbasis rahasia bersama: parameter client_secret digantikan oleh parameter client_assertion_type dan client_assertion.

Kasus ketiga: Permintaan token akses dengan kredensial federasi

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Pengaturan Keadaan Deskripsi
client_assertion Diperlukan Pernyataan (token web JWT, atau JSON) yang didapatkan aplikasi Anda dari penyedia identitas lain di luar platform identitas Microsoft, seperti Kubernetes. Spesifikasi JWT ini harus didaftarkan pada aplikasi Anda sebagai kredensial identitas federasi . Baca tentang federasi beban kerja identitas untuk mempelajari cara mengonfigurasi dan memanfaatkan asersi dari penyedia identitas lain.

Semua yang ada dalam permintaan sama dengan alur berbasis sertifikat, dengan pengecualian penting yaitu sumber client_assertion. Dalam alur ini, aplikasi Anda tidak membuat pernyataan JWT itu sendiri. Sebagai gantinya, aplikasi Anda menggunakan JWT yang dibuat oleh penyedia identitas lain. Ini disebut federasi identitas beban kerja, di mana identitas aplikasi Anda di platform identitas lain digunakan untuk memperoleh token di dalam platform identitas Microsoft. Ini paling cocok untuk skenario lintas cloud, seperti menghosting komputasi Anda di luar Azure tetapi mengakses API yang dilindungi oleh platform identitas Microsoft. Untuk informasi tentang format JWT yang diperlukan yang dibuat oleh penyedia identitas lain, baca tentang format pernyataan .

Respons berhasil

Respons yang berhasil dari metode apa pun terlihat seperti ini:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Pengaturan Deskripsi
access_token Token akses yang diminta. Aplikasi ini dapat menggunakan token ini untuk mengautentikasi ke sumber daya aman, seperti ke API web.
token_type Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung platform identitas Microsoft adalah bearer.
expires_in Jumlah waktu token akses valid (dalam detik).

Peringatan

Jangan mencoba memvalidasi atau membaca token untuk API apa pun yang tidak Anda miliki, termasuk token dalam contoh ini, dalam kode Anda. Token untuk layanan Microsoft dapat menggunakan format khusus yang tidak akan divalidasi sebagai JWT, dan juga dapat dienkripsi untuk pengguna konsumen (akun Microsoft). Meskipun membaca token adalah alat penelusuran kesalahan dan pembelajaran yang berguna, jangan ambil ketergantungan terhadapnya dalam kode Anda atau berasumsi tentang spesifikasi token yang bukan untuk API yang Anda kendalikan.

Tanggapan kesalahan

Respons kesalahan (400 Permintaan Buruk) terlihat seperti ini:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "YYYY-MM-DD HH:MM:SSZ",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Pengaturan Deskripsi
error String kode kesalahan yang dapat Anda gunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan tertentu yang mungkin membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.
error_codes Daftar kode kesalahan khusus STS yang mungkin membantu diagnostik.
timestamp Waktu ketika kesalahan terjadi.
trace_id Pengidentifikasi unik untuk permintaan guna membantu diagnostik.
correlation_id Pengidentifikasi unik permintaan untuk membantu diagnostik antar komponen.

Gunakan token

Sekarang setelah Anda memperoleh token, gunakan token untuk membuat permintaan ke sumber daya. Ketika token kedaluwarsa, ulangi permintaan ke titik akhir /token untuk memperoleh token akses baru.

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...

Coba perintah berikut di terminal Anda, pastikan untuk mengganti token dengan token Anda sendiri.

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'

Sampel kode dan dokumentasi lainnya

Baca dokumentasi gambaran umum kredensial klien dari Microsoft Authentication Library

Contoh Plattform Deskripsi
active-directory-dotnetcore-daemon-v2 .NET 6.0+ Aplikasi ASP.NET Core yang menampilkan pengguna penyewa yang mengkueri Microsoft Graph menggunakan identitas aplikasi, bukan atas nama pengguna. Sampel juga mengilustrasikan variasi menggunakan sertifikat untuk autentikasi.
active-directory-dotnet-daemon-v2 ASP.NET MVC Aplikasi web yang menyinkronkan data dari Microsoft Graph menggunakan identitas aplikasi, bukan atas nama pengguna.
ms-identity-javascript-nodejs-console Konsol Node.js Aplikasi Node.js yang menampilkan pengguna dari penyewa dengan melakukan kueri pada Microsoft Graph menggunakan identitas aplikasi