Bagikan melalui

Platform identitas Microsoft dan alurBehalf-Of On-Behalf-Of OAuth 2.0

Alur atas nama (OBO) menjelaskan skenario API web menggunakan identitas selain miliknya sendiri untuk memanggil API web lain. Dikenal sebagai 'delegation' dalam OAuth, tujuannya adalah untuk meneruskan identitas dan izin pengguna dalam 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 secara langsung terhadap protokol dalam aplikasi Anda. Jika memungkinkan, kami sarankan Anda menggunakan Microsoft Authentication Libraries (MSAL) yang didukung sebagai gantinya untuk memperoleh token dan memanggil API web aman. Lihat juga aplikasi sampel yang menggunakan MSAL misalnya.

Batasan untuk 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 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 yang mengikuti merupakan alur OBO dan dijelaskan dengan bantuan diagram berikut.

Menampilkan alurBehalf-Of On-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 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 disusupi.
  • Ketidakmampuan untuk memenuhi skenario pengikatan token dan Akses Bersyarat yang memerlukan langkah klaim (misalnya, MFA, Frekuensi Masuk).
  • Ketidaksesuaian dengan kebijakan berbasis perangkat yang dikonfigurasi admin (misalnya, MDM, kebijakan berbasis lokasi).

Ada dua kasus tergantung pada apakah aplikasi klien memilih untuk diamankan oleh rahasia bersama atau sertifikat.

Kasus pertama: Permintaan token akses menggunakan rahasia bersama

Saat menggunakan rahasia bersama, permintaan token akses layanan-ke-layanan berisi parameter berikut:

Pengaturan Tipe 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 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 sebagai gantinya memberikan kredensial di header Otorisasi, per RFC 6749 juga didukung.
assertion Diperlukan Token akses yang dikirim ke API tingkat menengah. Token ini harus memiliki klaim audiens (aud) aplikasi yang 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 dengan spasi untuk permintaan token. Untuk informasi selengkapnya, lihat cakupan.
requested_token_use Diperlukan Menentukan bagaimana permintaan harus diproses. Dalam alur OBO, nilai harus diatur ke on_behalf_of.

Contoh

HTTP POST berikut meminta token akses dan token refresh dengan user.read cakupan untuk https://graph.microsoft.com API web. 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: Permintaan token akses dengan sertifikat

Permintaan token akses layanan ke layanan dengan sertifikat berisi parameter berikut selain parameter dari contoh sebelumnya:

Pengaturan Tipe 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 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 klaim audiens (aud) aplikasi yang 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 alur OBO, nilai harus diatur ke on_behalf_of.
scope Diperlukan Daftar cakupan yang dipisahkan spasi 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 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.

Pengaturan Deskripsi
token_type Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung platform identitas Microsoft adalah Bearer. Untuk informasi selengkapnya 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 penyegar 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 cakupan diminta.

Contoh respons keberhasilan

Contoh berikut menunjukkan respons keberhasilan terhadap permintaan token akses untuk API web https://graph.microsoft.com. 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 titik akhir 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 ambil ketergantungan terhadapnya dalam kode Anda atau berasumsi tentang spesifikasi token yang bukan untuk API yang Anda kendalikan.

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 memunculkan kesalahan ini ke aplikasi klien sehingga aplikasi klien dapat memberikan interaksi pengguna untuk memenuhi kebijakan Akses Bersyarkat.

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\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

Menggunakan token akses untuk mengakses sumber daya 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 yang diperoleh melalui alur 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 On-Behalf-Of 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.

Petunjuk

Saat Anda memanggil layanan web yang dilindungi SAML dari aplikasi web front-end, Anda cukup memanggil API dan memulai alur autentikasi interaktif normal dengan sesi pengguna yang ada. Anda hanya perlu memakai alur OBO saat panggilan antar layanan memerlukan token SAML untuk memberikan konteks pengguna.

Dapatkan token SAML dengan melakukan permintaan OBO menggunakan kunci rahasia bersama

Permintaan layanan ke layanan untuk pernyataan SAML berisi parameter berikut:

Pengaturan Tipe Deskripsi
jenis_izin wajib Jenis permintaan token. Untuk permintaan yang menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer.
pernyataan wajib Nilai token akses yang digunakan dalam permintaan.
ID klien wajib ID aplikasi yang ditetapkan ke layanan panggilan selama pendaftaran dengan ID Microsoft Entra. Untuk menemukan ID aplikasi di pusat admin Microsoft Entra, telusuripendaftaran Aplikasi Id >Entralalu pilih nama aplikasi.
client_secret (kunci rahasia klien) wajib Kunci yang terdaftar untuk layanan panggilan di ID Microsoft Entra. Nilai ini harus dicatat pada saat pendaftaran. Pola autentikasi Dasar sebagai gantinya memberikan kredensial di header Otorisasi, per RFC 6749 juga didukung.
ruang lingkup wajib Daftar cakupan yang dipisahkan spasi 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.
penggunaan_token_yang_diminta wajib Menentukan bagaimana permintaan harus diproses. Dalam aliran On-Behalf-Of, nilainya harus on_behalf_of.
jenis_token_yang_diminta wajib Menentukan jenis 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 dari panggilan OBO: Jika aplikasi target memerlukan nilai dalam , maka nilai harus dikonfigurasi Recipientsebagai URL Balasan nonwildcard pertama dalam konfigurasi aplikasi sumber daya.SubjectConfirmationData 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 nonwildcard pertama digunakan. Untuk informasi selengkapnya, lihat URL Balasan.
  • Node SubjectConfirmationData: Simpul tidak dapat berisi InResponseTo atribut karena bukan bagian dari respons SAML. Aplikasi yang menerima token SAML harus dapat menerima pernyataan SAML tanpa InResponseTo atribut.
  • Izin API: Anda harus menambahkan izin API yang diperlukan pada aplikasi tingkat menengah untuk memungkinkan 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 alur OAuth. Untuk informasi, lihat Mendapatkan persetujuan untuk aplikasi tingkat menengah.

Respons dengan pernyataan SAML

Pengaturan Deskripsi
tipe_token Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung microsoft Entra ID adalah Pembawa. Untuk informasi selengkapnya tentang token pembawa, lihat Kerangka Kerja Otorisasi OAuth 2.0: Penggunaan Token Pembawa (RFC 6750).
ruang lingkup Ruang lingkup akses yang diberikan dalam token.
Kadaluarsa dalam Lamanya waktu token akses valid (dalam detik).
kedaluwarsa pada Waktu ketika token akses kedaluwarsa. Tanggal dinyatakan sebagai jumlah detik dari 1970-01-01T0:0:0Z UTC hingga waktu kedaluwarsa. Nilai ini digunakan untuk menentukan masa pakai token yang di-cache.
Sumber daya URI ID aplikasi dari layanan penerimaan (sumber daya aman).
access_token (token akses) Parameter yang mengembalikan pernyataan SAML.
token penyegaran Token penyegaran. Layanan panggilan dapat menggunakan token ini untuk meminta token akses lain setelah pernyataan SAML saat ini kedaluwarsa.
  • token_type: Pembawa
  • kedaluwarsa_dalam: 3296
  • ext_kedaluwarsa_dalam: 0
  • kedaluwarsa_pada: 1529627844
  • sumber daya: https://api.contoso.com
  • access_token: <pernyataan SAML>
  • jenis_token_dikeluarkan: urn: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 harus mempertimbangkan hal berikut untuk memastikan bahwa alur OBO berhasil:

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 cakupan. 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, lalu alur OBO berfungsi.

Layanan sumber daya (API) yang diidentifikasi dalam permintaan harus berupa API tempat aplikasi klien meminta token akses sebagai akibat 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.

Penting

Meskipun valid untuk digunakan scope=openid https://resource/.default dalam alur persetujuan gabungan yang melibatkan aplikasi klien yang diketahui, Anda tidak boleh menggabungkan dengan cakupan lain yang didelegasikan .default seperti User.Read, , Mail.Readprofile, atau User.ReadWrite.All dalam permintaan yang sama. Ini akan mengakibatkan kesalahan karena AADSTS70011 mewakili izin statis yang telah disetujui .default sebelumnya, sementara yang lain memerlukan persetujuan pengguna dinamis saat runtime.

offline_access terkadang diterima dengan .default untuk mengaktifkan token refresh, tetapi tidak boleh dikombinasikan dengan cakupan tambahan yang didelegasikan. Jika ragu, bagi permintaan token untuk menghindari konflik jenis cakupan.

Aplikasi yang telah diotorisasi

Sumber daya dapat menunjukkan bahwa aplikasi tertentu 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.

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 API web, 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 selengkapnya tentang protokol OAuth 2.0 dan cara lain untuk melakukan autentikasi layanan ke layanan menggunakan kredensial klien.