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. Hal ini terjadi untuk mencegah pengguna mendapatkan izin ke sumber daya yang seharusnya tidak dapat mereka akses.

Artikel ini menjelaskan cara memprogram langsung terhadap protokol 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 contoh aplikasi yang menggunakan MSAL misalnya.

Tip

Coba jalankan permintaan ini di Postman
Coba jalankan permintaan ini dan banyak lagi di Postman - jangan lupa untuk mengganti token dan ID!

Batasan Klien

Jika perwakilan layanan meminta token khusus aplikasi dan mengirimkannya ke API, API tersebut kemudian akan menukar token yang tidak mewakili perwakilan layanan asli. Ini karena alur OBO hanya berfungsi untuk prinsipal pengguna. Sebaliknya, 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/* 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 dapat ditukarkan oleh klien rahasia, bahkan jika klien yang memulai memiliki URL balasan kartubebas 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 dapat memvalidasi tanda tangan token akses yang diteruskan ke dalamnya. Ini akan mengakibatkan kesalahan karena token yang ditandatangani dengan kunci yang dikendalikan oleh klien tidak dapat diterima dengan aman.

Diagram protokol

Asumsikan bahwa pengguna telah diautentikasi pada 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 dan persetujuan pengguna 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.

Memperlihatkan aliran On-Behalf-Of OAuth2.0

  1. Aplikasi klien membuat permintaan ke API A dengan token A (dengan klaim aud API A).
  2. API A mengautentikasi ke titik akhir penerbitan token platform identitas Microsoft dan meminta token untuk mengakses API B.
  3. 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.
  4. Token B diatur oleh API A di header otorisasi permintaan ke API B.
  5. 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 menengah ke pihak lain mana pun. Token akses yang dikeluarkan ke tingkat menengah dimaksudkan untuk digunakan hanya oleh tingkat menengah tersebut.

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 Diperlukan 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 portal Microsoft Azure - Pendaftaran aplikasi ke aplikasi Anda.
client_secret Diperlukan Rahasia klien yang Anda buat untuk aplikasi Anda di portal Microsoft Azure - 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. Seharusnya sebaliknya 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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: Permintaan 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 Diperlukan 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 portal Microsoft Azure - 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. Seharusnya sebaliknya 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 dengan rahasia bersama kecuali bahwa parameter client_secret digantikan oleh dua parameter: 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=625391af-c675-43e5-8e44-edd3e30ceb15
&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. Grafik Microsoft disiapkan untuk menerima token v1.0, sehingga platform identitas Microsoft menghasilkan token akses v1.0 saat klien meminta token untuk Microsoft Graph. Aplikasi lain mungkin menunjukkan bahwa mereka menginginkan token format v2.0, token v1.0-format, atau bahkan format token berpenyabel 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 ditampilkan oleh titik akhir token saat mencoba memperoleh token akses untuk API hilir, jika API hilir memiliki kebijakan Akses Bersyarat (seperti autentikasi multifaktor) yang ditetapkan di dalamnya. Layanan tingkat menengah harus menampilkan kesalahan ini ke aplikasi klien sehingga aplikasi klien dapat memberikan interaksi pengguna untuk memenuhi kebijakan Akses Bersyarat.

{
    "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 'bf8d80f9-9098-4972-b203-500f535113b1'.\r\nTrace ID: b72a68c3-0926-4b8e-bc35-3150069c2800\r\nCorrelation ID: 73d656cf-54b1-4eb2-b429-26d8165a52d7\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"b72a68c3-0926-4b8e-bc35-3150069c2800",
    "correlation_id":"73d656cf-54b1-4eb2-b429-26d8165a52d7",
    "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 di atas 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. Azure Active Directory dapat memberikan pernyataan SAML sebagai tanggapan terhadap alur On-Behalf-Of yang menggunakan layanan web berbasis SAML sebagai sumber daya target.

Ini adalah ekstensi non-standar untuk aliran On-Behalf-Of OAuth 2.0 yang memungkinkan aplikasi berbasis OAuth2 untuk mengakses titik akhir API layanan web yang mengkonsumsi 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 Microsoft Azure AD. Untuk menemukan ID aplikasi di portal Microsoft Azure, pilih Direktori Aktif, pilih direktori, lalu pilih nama aplikasi.
client_secret diperlukan Kunci yang terdaftar untuk layanan panggilan di Microsoft Azure AD. Nilai ini seharusnya dicatat pada saat pendaftaran. Pola autentikasi Dasar melainkan pemberian info masuk di header Otorisasi, per RFC 6749 juga didukung.
scope 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 tokennya ingin Anda terima. 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:, Azure AD memulai 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 aliran Atas Nama, nilai 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.

Responsnya berisi token SAML yang dikodekan dalam UTF8 dan Base64url.

  • SubjectConfirmationData untuk pernyataan SAML yang bersumber dari panggilan OBO: Jika aplikasi target memerlukan nilai Recipient di SubjectConfirmationData, maka nilai tersebut harus dikonfigurasi sebagai URL Balasan non-wildcard pengganti pertama di aplikasi sumber daya konfigurasi. Karena URL Balasan default tidak digunakan untuk menentukan Recipient nilai, Anda mungkin harus menyusun ulang URL Balasan dalam konfigurasi aplikasi untuk memastikan bahwa URL Balasan non-wildcard pertama digunakan. Untuk informasi selengkapnya, lihat URL Balasan.
  • Node SubjectConfirmationData: Node tidak dapat berisi atribut InResponseTo karena bukan bagian dari respons SAML. Aplikasi yang menerima token SAML harus dapat menerima pernyataan SAML tanpa atribut InResponseTo.
  • Izin API: Anda harus menambahkan izin API yang diperlukan pada aplikasi tingkat menengah untuk mengizinkan akses ke aplikasi SAML, sehingga dapat meminta token untuk /.default cakupan aplikasi SAML.
  • Persetujuan: Persetujuan harus diberikan untuk menerima token SAML yang berisi data pengguna pada aliran OAuth. Untuk informasi, lihat Mendapatkan persetujuan untuk aplikasi tingkat menengah di bawah ini.

Tanggapan dengan pernyataan SAML

Parameter Deskripsi
token_type Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung AAD adalah Token pembawa. 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).
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.
sumber daya URI ID aplikasi dari layanan penerimaan (sumber daya aman).
access_token Parameter yang mengembalikan pernyataan SAML.
refresh_token Token refresh. 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>

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 mungkin ingin mempertimbangkan hal berikut untuk memastikan bahwa alur OBO berhasil.

Aplikasi tingkat menengah menambahkan klien ke daftar aplikasi klien yang diketahui (knownClientApplications) dalam manifesnya. Jika prompt persetujuan dipicu oleh klien, alur persetujuan akan ditujukan untuk dirinya sendiri serta aplikasi tingkat menengah. Pada platform identitas Microsoft, ini dilakukan menggunakan 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 dikenal dan .default, layar persetujuan akan menampilkan izin untuk .default 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, defaultnya adalah Microsoft Graph).

Terlepas dari API mana yang diidentifikasi dalam permintaan otorisasi, permintaan persetujuan akan dikombinasikan dengan semua izin yang diperlukan yang dikonfigurasi untuk aplikasi klien. Selain itu, semua izin yang diperlukan yang dikonfigurasi untuk setiap API tingkat menengah yang tercantum dalam daftar izin yang diperlukan klien, yang telah mengidentifikasi klien sebagai aplikasi klien yang diketahui, juga disertakan.

Aplikasi pra-otorisasi

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 pra-otorisasi (preAuthorizedApplications) dalam manifesnya. Aplikasi apa pun tersebut dapat meminta izin ini dalam alur OBO dan menerimanya tanpa pengguna memberikan persetujuan.

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 mungkin hanya memiliki satu pasangan klien tingkat menengah dan front-end. Dalam skenario ini, Anda mungkin merasa lebih mudah untuk membuat ini menjadi aplikasi tunggal, 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.

Langkah berikutnya

Pelajari lebih lanjut tentang protokol OAuth 2.0 dan cara lain untuk melakukan layanan ke layanan auth menggunakan kredensial klien.