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 Bersyarat 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 autentikasi) memungkinkan Anda menerapkan kebijakan terperinci ke data dan tindakan sensitif, bukan hanya pada tingkat aplikasi. Anda dapat memperbaiki kebijakan Zero Trust untuk akses hak istimewa paling rendah, sambil meminimalkan gangguan pengguna dan agar pengguna tetap lebih produktif dan sumber daya Anda menjadi lebih aman. Saat ini, digunakan oleh aplikasi yang 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 step-up dari dalam aplikasi dan layanan Anda, gunakan fitur konteks autentikasi mesin Akses Bersyarat Microsoft Entra. Pengembang sekarang memiliki kemampuan untuk menuntut autentikasi yang lebih canggih dan kuat, secara selektif, seperti MFA dari pengguna akhir mereka dari dalam aplikasi mereka. Fitur ini membantu pengembang membangun pengalaman pengguna yang lebih mulus di sebagian besar bagian aplikasi mereka, sementara akses ke operasi dan data yang lebih aman tetap dilindungi oleh kontrol autentikasi yang lebih kuat.

Pernyataan masalah

Administrator TI dan regulator sering berjuang untuk menyeimbangkan upaya meminta pengguna dengan faktor autentikasi tambahan dan mencapai keamanan yang memadai serta kepatuhan terhadap kebijakan 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 koleksi 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 dengan 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 referensi Konteks Autentikasi Akses Bersyaratnilai dengan Permintaan Klaim untuk memberi aplikasi cara untuk memicu dan memenuhi kebijakan.

Kedua, Conditional Access 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 membuat pengguna masuk. Aplikasi yang mengautentikasi sebagai dirinya sendiri tidak didukung. Gunakan panduan Alur autentikasi dan skenario aplikasi untuk mempelajari tentang jenis aplikasi autentikasi dan alur 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 tenant Anda. Untuk informasi selengkapnya, lihat Mengonfigurasi konteks autentikasi.

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

• C1 - Memerlukan autentikasi yang kuat
• C2 – Memerlukan perangkat yang patuh
• C3 – Wajibkan 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 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 tenant, id konteks autentikasi yang digunakan bisa berbeda, dan dalam beberapa kasus tidak tersedia sama sekali.

Kedua: Pengembang aplikasi yang berencana menggunakan konteks autentikasi Akses Bersyarat disarankan untuk terlebih dahulu memberikan sarana bagi admin aplikasi atau admin TI untuk memetakan tindakan sensitif yang berpotensi ke ID konteks autentikasi. Langkah-langkahnya kira-kira sebagai berikut:

1. Aksi identitas dalam kode yang dapat disediakan untuk memetakan terhadap Id konteks autentikasi.
2. Buat 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 ini secara umum meliputi

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

Ketiga: aplikasi Anda, dan untuk contoh ini, kami menganggap itu adalah API web, kemudian harus mengevaluasi panggilan terhadap pemetaan yang disimpan dan karenanya memunculkan claim challenge untuk aplikasi kliennya. Untuk mempersiapkan tindakan ini, langkah-langkah berikut harus dilakukan:

1. Dalam operasi dalam konteks autentikasi yang sensitif dan dilindungi, 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 berikut ini 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 step-up authentication. 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, akan muncul 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, tangani klaim challenge dan alihkan pengguna kembali ke Microsoft Entra ID untuk evaluasi kebijakan lebih lanjut. Cuplikan kode berikut ini 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 claims diberikan, alihkan pengguna kembali ke Microsoft Entra ID 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 ketika tidak semua klien API 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 Auth Context secara permanen di aplikasi Anda. Aplikasi harus membaca dan menerapkan konteks autentikasi menggunakan panggilan MS Graph. Praktik ini sangat penting untuk aplikasi multitenant. 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 Bersyarat. Fitur ini berfungsi paling baik ketika bagian dari aplikasi mengharuskan pengguna untuk memenuhi persyaratan autentikasi yang lebih tinggi.

Sampel kode

• Gunakan Conditional Access auth context untuk melakukan step-up authentication untuk operasi dengan hak istimewa tinggi dalam aplikasi web
• Gunakan auth context Conditional Access untuk melakukan autentikasi peningkatan untuk operasi dengan hak istimewa tinggi dalam API web
• Gunakan konteks autentikasi Akses Bersyarat untuk melakukan autentikasi step-up untuk operasi dengan hak istimewa tinggi dalam aplikasi satu halaman React dan API web Express

Perilaku yang diharapkan dari konteks autentikasi [ACRs] dalam Akses Bersyarat

Pemenuhan konteks autentikasi eksplisit dalam permintaan

Klien dapat secara eksplisit meminta token dengan Konteks Autentikasi (ACRS) melalui klaim dalam badan 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 Bersyarat 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 telah diterapkan	Pemeriksaan 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

Pemenuhan konteks autentikasi implisit oleh evaluasi oportunistik

Penyedia sumber daya dapat memilih untuk ikut serta dalam klaim 'acrs' opsional. Akses Bersyarat mencoba menambahkan ACRS ke klaim token secara oportunistik untuk menghindari komunikasi bolak-balik guna memperoleh token baru dari Microsoft Entra ID. Dalam evaluasi tersebut, Conditional Access memeriksa apakah kebijakan yang melindungi tantangan Auth Context 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 login berdasarkan interval

Akses Bersyarat menganggap "frekuensi masuk menurut interval" terpenuhi untuk evaluasi ACRS oportunistik ketika semua instan autentikasi faktor 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 tenant memiliki kebijakan Akses Bersyarat yang melindungi konteks autentikasi

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

Kebijakan A: Wajibkan MFA dari semua pengguna, kecuali pengguna "Ariel", saat meminta acrs "c1". Kebijakan B: Blokir semua pengguna, kecuali pengguna "Jay", saat meminta "c2", atau "c3" acrs.

Flow	ACRS diminta	Kebijakan diterapkan	Kendali terpenuhi	ACRS ditambahkan ke klaim
Ariel meminta token akses	c1	Tidak	Benar 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 mengajukan permintaan token akses (tanpa MFA)	c1	Kebijakan A	Tidak.	Tidak
Jay mengajukan permintaan 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 mengajukan permintaan 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	Yes 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)
• Zero Trust dengan platform identitas Microsoft
• Membangun aplikasi siap Zero Trust dengan platform identitas Microsoft
• Konteksi autentikasi akses bersyarat
• tipe sumber daya authenticationContextClassReference - MS Graph
• Tantangan klaim, permintaan klaim, dan kemampuan klien di platform Identitas Microsoft
• Menggunakan konteks autentikasi dengan Perlindungan Informasi Microsoft Purview dan SharePoint
• Cara menggunakan API dengan Continuous Access Evaluation yang diaktifkan di aplikasi Anda