Platform identitas Microsoft dan alur kredensial klien OAuth 2.0

  • Artikel

Alur pemberian kredensial klien OAuth 2.0 mengizinkan layanan web (klien rahasia) untuk menggunakan kredesialnya sendiri, bukan meniru identitas pengguna, untuk mengautentikasi saat memanggil layanan web lain. Hibah yang ditentukan dalam RFC 6749, kadang-kadang disebut OAuth dua kaki, dapat digunakan untuk mengakses sumber daya yang dihosting 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 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 langsung terhadap protokol di aplikasi Anda. Jika memungkinkan, sebaiknya Anda menggunakan Pustaka Autentikasi Microsoft (MSAL) yang didukung, bukan untuk memperoleh token dan memanggil API web aman. Anda juga dapat merujuk ke aplikasi sampel yang menggunakan MSAL. Sebagai catatan tambahan, token refresh tidak akan pernah diberikan dengan alur ini karena 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 gabungan, bukan 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 dalam artikel ini.

Diagram showing the client credentials flow

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. Tiap server sumber daya dapat memilih metode yang paling masuk akal untuk aplikasinya.

Daftar kontrol akses

Penyedia sumber daya dapat memberlakukan pemeriksaan otorisasi berdasarkan daftar ID aplikasi (klien) yang diketahui 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. Selanjutnya ini membandingkan aplikasi dengan daftar kontrol akses (ACL) yang dikelolanya. Granularitas dan metode ACL mungkin sangat bervariasi di antara sumber daya.

Kasus penggunaan umum adalah menggunakan ACL untuk menjalankan pengujian untuk aplikasi web atau untuk API web. API web mungkin hanya memberikan subnet izin penuh ke 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 selanjutnya memeriksa ACL untuk ID aplikasi klien pengujian untuk akses penuh ke seluruh fungsi API. Jika Anda menggunakan ACL semacam ini, pastikan untuk memvalidasi tidak hanya nilai appid pemanggil, tetapi juga memvalidasi bahwa nilai iss token tepercaya.

Jenis otorisasi ini umum untuk daemon dan akun layanan yang perlu mengakses data yang dimiliki oleh pengguna konsumen yang memiliki akun Microsoft personal. Untuk data yang dimiliki oleh organisasi, sebaiknya dapatkan 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 diterbitkan 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, pastikan persyaratan penetapan diaktifkan untuk aplikasi Anda. Tindakan ini akan memblokir pengguna dan aplikasi tanpa peran yang ditetapkan 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 mengekspos beberapa izin aplikasi untuk melakukan hal berikut:

  • Membaca email di semua kotak surat
  • Membaca dan menulis email di semua kotak surat
  • Mengirim email sebagai pengguna
  • 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, konfigurasikan peran aplikasi yang diperlukan dengan memilih izin tersebut dalam 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 (bukan pengguna), Anda tidak dapat menggunakan izin yang didelegasikan karena tidak ada pengguna untuk aplikasi Anda yang bertindak atas namanya. 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 membangun aplikasi yang menggunakan izin aplikasi, aplikasi memerlukan halaman atau tampilan tempat admin menyetujui izin aplikasi. Halaman ini dapat menjadi bagian dari alur masuk aplikasi, bagian dari pengaturan aplikasi, atau alur koneksi khusus. Seringkali masuk akal bagi aplikasi untuk menampilkan tampilan koneksi ini hanya setelah pengguna masuk dengan akun Microsoft kantor atau sekolah.

Jika Anda memasukkan pengguna ke aplikasi, Anda dapat mengidentifikasi organisasi tempat pengguna berada sebelum meminta pengguna menyetujui izin aplikasi. Meskipun tidak terlalu 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 siap untuk meminta izin dari admin organisasi, Anda dapat mengalihkan pengguna ke titik akhir persetujuan admin platform identitas Microsoft.

// 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
Parameter Kondisi Deskripsi
tenant Wajib diisi Penyewa direktori yang ingin dimintai izinnya. Ini bisa dalam format GUID atau nama yang mudah dikenal. Jika Anda tidak mengetahui penyewa mana yang memiliki pengguna dan Anda ingin mengizinkan mereka masuk dengan penyewa mana pun, gunakan common.
client_id Diperlukan ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – pengalaman Pendaftaran aplikasi ke aplikasi Anda.
redirect_uri Diperlukan URI pengalihan tempat Anda ingin respons dikirim untuk ditangani aplikasi Anda. Itu harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di portal, kecuali bahwa itu harus disandikan URL, dan dapat memiliki segmen jalur tambahan.
state Disarankan Nilai yang disertakan dalam permintaan yang juga dikembalikan dalam respons token. Ini bisa berupa string dari konten apa pun yang ingin Anda gunakan. Status ini digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, 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 sudah Anda minta untuk aplikasi Anda di portal pendaftaran aplikasi.

Respons berhasil

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

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parameter Deskripsi
tenant Penyewa direktori yang memberi izin yang diminta aplikasi Anda, dalam format GUID.
state Nilai yang disertakan dalam permintaan yang juga dikembalikan dalam respons token. Ini bisa berupa string dari konten apa pun yang ingin Anda gunakan. Status ini digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.
admin_consent Atur ke Benar.
Respons 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
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan yang dapat Anda gunakan untuk menanggapi kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan.

Setelah Anda menerima respons yang berhasil dari titik akhir penyediaan aplikasi, aplikasi Anda sudah 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 /token platform identitas Microsoft. Ada beberapa kasus yang berbeda:

Kasus pertama: Mengakses permintaan token 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=sampleCredentials
&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'
Parameter Kondisi Deskripsi
tenant Wajib diisi Penyewa direktori yang rencananya akan dioperasikan oleh aplikasi, dalam format GUID atau nama domain.
client_id Diperlukan ID aplikasi yang ditetapkan ke aplikasi Anda. Anda dapat menemukan informasi ini di portal tempat Anda mendaftarkan aplikasi.
scope Diperlukan Nilai yang dilewatkan untuk parameter scope dalam permintaan ini harus menjadi pengidentifikasi sumber daya (URI ID aplikasi) dari sumber daya yang Anda inginkan, yang diawali dengan akhiran .default. Semua cakupan yang disertakan harus untuk satu sumber daya. Menyertakan cakupan untuk beberapa sumber daya akan mengakibatkan kesalahan.
Untuk contoh Microsoft Graph, nilainya adalah 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 dienkodekan dengan URL sebelum dikirim. Pola autentikasi Dasar melainkan pemberian info masuk di header Otorisasi, per RFC 6749 juga didukung.
grant_type Diperlukan Harus diatur ke client_credentials.

Kasus kedua: Meminta 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
Parameter Kondisi Deskripsi
tenant Wajib diisi Penyewa direktori yang rencananya akan dioperasikan oleh aplikasi, dalam format GUID atau nama domain.
client_id Diperlukan ID aplikasi (klien) yang ditetapkan ke aplikasi Anda.
scope Diperlukan Nilai yang dilewatkan untuk parameter scope dalam permintaan ini harus menjadi pengidentifikasi sumber daya (URI ID aplikasi) dari sumber daya yang Anda inginkan, yang diawali dengan akhiran .default. Semua cakupan yang disertakan harus untuk satu sumber daya. Menyertakan cakupan untuk beberapa sumber daya akan mengakibatkan kesalahan.
Untuk contoh Microsoft Graph, nilainya adalah 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 kredensial sertifikat untuk mempelajari cara mendaftarkan sertifikat Anda dan format pernyataan.
grant_type Diperlukan Harus diatur ke client_credentials.

Parameter untuk permintaan berbasis sertifikat hanya berbeda dalam satu hal dari permintaan berbagi berbasis rahasia: parameter client_secret diganti dengan parameter client_assertion_type dan client_assertion.

Kasus ketiga: Akses permintaan token 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
Parameter Kondisi Deskripsi
client_assertion Wajib diisi Pernyataan (token web JWT, atau JSON) yang diperoleh aplikasi Anda dari IdP lain di luar platform identitas Microsoft, seperti Kubernetes. Spesifikasi JWT ini harus didaftarkan pada aplikasi Anda sebagai kredensial identitas federasi. Baca tentang federasi identitas beban kerja untuk mempelajari cara menyiapkan dan menggunakan pernyataan yang dihasilkan dari penyedia identitas lain.

Semua yang ada dalam permintaan sama dengan alur berbasis sertifikat, dengan pengecualian penting dari client_assertionsumber . 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. Hal 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 eksternal, 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..."
}
Parameter Deskripsi
access_token Token akses yang diminta. Aplikasi dapat menggunakan token ini untuk mengautentikasi ke sumber daya yang aman, seperti API web.
token_type Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung platform identitas Microsoft adalah bearer.
expires_in Frekuensi 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 mengambil dependensi terhadapnya dalam kode Anda atau asumsikan hal-hal yang spesifik tentang token yang bukan untuk API yang Anda kontrol.

Respons 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"
}
Parameter Deskripsi
error String kode galat yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan untuk menanggapi kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.
error_codes Daftar kode kesalahan khusus STS yang mungkin membantu diagnostik.
timestamp Waktu kesalahan terjadi.
trace_id Pengidentifikasi unik untuk permintaan untuk membantu diagnostik.
correlation_id Pengidentifikasi unik untuk permintaan untuk membantu diagnostik di seluruh komponen.

Menggunakan token

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

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

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

Sampel Platform 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 menggambarkan 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 penyewa dengan mengkueri Microsoft Graph menggunakan identitas aplikasi