Panduan pengembang terkait konteks autentikasi Akses Bersyarat

Berlaku untuk: Penyewa tenaga kerja Penyewa eksternal (Lingkaran hijau dengan simbol tanda centang putih yang menunjukkan konten berikut berlaku untuk penyewa eksternal.) (Green circle with a white check mark symbol that indicates the following content applies to external tenants.pelajari selengkapnya)

Akses Bersyar adalah sarana kontrol Zero Trust yang memungkinkan Anda menargetkan kebijakan untuk akses ke semua aplikasi Anda – lama atau baru, privat, atau publik, lokal, atau multicloud. Dengan konteks autentikasi Akses Bersyarat, Anda dapat menerapkan kebijakan yang berbeda dalam aplikasi tersebut.

Konteks autentikasi Akses Bersyarat (konteks otoriasaso) memungkinkan Anda menerapkan kebijakan terperinci ke data dan tindakan sensitif, bukan hanya pada tingkat aplikasi. Anda dapat memperbaiki kebijakan Zero Trust untuk akses yang paling tidak istimewa, sambil meminimalkan gangguan pengguna dan agar pengguna tetap lebih produktif dan sumber daya Anda menjadi lebih aman. Saat ini, aplikasi ini digunakan oleh aplikasi menggunakan OpenId Connect untuk autentikasi yang dikembangkan oleh perusahaan Anda untuk melindungi sumber daya sensitif, seperti transaksi bernilai tinggi atau melihat data pribadi karyawan.

Untuk memicu autentikasi peningkatan dari dalam aplikasi dan layanan Anda, gunakan fitur konteks autentikasi mesin Microsoft Entra Conditional Access. Pengembang sekarang memiliki kemampuan untuk menuntut autentikasi yang lebih kuat, secara selektif, seperti MFA dari pengguna akhir mereka dari dalam aplikasi mereka. Fitur ini membantu pengembang membangun pengalaman pengguna yang lebih mulus untuk sebagian besar bagian aplikasi mereka, sementara akses ke operasi dan data yang lebih aman tetap berada di belakang kontrol autentikasi yang lebih kuat.

Pernyataan masalah

Administrator TI dan regulator sering berjuang untuk menyeimbangkan permintaan pengguna dengan faktor tambahan autentikasidan mencapai kepatuhan keamanan dan kebijakan yang memadai untuk aplikasi. Ini bisa menjadi pilihan antara kebijakan kuat yang memengaruhi produktivitas pengguna atau kebijakan yang tidak cukup kuat untuk sumber daya sensitif.

Jadi, bagaimana jika aplikasi dapat mencampur keduanya? Berfungsi dengan tingkat keamanan yang lebih rendah dan lebih sedikit notifikasi untuk sebagian besar skenario. Kemudian secara kondisional meningkatkan persyaratan keamanan ketika data yang lebih sensitif diakses?

Skenario umum

Misalnya, saat pengguna mungkin masuk ke SharePoint menggunakan autentikasi multifaktor, mengakses kumpulan situs di SharePoint yang berisi dokumen sensitif dapat memerlukan perangkat yang sesuai dan hanya dapat diakses dari rentang IP tepercaya.

Prasyarat

Pertama, aplikasi Anda harus diintegrasikan dengan platform identitas Microsoft menggunakan protokol OpenID Connect/ OAuth 2.0 untuk autentikasi dan otorisasi. Sebaiknya gunakan pustaka autentikasi platform identitas Microsoft untuk mengintegrasikan dan mengamankan aplikasi Anda dengan ID Microsoft Entra. dokumentasi platform identitas Microsoft adalah tempat yang baik untuk mulai mempelajari cara mengintegrasikan aplikasi Anda dengan platform identitas Microsoft. Dukungan fitur Konteks Autentikasi Akses Bersyarat dibangun di atas ekstensi protokol yang disediakan oleh protokol OpenID Connect standar industri. Pengembang menggunakan nilaireferensi Konteks Autentikasi Akses Bersyarat dengan Permintaan Klaim untuk memberi aplikasi cara untuk memicu dan memenuhi kebijakan.

Kedua, Akses Bersyarat memerlukan lisensi Microsoft Entra ID P1. Informasi selengkapnya tentang lisensi dapat ditemukan di halaman harga Microsoft Entra.

Ketiga, hari ini hanya tersedia untuk aplikasi yang memasukkan pengguna. Aplikasi yang mengautentikasi sebagai dirinya sendiri tidak didukung. Gunakan alur Autentikasi dan panduan skenario aplikasi untuk mempelajari tentang jenis dan alur aplikasi autentikasi yang didukung di platform identitas Microsoft.

Langkah-langkah integrasi

Anda dapat mulai mengintegrasikan fitur ini di aplikasi Anda setelah terintegrasi menggunakan protokol autentikasi yang didukung dan terdaftar di penyewa Microsoft Entra yang memiliki fitur Akses Bersyarat yang tersedia.

Catatan

Panduan mendetail tentang fitur ini juga tersedia sebagai sesi yang direkam di Gunakan Konteks Autentikasi Akses Bersyarat di aplikasi Anda untuk autentikasi step-up.

Pertama, nyatakan dan sediakan konteks autentikasi di penyewa Anda. Untuk informasi selengkapnya, lihat Mengonfigurasi konteks autentikasi.

Nilai C1-C99 tersedia untuk digunakan sebagai ID Konteks Autentikasi dalam penyewa. Contoh konteks autentikasi mungkin:

• C1 - Memerlukan autentikasi yang kuat
• C2 - Memerlukan perangkat yang sesuai
• C3 - Memerlukan lokasi tepercaya

Untuk menggunakan Konteks Autentikasi Akses Bersyarat, ubah atau buat kebijakan Akses Bersyarat Anda. Contoh kebijakan dapat berupa:

• Semua pengguna yang masuk ke aplikasi web ini harus berhasil menyelesaikan 2FA untuk id konteks autentikasi C1.
• Semua pengguna yang masuk ke aplikasi web ini harus berhasil menyelesaikan 2FA dan juga mengakses aplikasi dari rentang alamat IP yang ditentukan untuk ID konteks autentikasi C3.

Catatan

Nilai konteks autentikasi Akses Bersyarat dideklarasikan dan dikelola secara terpisah dari aplikasi. Tidak disarankan bagi aplikasi untuk sangat tergantung pada id konteks autentikasi. Administrator TI biasanya membuat kebijakan Akses Bersyarat karena mereka memiliki pemahaman yang lebih baik tentang sumber daya yang tersedia. Demikian pula, jika aplikasi digunakan di beberapa penyewa, id konteks autentikasi yang digunakan bisa berbeda, dan dalam beberapa kasus tidak tersedia sama sekali.

Kedua:Pengembang aplikasi yang berencana menggunakan konteks auth Akses Bersyarat disarankan untuk terlebih dahulu menyediakan admin aplikasi atau admin TI untuk memetakan potensi tindakan sensitif untuk ID konteks autentikasi. Langkah-langkahnya kira-kira menjadi:

1. Tindakan identitas dalam kode yang dapat disediakan untuk memetakan terhadap Id konteks autentikasi.
2. Membangun layar di portal admin aplikasi (atau fungsionalitas yang setara) yang dapat digunakan admin TI untuk memetakan tindakan sensitif terhadap ID konteks autentikasi yang tersedia.
3. Lihat sampel kode, Gunakan Konteks Autentikasi Akses Kondisional untuk melakukan autentikasi peningkatan langkah sebagai contoh.

Langkah-langkah ini adalah perubahan yang perlu Anda lakukan di basis kode Anda. Langkah-langkah yang terdiri secara luas dari

• Mengkueri MS Graph untuk mencantumkan semua Konteks Autentikasi yang tersedia.
• Izinkan admin TI untuk memilih operasi sensitif/istimewa tinggi dan menetapkannya terhadap Konteks Autentikasi yang tersedia menggunakan kebijakan Akses Bersyarkat.
• Menyimpan informasi pemetaan ini di database/toko lokal Anda.

Ketiga: aplikasi Anda, dan untuk contoh ini, kami menganggap itu adalah API web, maka perlu mengevaluasi panggilan terhadap pemetakan yang disimpan dan karenanya menimbulkan tantangan klaim untuk aplikasi kliennya. Untuk mempersiapkan tindakan ini, langkah-langkah berikut harus dilakukan:

1. Dalam operasi konteks autentikasi dan dilindungi oleh sensitif, evaluasi nilai dalam klaim acrs terhadap pemetaan ID Konteks Autentikasi yang disimpan sebelumnya dan ajukan Tantangan Klaim sebagaimana disediakan dalam cuplikan kode berikut.

2. Diagram berikut menunjukkan interaksi antara pengguna, aplikasi klien, dan API web.

   

   Cuplikan kode yang diikuti berasal dari sampel kode, Gunakan konteks autentikasi Akses Bersyarat untuk melakukan autentikasi peningkatan. Metode pertama, CheckForRequiredAuthContext() dalam API

   • Memeriksa apakah tindakan aplikasi yang dipanggil memerlukan autentikasi peningkatan. Ini dilakukan dengan memeriksa basis datanya untuk pemetaan tersimpan untuk metode ini
   • Jika tindakan ini memang membutuhkan konteks auth yang ditingkatan, ini memeriksa klaim acrs untuk ID Konteks Autentikasi yang ada dan cocok.
   • Jika ID Konteks Autentikasi yang cocok tidak ditemukan, ID tersebut akan menimbulkan tantangan klaim.

   public void CheckForRequiredAuthContext(string method)
   {
       string authType = _commonDBContext.AuthContext.FirstOrDefault(x => x.Operation == method
                   && x.TenantId == _configuration["AzureAD:TenantId"])?.AuthContextId;
   
       if (!string.IsNullOrEmpty(authType))
       {
           HttpContext context = this.HttpContext;
           string authenticationContextClassReferencesClaim = "acrs";
   
           if (context == null || context.User == null || context.User.Claims == null
               || !context.User.Claims.Any())
           {
               throw new ArgumentNullException("No Usercontext is available to pick claims from");
           }
   
           Claim acrsClaim = context.User.FindAll(authenticationContextClassReferencesClaim).FirstOrDefault(x
               => x.Value == authType);
   
           if (acrsClaim == null || acrsClaim.Value != authType)
           {
               if (IsClientCapableofClaimsChallenge(context))
               {
                   string clientId = _configuration.GetSection("AzureAd").GetSection("ClientId").Value;
                   var base64str = Convert.ToBase64String(Encoding.UTF8.GetBytes("{\"access_token\":{\"acrs\":{\"essential\":true,\"value\":\"" + authType + "\"}}}"));
   
                   context.Response.Headers.Append("WWW-Authenticate", $"Bearer realm=\"\", authorization_uri=\"https://login.microsoftonline.com/common/oauth2/authorize\", client_id=\"" + clientId + "\", error=\"insufficient_claims\", claims=\"" + base64str + "\", cc_type=\"authcontext\"");
                   context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
                   string message = string.Format(CultureInfo.InvariantCulture, "The presented access tokens had insufficient claims. Please request for claims requested in the WWW-Authentication header and try again.");
                   context.Response.WriteAsync(message);
                   context.Response.CompleteAsync();
                   throw new UnauthorizedAccessException(message);
               }
               else
               {
                   throw new UnauthorizedAccessException("The caller does not meet the authentication  bar to carry our this operation. The service cannot allow this operation");
               }
           }
       }
   }
   

   Catatan

   Format tantangan klaim dijelaskan dalam artikel, Tantangan Klaim dalam platform identitas Microsoft.

3. Dalam aplikasi klien, Cegat tantangan klaim dan alihkan pengguna kembali ke ID Microsoft Entra untuk evaluasi kebijakan lebih lanjut. Cuplikan kode yang diikuti berasal dari sampel kode, Gunakan konteks autentikasi Akses Bersyarat untuk melakukan autentikasi peningkatan.

   internal static string ExtractHeaderValues(WebApiMsalUiRequiredException response)
   {
       if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized && response.Headers.WwwAuthenticate.Any())
       {
           AuthenticationHeaderValue bearer = response.Headers.WwwAuthenticate.First(v => v.Scheme == "Bearer");
           IEnumerable<string> parameters = bearer.Parameter.Split(',').Select(v => v.Trim()).ToList();
           var errorValue = GetParameterValue(parameters, "error");
   
           try
           {
               // read the header and checks if it contains error with insufficient_claims value.
               if (null != errorValue && "insufficient_claims" == errorValue)
               {
                   var claimChallengeParameter = GetParameterValue(parameters, "claims");
                   if (null != claimChallengeParameter)
                   {
                       var claimChallenge = ConvertBase64String(claimChallengeParameter);
   
                       return claimChallenge;
                   }
               }
           }
           catch (Exception ex)
           {
               throw ex;
           }
       }
       return null;
   }
   

   Tangani pengecualian dalam panggilan ke Web API, jika tantangan klaim disajikan, alihkan pengguna kembali ke ID Microsoft Entra untuk pemrosesan lebih lanjut.

   try
   {
       // Call the API
       await _todoListService.AddAsync(todo);
   }
   catch (WebApiMsalUiRequiredException hex)
   {
       // Challenges the user if exception is thrown from Web API.
       try
       {
           var claimChallenge =ExtractHeaderValues(hex);
           _consentHandler.ChallengeUser(new string[] { "user.read" }, claimChallenge);
   
           return new EmptyResult();
       }
       catch (Exception ex)
       {
           _consentHandler.HandleException(ex);
       }
   
       Console.WriteLine(hex.Message);
   }
   return RedirectToAction("Index");
   

4. (Opsional) Deklarasikan kemampuan klien. Kemampuan klien membantu penyedia sumber daya (RP) seperti API Web kami untuk mendeteksi apakah aplikasi klien memahami tantangan klaim dan kemudian dapat menyesuaikan responsnya. Kemampuan ini dapat berguna di mana tidak semua API klien mampu menangani tantangan klaim, dan beberapa API lawas masih mengharapkan respons yang berbeda. Untuk informasi selengkapnya, lihat bagian Kemampuan klien.

Peringatan dan rekomendasi

Jangan mengkodekan nilai Konteks Autentikasi secara permanen di aplikasi Anda. Aplikasi harus membaca dan menerapkan konteks autentikasi menggunakan panggilan MS Graph. Praktik ini sangat penting untuk aplikasi multi-penyewa. Nilai Konteks Auth bervariasi antara tenant Microsoft Entra dan tidak tersedia di edisi Microsoft Entra ID Free. Untuk informasi selengkapnya tentang bagaimana aplikasi harus mengkueri, mengatur, dan menggunakan konteks autentikasi dalam kodenya, lihat sampel kode, Menggunakan konteks autentikasi akses bersyarkat untuk melakukan autentikasi peningkatan.

Jangan gunakan konteks autentikasi di mana aplikasi itu sendiri akan menjadi target kebijakan Akses Bersyar. Fitur ini berfungsi paling baik ketika bagian dari aplikasi mengharuskan pengguna untuk memenuhi bilah autentikasi yang lebih tinggi.

Sampel kode

• Menggunakan konteks autentikasi akses bersyarat untuk melakukan autentikasi peningkatan izin operasi sangat istimewa dalam Aplikasi web
• Menggunakan konteks autentikasi akses bersyarat untuk melakukan autentikasi peningkatan untuk operasi hak sangat istimewa dalam API Web
• Gunakan konteks autentikasi Akses Bersyarah untuk melakukan autentikasi peningkatan untuk operasi hak istimewa tinggi dalam aplikasi satu halaman React dan API web Ekspres

Konteks autentikasi [ACL] dalam perilaku yang diharapkan Akses Bersyar

Kepuasan konteks autentikasi eksplisit dalam permintaan

Klien dapat secara eksplisit meminta token dengan Konteks Autentikasi (ACRS) melalui klaim dalam isi permintaan. Jika ACRS diminta, Akses Bersyarat memungkinkan penerbitan token dengan ACRS yang diminta jika semua tantangan telah diselesaikan.

Perilaku yang diharapkan saat konteks autentikasi tidak dilindungi oleh Akses Bersyar di penyewa

Akses Bersyarat dapat mengeluarkan ACRS dalam klaim token ketika semua kebijakan Akses Bersyarat yang ditetapkan untuk nilai ACRS terpenuhi. Jika tidak ada kebijakan Akses Bersyarat yang ditetapkan ke nilai ACRS, klaim mungkin masih dikeluarkan karena semua persyaratan kebijakan telah terpenuhi.

Tabel ringkasan untuk perilaku yang diharapkan ketika ACRS diminta secara eksplisit

ACRS diminta	Kebijakan diterapkan	Kontrol terpenuhi	ACRS ditambahkan ke klaim
Ya	Tidak.	Ya	Ya
Ya	Ya	Tidak.	Tidak.
Ya	Ya	Ya	Ya
Ya	Tidak ada kebijakan yang dikonfigurasi dengan ACRS	Ya	Ya

Kepuasan konteks autentikasi implisit oleh evaluasi oportunistik

Penyedia sumber daya dapat ikut serta dalam klaim 'acrs' opsional. Akses Bersyariah mencoba menambahkan ACRS ke klaim token secara oportunistik untuk menghindari perjalanan pulang pergi untuk memperoleh token baru ke ID Microsoft Entra. Dalam evaluasi tersebut, Akses Bersyar memeriksa apakah kebijakan yang melindungi tantangan Konteks Autentikasi sudah terpenuhi dan menambahkan ACRS ke klaim token jika demikian.

Catatan

Setiap jenis token harus didaftarkan secara individual (token ID, token akses).

Jika penyedia sumber daya tidak ikut serta dalam klaim 'acrs' opsional, satu-satunya cara untuk mendapatkan ACRS dalam token adalah dengan secara eksplisit memintanya dalam permintaan token. Proses ini tidak akan mendapatkan manfaat dari evaluasi oportunistik, oleh karena itu setiap kali ACRS yang diperlukan tidak ada dalam klaim token, penyedia sumber daya akan menantang klien untuk memperoleh token baru yang menyertakan ACRS tersebut dalam klaim.

Perilaku yang diharapkan dengan konteks autentikasi dan kontrol sesi untuk evaluasi oportunistik ACRS implisit

Frekuensi masuk menurut interval

Akses Bersyarat mempertimbangkan "frekuensi masuk menurut interval" sebagaimana dipenuhi untuk evaluasi ACRS oportunistik ketika semua instans autentikasi autentikasi saat ini berada dalam interval frekuensi masuk. Jika salah satu faktor autentikasi sudah kedaluwarsa, frekuensi masuk berdasarkan interval tidak akan dipenuhi, dan ACRS tidak akan dikeluarkan dalam token secara oportunistik.

Cloud App Security (CAS)

Akses Bersyarat menganggap kontrol sesi CAS sudah dipenuhi untuk evaluasi oportunistik ACRS, ketika sesi CAS dibangun selama permintaan tersebut. Misalnya, ketika permintaan masuk, dan kebijakan Akses Bersyarat apa pun diterapkan yang memberlakukan sesi CAS, serta ada kebijakan Akses Bersyarat lain yang juga memerlukan sesi CAS, karena sesi CAS tersebut akan diberlakukan, hal itu memenuhi kontrol sesi CAS untuk evaluasi oportunistik.

Perilaku yang diharapkan saat penyewa berisi kebijakan Akses Bersyar yang melindungi konteks autentikasi

Tabel di bawah ini menunjukkan semua kasus sudut di mana ACRS ditambahkan ke klaim token dengan evaluasi oportunistik.

Kebijakan A: Memerlukan MFA dari semua pengguna, tidak termasuk pengguna "Ariel", saat meminta akr "c1". Kebijakan B: Blokir semua pengguna, tidak termasuk pengguna "Jay", saat meminta akr "c2", atau "c3".

Flow	ACRS diminta	Kebijakan diterapkan	Kontrol terpenuhi	ACRS ditambahkan ke klaim
Ariel meminta token akses	c1	Tidak	Ya untuk "c1". Tidak untuk "c2" dan "c3"	"c1" (diminta)
Ariel meminta token akses	c2	Kebijakan B	Diblokir oleh kebijakan B	Tidak
Ariel meminta token akses	Tidak	Tidak	Ya untuk "c1". Tidak untuk "c2" dan "c3"	"c1" (ditambahkan secara oportunistik dari kebijakan A)
Jay meminta token akses (tanpa MFA)	c1	Kebijakan A	Tidak.	Tidak
Jay meminta token akses (dengan MFA)	c1	Kebijakan A	Ya	"c1" (diminta), "c2" (ditambahkan secara oportunistik dari kebijakan B), "c3" (ditambahkan secara oportunistik dari kebijakan B)
Jay meminta token akses (tanpa MFA)	c2	Tidak	Ya untuk "c2" dan "c3". Tidak untuk "c1"	"c2" (diminta), "c3" (ditambahkan secara oportunistik dari kebijakan B)
Jay meminta token akses (dengan MFA)	c2	Tidak	Ya untuk "c1", "c2" dan "c3"	"c1" (upaya terbaik dari A), "c2" (diminta), "c3" (ditambahkan secara oportunistik dari kebijakan B)
Jay meminta token akses (dengan MFA)	Tidak	Tidak	Ya untuk "c1", "c2" dan "c3"	"c1", "c2", "c3" semua ditambahkan secara oportunistik
Jay meminta token akses (tanpa MFA)	Tidak	Tidak	Ya untuk "c2" dan "c3". Tidak untuk "c1"	"c2", "c3" semua ditambahkan secara oportunistik

Langkah berikutnya

• Akses Bersyarat Granular untuk data dan tindakan sensitif (Blog)
• Tidak ada kepercayaan dengan platform identitas Microsoft
• Membangun aplikasi siap Zero Trust dengan platform identitas Microsoft
• Konteksi autentikasi akses bersyarat
• Jenis sumber daya authenticationContextClassReference - MS Graph
• Tantangan klaim, permintaan klaim, dan kemampuan klien di platform Identitas Microsoft
• Menggunakan konteks autentikasi dengan Microsoft Purview Information Protection dan SharePoint
• Cara menggunakan API yang diaktifkan Evaluasi Akses Berkelanjutan di aplikasi Anda