Tantangan klaim, permintaan klaim, dan kemampuan klien

Tantangan klaim adalah respons terkirim dari API yang menunjukkan bahwa token akses yang dikirim oleh aplikasi klien memiliki klaim yang tidak mencukupi. Ini bisa terjadi karena token tidak memenuhi kebijakan Akses Bersyar yang ditetapkan untuk API tersebut, atau token akses telah dicabut.

Permintaan klaim dibuat oleh aplikasi klien untuk mengalihkan pengguna kembali ke Penyedia Identitas untuk mengambil token baru dengan klaim yang memenuhi persyaratan lain yang tidak terpenuhi.

Aplikasi yang menggunakan fitur keamanan yang disempurnakan seperti Evaluasi Akses Berkelanjutan (CAE) dan Konteks autentikasi Akses Bersyarat harus disiapkan untuk menangani tantangan klaim.

Aplikasi Anda menerima tantangan klaim dari layanan populer seperti Microsoft Graph hanya jika mendeklarasikan kemampuan kliennya dalam panggilannya ke layanan.

Format header tantangan klaim

Tantangan klaim adalah arahan sebagai header www-authenticate yang dikembalikan oleh API ketika token akses yang disajikan tidak diizinkan, dan token akses baru dengan kemampuan yang tepat dibutuhkan sebagai gantinya. Tantangan klaim terdiri dari beberapa bagian: kode status HTTP respons dan header www-authenticate, yang sendiri memiliki beberapa bagian dan harus berisi arahan klaim.

Berikut contohnya:

HTTP 401; Unauthorized

www-authenticate =Bearer realm="", authorization_uri="https://login.microsoftonline.com/common/oauth2/authorize", error="insufficient_claims", claims="eyJhY2Nlc3NfdG9rZW4iOnsiYWNycyI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlIjoiY3AxIn19fQ=="

Kode Status HTTP: Seharusnya 401 Tidak Sah.

header response www-authenticate berisi:

Parameter	Diperlukan/opsional	Deskripsi
Jenis autentikasi	Wajib	Harus berupa Pembawa.
Realm	Opsional	ID penyewa atau nama domain penyewa (misalnya, microsoft.com) sedang diakses. HARUS berupa untai kosong dalam kasus di mana autentikasi melewati titik akhir umum.
authorization_uri	Wajib	URI authorize titik akhir tempat autentikasi interaktif dapat dilakukan jika perlu. Jika ditentukan dalam realm, informasi penyewa HARUS disertakan dalam authorization_uri. Jika realm adalah string kosong, authorization_uri HARUS bertentangan dengan titik akhir umum.
error	Wajib	Harus berupa "insufficient_claims" ketika tantangan klaim harus dihasilkan.
claims	Diperlukan ketika kesalahan adalah "insufficient_claims".	Untai yang dikuotasi berisi permintaan klaim dasar 64 yang dikodekan. Permintaan klaim harus meminta klaim untuk "access_token" di tingkat atas objek JSON. Nilai (klaim yang diminta) akan tergantung konteks, dan ditentukan nanti dalam dokumen ini. Karena alasan ukuran, aplikasi pihak yang mendasarinya HARUS mengecilkan JSON sebelum pengkodean dasar 64. JSON mentah dari contoh di atas adalah {"access_token":{"acrs":{"essential":true,"value":"cp1"}}}.

Respons 401 dapat berisi lebih dari satu header www-authenticate. Semua bidang dalam tabel sebelumnya harus dimuat dalam header www-authenticate yang sama. Header www-authenticate yang berisi tantangan klaim dapat berisi bidang lain. Bidang di header tidak diurutkan. Menurut RFC 7235, setiap nama parameter hanya boleh terjadi sekali per tantangan skema autentikasi.

Permintaan klaim

Ketika aplikasi menerima tantangan klaim, ini menunjukkan bahwa token akses sebelumnya tidak lagi dianggap valid. Dalam skenario ini, aplikasi harus menghapus token dari cache lokal atau sesi pengguna. Kemudian, pengguna harus mengalihkan pengguna yang masuk kembali ke MICROSOFT Entra ID untuk mengambil token baru dengan menggunakan alur kode otorisasi OAuth 2.0 dengan parameter klaim yang akan memenuhi persyaratan lain yang tidak terpenuhi.

Berikut contohnya:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22acrs%22%3A%7B%22essential%22%3Atrue%2C%22value%22%3A%22c1%22%7D%7D%7D

Tantangan klaim harus diteruskan sebagai bagian dari semua panggilan ke titik akhir Microsoft Entra /authorize hingga token berhasil diambil. Setelah token diambil, token tidak lagi diperlukan.

Untuk mengisi parameter klaim, pengembang harus:

1. Mengodekan untai dasar64 yang diterima sebelumnya.
2. Mengodekan URL string dan menambahkan lagi ke parameter klaim.

Setelah menyelesaikan alur ini, aplikasi menerima token akses yang memiliki klaim lain yang membuktikan bahwa pengguna memenuhi kondisi yang diperlukan.

Kapabilitas klien

Kemampuan klien membantu penyedia sumber daya seperti API Web mendeteksi apakah aplikasi klien panggilan memahami tantangan klaim lalu dapat menyesuaikan responsnya. Kemampuan ini mungkin berguna ketika tidak semua klien API mampu menangani tantangan klaim, dan beberapa versi sebelumnya masih mengharapkan respons yang berbeda.

Beberapa aplikasi populer seperti Microsoft Graph mengirim tantangan klaim hanya jika aplikasi klien panggilan menyatakan mampu menanganinya menggunakan kemampuan klien.

Untuk menghindari lalu lintas atau dampak tambahan terhadap pengalaman pengguna, ID Microsoft Entra tidak mengasumsikan bahwa aplikasi Anda dapat menangani klaim yang ditantang kecuali Anda secara eksplisit ikut serta. Aplikasi tidak akan menerima tantangan klaim (dan tidak akan dapat menggunakan fitur terkait seperti token CAE) kecuali menyatakan siap untuk menanganinya dengan kemampuan "cp1".

Cara mengkomunikasikan kemampuan klien ke ID Microsoft Entra

Contoh parameter klaim berikut menunjukkan bagaimana aplikasi klien mengomunikasikan kemampuannya ke ID Microsoft Entra dalam alur kode otorisasi OAuth 2.0.

Claims: {"access_token":{"xms_cc":{"values":["cp1"]}}}

.NET

Gunakan kode berikut jika Anda menggunakan pustaka MSAL:

_clientApp = PublicClientApplicationBuilder.Create(App.ClientId)
 .WithDefaultRedirectUri()
 .WithAuthority(authority)
 .WithClientCapabilities(new [] {"cp1"})
 .Build();

Mereka yang menggunakan Microsoft.Identity.Web dapat menambahkan kode berikut ke file konfigurasi:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": 'Enter_the_Application_Id_Here' 
    "ClientCapabilities": [ "cp1" ],
    // remaining settings...
},

JavaScript

Mereka yang menggunakan MSAL.js atau MSAL Node dapat menambahkan clientCapabilities properti ke objek konfigurasi. Catatan: opsi ini tersedia untuk aplikasi klien publik dan rahasia.

const msalConfig = {
    auth: {
        clientId: 'Enter_the_Application_Id_Here', 
        clientCapabilities: ["CP1"]
        // remaining settings...
    }
}

const msalInstance = new msal.PublicClientApplication(msalConfig);

Lihat cuplikan berikut untuk melihat contoh permintaan ke ID Microsoft Entra:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22xms_cc%22%3A%7B%22values%22%3A%5B%22cp1%22%5D%7D%7D%7D

Ketika Anda sudah memiliki payload yang ada untuk parameter klaim, maka Anda akan menambahkan ini ke set yang ada.

Misalnya, jika Anda sudah memiliki respons berikut dari operasi konteks autentikasi Akses Kondisi;

{"access_token":{"acrs":{"essential":true,"value":"c25"}}}

Anda akan melakukan prepend kemampuan klien dalam payload klaim yang ada.

{"access_token":{"xms_cc":{"values":["cp1"]},"acrs":{"essential":true,"value":"c25"}}}

Menerima xms_cc anda dalam token akses

Untuk menerima informasi tentang apakah aplikasi klien dapat menangani tantangan klaim, pelaksana API harus meminta xms_cc sebagai klaim opsional dalam manifes aplikasinya.

Klaim xms_cc dengan nilai "cp1" dalam token akses adalah cara otoritatif untuk mengidentifikasi aplikasi klien yang mampu menangani tantangan klaim. xms_cc adalah klaim opsional yang tidak akan selalu dikeluarkan dalam token akses, bahkan jika klien mengirim permintaan klaim dengan "xms_cc". Agar token akses berisi klaim xms_cc, aplikasi sumber daya (yaitu, pelaksana API) harus meminta xms_cc sebagai klaim opsional dalam manifes aplikasinya. Ketika diminta sebagai klaim opsional, xms_cc ditambahkan ke token akses hanya jika aplikasi klien mengirim xms_cc dalam permintaan klaim. Nilai permintaan klaim xms_cc disertakan sebagai nilai klaim xms_cc dalam token akses, jika itu adalah nilai yang diketahui. Satu-satunya nilai yang saat ini diketahui adalah cp1.

Nilai tidak peka huruf besar/kecil dan tidak diurutkan. Jika lebih dari satu nilai ditentukan dalam klaim xms_cc, nilai tersebut akan menjadi kumpulan multi-nilai sebagai nilai klaim xms_cc.

Ambil permintaan berikut sebagai contoh:

{ "access_token": { "xms_cc":{"values":["cp1","foo", "bar"] } }}

Ini menghasilkan klaim cuplikan berikut dalam token akses, jika cp1, foo dan bar adalah kemampuan yang diketahui.

"xms_cc": ["cp1", "foo", "bar"]

Setelah klaim opsional xms_ccdiminta, manifes aplikasi berubah agar terlihat seperti berikut ini:

"optionalClaims":
{
    "accessToken": [
    {
        "additionalProperties": [],
        "essential": false,
        "name": "xms_cc",
        "source": null
    }],
    "idToken": [],
    "saml2Token": []
}

API lalu dapat menyesuaikan respons mereka berdasarkan apakah klien mampu menangani tantangan klaim atau tidak.

.NET

Claim ccClaim = context.User.FindAll(clientCapabilitiesClaim).FirstOrDefault(x => x.Type == "xms_cc");
if (ccClaim != null && ccClaim.Value == "cp1")
{
    // Return formatted claims challenge as this client understands this
}
else
{
    // Throw generic exception
    throw new UnauthorizedAccessException("The caller does not meet the authentication bar to carry our this operation. The service cannot allow this operation");
}

JavaScript

Cuplikan berikut mengilustrasikan middleware Express.js kustom:

const checkIsClientCapableOfClaimsChallenge = (req, res, next) => {
    // req.authInfo contains the decoded access token payload
    if (req.authInfo['xms_cc'] && req.authInfo['xms_cc'].includes('CP1')) {
          // Return formatted claims challenge as this client understands this
    } else {
          return res.status(403).json({ error: 'Client is not capable' });
    }
}

Sampel kode

• Aktifkan aplikasi satu halaman Angular Anda untuk memasukkan pengguna dan memanggil Microsoft Graph
• Aktifkan aplikasi satu halaman React Anda untuk memasukkan pengguna dan memanggil Microsoft Graph
• Mengaktifkan aplikasi web ASP.NET Core Anda untuk memasukkan pengguna dan memanggil Microsoft Graph

Langkah berikutnya

• Platform identitas Microsoft dan alur kode otorisasi OAuth 2.0
• Cara menggunakan API yang diaktifkan Evaluasi Akses Berkelanjutan di aplikasi Anda
• Akses Bersyarat Granular untuk data sensitif dan tindakan