Platform identitas Microsoft dan aliran On-Behalf-Of OAuth 2.0
Alur atas nama (OBO) menjelaskan skenario API web menggunakan identitas selain miliknya sendiri untuk memanggil API web lain. Disebut sebagai delegasi di OAuth, niatnya adalah untuk meneruskan identitas dan izin pengguna melalui rantai permintaan.
Agar layanan tingkat menengah membuat permintaan terautentikasi ke layanan hilir, layanan perlu mengamankan token akses dari platform identitas Microsoft. Ini hanya menggunakan cakupan yang didelegasikan dan bukan peran aplikasi. Peran tetap melekat pada prinsipal (pengguna) dan tidak pernah ke aplikasi yang beroperasi atas nama pengguna. Ini terjadi untuk mencegah pengguna mendapatkan izin ke sumber daya yang seharusnya tidak mereka akses.
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. Lihat juga aplikasi sampel yang menggunakan MSAL misalnya.
Batasan Klien
Jika perwakilan layanan meminta token khusus aplikasi dan mengirimkannya ke API, API tersebut kemudian akan bertukar token yang tidak mewakili perwakilan layanan asli. Ini karena alur OBO hanya berfungsi untuk prinsipal pengguna. Sebagai gantinya, ia harus menggunakan alur kredensial klien untuk mendapatkan token khusus aplikasi. Dalam kasus aplikasi halaman tunggal (SPAs), mereka harus meneruskan token akses ke klien rahasia tingkat menengah untuk melakukan alur OBO sebagai gantinya.
Jika klien menggunakan alur implisit untuk mendapatkan id_token dan juga memiliki wildcard dalam URL balasan, id_token tidak dapat digunakan untuk alur OBO. Kartubebas adalah URL yang diakhir * dengan karakter. Misalnya, jika https://myapp.com/* adalah URL balasan, id_token tidak dapat digunakan karena tidak cukup spesifik untuk mengidentifikasi klien. Ini akan mencegah token dikeluarkan. Namun, token akses yang diperoleh melalui alur pemberian implisit ditukarkan oleh klien rahasia, bahkan jika klien yang memulai memiliki URL balasan wildcard yang terdaftar. Ini karena klien rahasia dapat mengidentifikasi klien yang memperoleh token akses. Klien rahasia kemudian dapat menggunakan token akses untuk memperoleh token akses baru untuk API hilir.
Selain itu, aplikasi dengan kunci penandatanganan kustom tidak dapat digunakan sebagai API tingkat menengah dalam alur OBO. Ini termasuk aplikasi perusahaan yang dikonfigurasi untuk akses menyeluruh. Jika API tingkat menengah menggunakan kunci penandatanganan kustom, API hilir tidak akan memvalidasi tanda tangan token akses yang diteruskan ke dalamnya. Ini menghasilkan kesalahan karena token yang ditandatangani dengan kunci yang dikendalikan oleh klien tidak dapat diterima dengan aman.
Diagram protokol
Asumsikan bahwa pengguna mengautentikasi aplikasi menggunakan alur pemberian kode otorisasi OAuth 2.0 atau alur masuk lainnya. Pada titik ini, aplikasi memiliki token akses untuk API A (token A) dengan klaim pengguna dan persetujuan untuk mengakses API web tingkat menengah (API A). Sekarang, API A perlu membuat permintaan yang diautentikasi ke API web hilir (API B).
Langkah-langkah berikutnya merupakan aliran OBO dan dijelaskan dengan bantuan diagram berikut.
- Aplikasi klien membuat permintaan ke API A dengan token A (dengan klaim
audAPI A). - API A mengautentikasi ke titik akhir penerbitan token platform identitas Microsoft dan meminta token untuk mengakses API B.
- Titik akhir penerbitan token platform identitas Microsoft memvalidasi kredensial API A bersama dengan token A dan mengeluarkan token akses untuk API B (token B) ke API A.
- Token B diatur oleh API A di header otorisasi permintaan ke API B.
- Data dari sumber daya aman dikembalikan oleh API B ke API A, lalu ke klien.
Dalam skenario ini, layanan tingkat menengah tidak memiliki interaksi pengguna untuk mendapatkan persetujuan pengguna untuk mengakses API hilir. Oleh karena itu, opsi untuk memberikan akses ke API hilir disajikan di muka sebagai bagian dari langkah persetujuan selama autentikasi. Untuk mempelajari cara menerapkan ini di aplikasi Anda, lihat Mendapatkan persetujuan untuk aplikasi tingkat menengah.
Permintaan token akses tingkat menengah
Untuk meminta token akses, buat HTTP POST ke titik akhir token platform identitas Microsoft khusus penyewa dengan parameter berikut.
https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
Peringatan
JANGAN mengirim token akses yang dikeluarkan ke tingkat tengah ke mana saja kecuali audiens yang dimaksudkan untuk token. Token akses yang dikeluarkan ke tingkat tengah ditujukan untuk digunakan hanya oleh tingkat menengah tersebut untuk berkomunikasi dengan titik akhir audiens yang dimaksudkan.
Risiko keamanan menyampaikan token akses dari sumber daya tingkat menengah ke klien (alih-alih klien mendapatkan token akses itu sendiri), meliputi:
- Peningkatan risiko intersepsi token atas saluran SSL/TLS yang dikompromikan.
- Ketidakmampuan untuk memenuhi skenario pengikatan token dan Akses Bersyarat yang memerlukan peningkatan klaim (misalnya, MFA, Frekuensi Masuk).
- Ketidakcocokan dengan kebijakan berbasis perangkat yang dikonfigurasi admin (contoh, MDM, kebijakan berbasis lokasi).
Ada dua kasus tergantung pada apakah aplikasi klien memilih untuk diamankan oleh rahasia bersama atau sertifikat.
Kasus pertama: Mengakses permintaan token dengan rahasia bersama
Saat menggunakan rahasia bersama, permintaan token akses layanan ke layanan berisi parameter berikut:
| Parameter | Jenis | Deskripsi |
|---|---|---|
grant_type |
Wajib diisi | Jenis permintaan token. Untuk permintaan menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Diperlukan | ID aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra - halaman Pendaftaran aplikasi ke aplikasi Anda. |
client_secret |
Diperlukan | Rahasia klien yang Anda buat untuk aplikasi Anda di pusat admin Microsoft Entra - halaman Pendaftaran aplikasi. Pola autentikasi Dasar melainkan pemberian info masuk di header Otorisasi, per RFC 6749 juga didukung. |
assertion |
Diperlukan | Token akses yang dikirim ke API tingkat menengah. Token ini harus memiliki audiens (aud) klaim aplikasi membuat permintaan OBO ini (aplikasi yang ditandai oleh client-id bidang). Aplikasi tidak dapat menukarkan token untuk aplikasi lain (misalnya, jika klien mengirim API token yang dimaksudkan untuk Microsoft Graph, API tidak dapat menukarkannya menggunakan OBO. Sebaliknya harus menolak token). |
scope |
Diperlukan | Daftar ruang lingkup yang dipisahkan untuk permintaan token. Untuk informasi selengkapnya, lihat cakupan. |
requested_token_use |
Diperlukan | Menentukan bagaimana permintaan harus diproses. Dalam aliran OBO, nilai harus diatur ke on_behalf_of. |
Contoh
HTTP POST berikut meminta token akses dan token refresh dengan cakupan user.read untuk API web https://graph.microsoft.com. Permintaan ditandatangani dengan rahasia klien dan dibuat oleh klien rahasia.
//line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of
Kasus kedua: Meminta token akses dengan sertifikat
Permintaan token akses layanan ke layanan dengan sertifikat berisi parameter berikut selain parameter dari contoh sebelumnya:
| Parameter | Jenis | Deskripsi |
|---|---|---|
grant_type |
Wajib diisi | Jenis permintaan token. Untuk permintaan menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Diperlukan | ID aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra - halaman Pendaftaran aplikasi ke aplikasi Anda. |
client_assertion_type |
Diperlukan | Nilainya harus 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. |
assertion |
Diperlukan | Token akses yang dikirim ke API tingkat menengah. Token ini harus memiliki audiens (aud) klaim aplikasi membuat permintaan OBO ini (aplikasi yang ditandai oleh client-id bidang). Aplikasi tidak dapat menukarkan token untuk aplikasi lain (misalnya, jika klien mengirim API token yang dimaksudkan untuk MS Graph, API tidak dapat menukarkannya menggunakan OBO. Sebaliknya harus menolak token). |
requested_token_use |
Diperlukan | Menentukan bagaimana permintaan harus diproses. Dalam aliran OBO, nilai harus diatur ke on_behalf_of. |
scope |
Diperlukan | Daftar ruang lingkup yang dipisahkan untuk permintaan token. Untuk informasi selengkapnya, lihat cakupan. |
Perhatikan bahwa parameter hampir sama seperti dalam kasus permintaan oleh rahasia bersama, kecuali bahwa client_secret parameter digantikan oleh dua parameter: a client_assertion_type dan client_assertion. Parameter client_assertion_type diatur ke urn:ietf:params:oauth:client-assertion-type:jwt-bearer dan client_assertion parameter diatur ke token JWT yang ditandatangani dengan kunci privat sertifikat.
Contoh
HTTP POST berikut meminta token akses dan token refresh dengan user.read cakupan untuk https://graph.microsoft.com API web dengan sertifikat. Permintaan ditandatangani dengan rahasia klien dan dibuat oleh klien rahasia.
// line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&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}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access
Respons token akses tingkat menengah
Respons sukses adalah respons JSON OAuth 2.0 dengan parameter berikut.
| Parameter | Deskripsi |
|---|---|
token_type |
Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung platform identitas Microsoft adalah Bearer. Untuk informasi lebih lanjut tentang token pembawa, lihat Kerangka Kerja Otorisasi OAuth 2.0: Penggunaan Token Pembawa (RFC 6750). |
scope |
Ruang lingkup akses yang diberikan dalam token. |
expires_in |
Masa berlaku token akses (dalam detik), bahwa token akses adalah sah. |
access_token |
Token akses yang diminta. Layanan panggilan dapat menggunakan token ini untuk mengautentikasi ke layanan penerimaan. |
refresh_token |
Token refresh untuk token akses yang diminta. Layanan panggilan dapat menggunakan token ini untuk meminta token akses lain setelah token akses saat ini kedaluwarsa. Token refresh hanya disediakan jika offline_access ruang lingkup diminta. |
Contoh respons keberhasilan
Contoh berikut menunjukkan respons keberhasilan terhadap permintaan token akses untuk https://graph.microsoft.com API web. Respons berisi token akses dan token refresh dan ditandatangani dengan kunci privat sertifikat.
{
"token_type": "Bearer",
"scope": "https://graph.microsoft.com/user.read",
"expires_in": 3269,
"ext_expires_in": 0,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
"refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}
Token akses ini adalah token berformat v1.0 untuk Microsoft Graph. Ini karena format token didasarkan pada sumber daya yang diakses dan tidak terkait dengan endpoint yang digunakan untuk memintanya. Microsoft Graph disiapkan untuk menerima token v1.0, sehingga platform identitas Microsoft menghasilkan token akses v1.0 saat klien meminta token untuk Microsoft Graph. Aplikasi lain dapat menunjukkan bahwa mereka menginginkan token format v2.0, token format v1.0, atau bahkan format token eksklusif atau terenkripsi. Titik akhir v1.0 dan v2.0 dapat memancarkan salah satu format token. Dengan cara ini, sumber daya selalu bisa mendapatkan format token yang tepat terlepas dari bagaimana atau di mana token diminta oleh klien.
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.
Contoh respons kesalahan
Respons kesalahan dikembalikan oleh titik akhir token saat mencoba memperoleh token akses untuk API hilir, jika API hilir memiliki kebijakan Akses Bersyarat (seperti autentikasi multifaktor) yang ditetapkan. Layanan tingkat menengah harus menampilkan kesalahan ini ke aplikasi klien sehingga aplikasi klien dapat memberikan interaksi pengguna untuk memenuhi kebijakan Akses Bersyarat.
Untuk menampilkan kesalahan ini kembali ke klien, layanan tingkat menengah membalas dengan HTTP 401 Tidak Sah dan dengan header HTTP WWW-Authenticate yang berisi kesalahan dan tantangan klaim. Klien harus mengurai header ini dan memperoleh token baru dari penerbit token, dengan menyajikan tantangan klaim jika ada. Klien tidak boleh mencoba lagi untuk mengakses layanan tingkat menengah menggunakan token akses cache.
{
"error":"interaction_required",
"error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
"error_codes":[50079],
"timestamp":"2017-05-01 22:43:20Z",
"trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
"claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"9ab03e19-ed42-4168-b6b7-7001fb3e933a\"]}}}"
}
Gunakan token akses untuk mengakses sumber daya yang aman
Sekarang layanan tingkat menengah dapat menggunakan token yang diperoleh sebelumnya untuk membuat permintaan terautentikasi ke API web hilir, dengan mengatur token di Authorization header.
Contoh
GET /v1.0/me HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Pernyataan SAML diperoleh dengan aliran OBO OAuth2.0
Beberapa layanan web berbasis OAuth perlu mengakses API layanan web lain yang menerima pernyataan SAML dalam alur non-interaktif. MICROSOFT Entra ID dapat memberikan pernyataan SAML sebagai respons terhadap alur Atas Nama yang menggunakan layanan web berbasis SAML sebagai sumber daya target.
Ini adalah ekstensi nonstandar untuk alur On-Behalf-Of OAuth 2.0 yang memungkinkan aplikasi berbasis OAuth2 mengakses titik akhir API layanan web yang menggunakan token SAML.
Tip
Ketika Anda memanggil layanan web yang dilindungi SAML dari aplikasi web front-end, Anda cukup memanggil API dan memulai aliran autentikasi interaktif normal dengan sesi pengguna yang ada. Anda hanya perlu menggunakan alur OBO saat panggilan layanan ke layanan memerlukan token SAML untuk memberikan konteks pengguna.
Dapatkan token SAML dengan menggunakan permintaan OBO dengan rahasia bersama
Permintaan layanan ke layanan untuk pernyataan SAML berisi parameter berikut:
| Parameter | Jenis | Deskripsi |
|---|---|---|
| grant_type | diperlukan | Jenis permintaan token. Untuk permintaan yang menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer. |
| assertion | diperlukan | Nilai token akses yang digunakan dalam permintaan. |
| client_id | diperlukan | ID aplikasi yang ditetapkan ke layanan panggilan selama pendaftaran dengan ID Microsoft Entra. Untuk menemukan ID aplikasi di pusat admin Microsoft Entra, telusuri ke Aplikasi> Identitas>Pendaftaran aplikasi lalu pilih nama aplikasi. |
| client_secret | diperlukan | Kunci yang terdaftar untuk layanan panggilan di ID Microsoft Entra. Nilai ini harus dicatat pada saat pendaftaran. Pola autentikasi Dasar melainkan pemberian info masuk di header Otorisasi, per RFC 6749 juga didukung. |
| cakupan | diperlukan | Daftar ruang lingkup yang dipisahkan untuk permintaan token. Untuk informasi selengkapnya, lihat cakupan. SAML sendiri tidak memiliki konsep cakupan, tetapi digunakan untuk mengidentifikasi aplikasi SAML target yang ingin Anda terima tokennya. Untuk alur OBO ini, nilai cakupan harus selalu menjadi ID Entitas SAML dengan /.default ditambahkan. Misalnya, jika ID Entitas aplikasi SAML adalah https://testapp.contoso.com, maka cakupan yang diminta harus https://testapp.contoso.com/.default. Jika ID Entitas tidak dimulai dengan skema URI seperti https:, Microsoft Entra mengawali ID Entitas dengan spn:. Dalam hal ini Anda harus meminta cakupan spn:<EntityID>/.default, misalnya spn:testapp/.default jika ID Entitas adalah testapp. Nilai cakupan yang Anda minta di sini menentukan elemen yang Audience dihasilkan dalam token SAML, yang mungkin penting bagi aplikasi SAML yang menerima token. |
| requested_token_use | diperlukan | Menentukan bagaimana permintaan harus diproses. Dalam alur Atas Nama, nilainya harus on_behalf_of. |
| requested_token_type | diperlukan | Menentukan tipe token yang diminta. Nilainya bisa urn:ietf:params:oauth:token-type:saml2 atau urn:ietf:params:oauth:token-type:saml1 tergantung pada persyaratan sumber daya yang diakses. |
Respons berisi token SAML yang dikodekan dalam UTF8 dan Base 64url.
- SubjectConfirmationData untuk pernyataan SAML yang bersumber
Recipientdari panggilan OBO: Jika aplikasi target memerlukan nilai dalam , maka nilai harus dikonfigurasiSubjectConfirmationDatasebagai URL Balasan nonwildcard pertama dalam konfigurasi aplikasi sumber daya. Karena URL Balasan default tidak digunakan untuk menentukanRecipientnilai, Anda mungkin harus menyusun ulang URL Balasan dalam konfigurasi aplikasi untuk memastikan bahwa URL Balasan nonwildcard pertama digunakan. Untuk informasi selengkapnya, lihat URL Balasan. - Node SubjectConfirmationData: Simpul tidak dapat berisi
InResponseToatribut karena bukan bagian dari respons SAML. Aplikasi yang menerima token SAML harus dapat menerima pernyataan SAML tanpaInResponseToatribut. - Izin API: Anda harus menambahkan izin API yang diperlukan pada aplikasi tingkat menengah untuk mengizinkan akses ke aplikasi SAML, sehingga dapat meminta token untuk
/.defaultcakupan aplikasi SAML. - Persetujuan: Persetujuan harus diberikan untuk menerima token SAML yang berisi data pengguna pada alur OAuth. Untuk informasi, lihat Mendapatkan persetujuan untuk aplikasi tingkat menengah.
Tanggapan dengan pernyataan SAML
| Parameter | Deskripsi |
|---|---|
| token_type | Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung microsoft Entra ID adalah Pembawa. Untuk informasi lebih lanjut tentang token pembawa, lihat Kerangka Kerja Otorisasi OAuth 2.0: Penggunaan Token Pembawa (RFC 6750). |
| cakupan | Ruang lingkup akses yang diberikan dalam token. |
| Berakhir dalam | Masa berlaku token akses (dalam detik). |
| expires_on | Rentang waktu kapan token akses kedaluwarsa. Tanggal tersebut dinyatakan sebagai jumlah detik dari 1970-01-01T0:0:0Z UTC hingga waktu kedaluwarsa. Nilai ini digunakan untuk menentukan masa pakai token cache. |
| resource | URI ID aplikasi dari layanan penerimaan (sumber daya aman). |
| access_token | Parameter yang mengembalikan pernyataan SAML. |
| refresh_token | Token segarjan. Layanan panggilan dapat menggunakan token ini untuk meminta token akses lain setelah assertion SAML saat ini kedaluwarsa. |
- token_type: Pembawa
- expires_in: 3296
- ext_expires_in: 0
- expires_on: 1529627844
- sumber daya:
https://api.contoso.com - access_token: <Pernyataan SAML>
- issued_token_type: guci:ietf:params:oauth:token-type:saml2
- refresh_token: <Token refresh>
Mendapatkan persetujuan untuk aplikasi tingkat menengah
Tujuan dari alur OBO adalah untuk memastikan persetujuan yang tepat diberikan sehingga aplikasi klien dapat memanggil aplikasi tingkat menengah dan aplikasi tingkat menengah memiliki izin untuk memanggil sumber daya back-end. Bergantung pada arsitektur atau penggunaan aplikasi Anda, Anda harus mempertimbangkan hal berikut untuk memastikan bahwa alur OBO berhasil:
.default dan persetujuan gabungan
Aplikasi tingkat menengah menambahkan klien ke daftar aplikasi klien yang diketahui (knownClientApplications) dalam manifesnya. Jika permintaan persetujuan dipicu oleh klien, alur persetujuan adalah untuk dirinya sendiri dan aplikasi tingkat menengah. Pada platform identitas Microsoft, ini dilakukan menggunakan .default lingkup. Cakupan .default adalah cakupan khusus yang digunakan untuk meminta persetujuan untuk mengakses semua cakupan yang izinnya dimiliki aplikasi. Ini berguna ketika aplikasi perlu mengakses beberapa sumber daya, tetapi pengguna hanya boleh dimintai persetujuan sekali.
Saat memicu layar persetujuan menggunakan aplikasi klien yang diketahui dan .default, layar persetujuan menunjukkan izin untuk klien ke API tingkat menengah, dan juga meminta izin apa pun yang diperlukan oleh API tingkat menengah. Pengguna memberikan persetujuan untuk kedua aplikasi, dan kemudian aliran OBO berfungsi.
Layanan sumber daya (API) yang diidentifikasi dalam permintaan harus merupakan API tempat aplikasi klien meminta token akses sebagai hasil dari masuknya pengguna. Misalnya, scope=openid https://middle-tier-api.example.com/.default (untuk meminta token akses untuk API tingkat menengah), atau scope=openid offline_access .default (saat sumber daya tidak diidentifikasi, token tersebut default ke Microsoft Graph).
Terlepas dari API mana yang diidentifikasi dalam permintaan otorisasi, permintaan persetujuan dikombinasikan dengan semua izin yang diperlukan yang dikonfigurasi untuk aplikasi klien. Semua izin yang diperlukan yang dikonfigurasi untuk setiap API tingkat menengah yang tercantum dalam daftar izin yang diperlukan klien, yang mengidentifikasi klien sebagai aplikasi klien yang diketahui, juga disertakan.
Aplikasi yang telah diotorisasi
Sumber daya dapat menunjukkan bahwa aplikasi yang diberikan selalu memiliki izin untuk menerima cakupan tertentu. Ini berguna untuk membuat koneksi antara klien front-end dan sumber daya back-end lebih mulus. Sumber daya dapat mendeklarasikan beberapa aplikasi yang telah diotorisasi (preAuthorizedApplications) dalam manifesnya. Aplikasi tersebut dapat meminta izin ini dalam alur OBO dan menerimanya tanpa pengguna memberikan persetujuan.
Persetujuan admin
Admin penyewa dapat menjamin bahwa aplikasi memiliki izin untuk memanggil API yang diperlukan dengan memberikan persetujuan admin untuk aplikasi tingkat menengah. Untuk melakukan ini, admin dapat menemukan aplikasi tingkat menengah di penyewa mereka, membuka halaman izin yang diperlukan, dan memilih untuk memberikan izin untuk aplikasi. Untuk mempelajari selengkapnya tentang persetujuan admin, lihat dokumentasi persetujuan dan izin.
Penggunaan satu aplikasi
Dalam beberapa skenario, Anda hanya dapat memiliki satu pasangan klien tingkat menengah dan ujung depan. Dalam skenario ini, Anda dapat merasa lebih mudah untuk menjadikan ini satu aplikasi, meniadakan kebutuhan akan aplikasi tingkat menengah sama sekali. Untuk mengautentikasi antara front-end dan web API, Anda dapat menggunakan cookie, id_token, atau token akses yang diminta untuk aplikasi itu sendiri. Kemudian, minta persetujuan dari aplikasi tunggal ini ke sumber daya back-end.
Lihat juga
Pelajari lebih lanjut tentang protokol OAuth 2.0 dan cara lain untuk melakukan layanan ke layanan auth menggunakan kredensial klien.