Platform identitas Microsoft dan alur kredensial klien OAuth 2.0

Anda dapat menggunakan pemberian kredensial klien OAuth 2.0 yang ditentukan dalam RFC 6749, terkadang disebut two-legged OAuth, untuk mengakses sumber daya yang dihosting web dengan menggunakan identitas aplikasi. Jenis pemberian ini umumnya digunakan untuk interaksi server-ke-server yang harus dijalankan di latar belakang, tanpa interaksi langsung dengan pengguna. Jenis aplikasi ini sering disebut sebagai daemon atau akun layanan.

Artikel ini menjelaskan cara memprogram protokol secara langsung di aplikasi Anda. Jika memungkinkan, kami sarankan Anda menggunakan Microsoft Authentication Libraries (MSAL) yang didukung alih-alih mendapatkan token dan memanggil API web aman. Lihat juga sampel aplikasi yang menggunakan MSAL.

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. Untuk tingkat jaminan yang lebih tinggi, platform identitas Microsoft juga memungkinkan layanan panggilan untuk mengautentikasi menggunakan sertifikat atau kredensial gabungan, bukan rahasia bersama. Karena info masuk aplikasi itu sendiri sedang digunakan, info masuk ini harus disimpan dengan aman - jangan pernah memublikasikan info masuk itu dalam kode sumber Anda, menyematkannya di halaman web, atau menggunakannya dalam aplikasi asli yang didistribusikan secara luas.

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 langkah yang diperlukan untuk mengotorisasi aplikasi untuk memanggil API, serta cara mendapatkan token yang diperlukan untuk memanggil API tersebut.

Tip

Try running this request in Postman
Coba jalankan permintaan ini dan banyak lagi di Postman - jangan lupa untuk mengganti token dan ID!

Diagram protokol

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

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 di Microsoft Azure Active Directory serta kami merekomendasikannya untuk klien dan sumber daya yang menjalankan 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, buat klien pengujian yang memperoleh token dari platform identitas Microsoft, lalu kirimkan 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, Microsoft Azure Active Directory 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. Izin aplikasi diberikan ke aplikasi oleh administrator organisasi, dan hanya dapat digunakan untuk mengakses data yang dimiliki oleh organisasi tersebut serta 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 dulu mengekspos peran aplikasi dalam pendaftaran aplikasi API di portal Azure. 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 dalam pendaftaran aplikasi di aplikasi klien Anda dalam portal Azure.

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 dapat menjadi alur "terhubung" khusus. Dalam banyak kasus, dapat dimengerti jika aplikasi menampilkan tampilan "terhubung" 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=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Tips pro: Coba tempelkan permintaan berikut di browser.

https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
Parameter Kondisi Deskripsi
tenant Diperlukan 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 pengalaman portal Microsoft Azure – 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 mengenkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.

Pada titik ini, Microsoft Azure Active Directory 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=a8990e1f-ff32-408a-9f8e-78d3b9139b95&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 mengenkodekan 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 menggunakan pemberian kredensial klien, kirim permintaan POST ke /token platform identitas Microsoft:

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
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=qWgdYAmab0YSkuL1qKv5bPX&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
Parameter Kondisi Deskripsi
tenant Diperlukan 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. 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
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&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 Diperlukan 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. 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, ini 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. Untuk mempelajari cara mendaftarkan sertifikat Anda dan format pernyataan, lihat kredensial sertifikat.
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
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&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 Diperlukan 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 di atas, dengan satu pengecualian penting - 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. 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
# Pro tip: Try the following command! (Replace the token with your own.)

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

Sampel kode dan dokumentasi lainnya

Baca dokumentasi gambaran umum kredensial klien dari Microsoft Authentication Library

Sampel Platform Deskripsi
active-directory-dotnetcore-daemon-v2 Konsol .NET Core 2.1 Aplikasi .NET Core sederhana yang menampilkan pengguna penyewa yang mengueri 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.