Rollover kunci penandatanganan di platform identitas Microsoft

Artikel
10/30/2024

Artikel ini membahas apa yang perlu Anda ketahui tentang kunci publik yang digunakan oleh platform identitas Microsoft untuk menandatangani token keamanan. Penting untuk dicatat bahwa kunci ini bergulir secara berkala dan, dalam keadaan darurat, dapat segera digulirkan. Semua aplikasi yang menggunakan platform identitas Microsoft harus dapat secara terprogram menangani proses rollover kunci. Anda akan memahami cara kerja kunci, cara menilai dampak rollover ke aplikasi Anda. Anda juga akan mempelajari cara memperbarui aplikasi atau membuat proses rollover manual berkala untuk menangani rollover kunci jika perlu.

Ikhtisar kunci penandatanganan di platform identitas Microsoft

Platform identitas Microsoft menggunakan kriptografi kunci publik yang dibangun berdasarkan standar industri, untuk membangun kepercayaan antara platform dan aplikasi yang menggunakannya. Dalam istilah praktis, ini berfungsi dengan cara berikut: Platform identitas Microsoft menggunakan kunci penandatanganan yang terdiri dari pasangan kunci publik dan pribadi. Saat pengguna masuk ke aplikasi yang menggunakan platform identitas Microsoft untuk autentikasi, platform identitas Microsoft membuat token keamanan yang berisi informasi tentang pengguna. Token ini ditandatangani oleh platform identitas Microsoft menggunakan kunci privatnya sebelum dikirim kembali ke aplikasi. Untuk memverifikasi bahwa token adalah valid dan berasal dari platform identitas Microsoft, aplikasi harus memvalidasi tanda tangan token menggunakan kunci publik yang diekspose oleh platform identitas Microsoft yang dimuat dalam dokumen penemuan OpenID Connect penyewa atau dokumen metadata federasi SAML/WS-Fed.

Demi tujuan keamanan, kunci penandatanganan platform identitas Microsoft bergulir secara berkala, dan dalam keadaan darurat dapat segera digulirkan. Tidak ada waktu yang ditetapkan atau dijamin di antara gulungan kunci ini. Aplikasi apa pun yang terintegrasi dengan platform identitas Microsoft harus disiapkan untuk menangani peristiwa rollover kunci tidak peduli seberapa sering hal itu dapat terjadi. Jika aplikasi Anda tidak menangani refresh tiba-tiba, dan mencoba menggunakan kunci kedaluwarsa untuk memverifikasi tanda tangan pada token, aplikasi Anda salah menolak token. Disarankan untuk menggunakan pustaka standar untuk memastikan metadata kunci disegarkan dengan benar, dan selalu diperbarui. Dalam kasus di mana pustaka standar tidak digunakan, pastikan implementasi mengikuti bagian praktik terbaik.

Selalu ada lebih dari satu kunci valid yang tersedia di dokumen penemuan OpenID Connect dan dokumen metadata federasi. Aplikasi Anda harus siap untuk menggunakan salah satu dan semua kunci yang ditentukan dalam dokumen, karena satu kunci mungkin segera digulirkan, kunci yang lain mungkin merupakan penggantinya, dan seterusnya. Jumlah kunci yang tersedia dapat berubah dari waktu ke waktu, berdasarkan arsitektur internal platform identitas Microsoft saat kami mendukung platform baru, cloud baru, atau protokol autentikasi baru. Baik urutan kunci dalam respons JSON maupun urutan di mana kunci tersebut diekspos harus dianggap bermakna bagi aplikasi Anda. Untuk mempelajari selengkapnya tentang struktur data JSON Web Key, Anda dapat mereferensikan RFC7517.

Aplikasi yang hanya mendukung satu kunci penandatanganan, atau aplikasi yang memerlukan pembaruan manual pada kunci penandatanganan, secara inheren kurang aman dan kurang dapat diandalkan. Mereka harus diperbarui untuk menggunakan pustaka standar untuk memastikan bahwa mereka selalu menggunakan kunci penandatanganan terbaru, di antara praktik terbaik lainnya.

Praktik terbaik untuk penembolokan dan validasi metadata kunci

Menemukan kunci menggunakan titik akhir khusus penyewa seperti yang dijelaskan dalam metadata OpenID Connect (OIDC) dan Federasi
Bahkan jika aplikasi Anda disebarkan di beberapa penyewa, disarankan untuk selalu menemukan dan menyimpan kunci secara independen untuk setiap penyewa yang dilayani aplikasi (menggunakan titik akhir khusus penyewa). Kunci yang umum di seluruh penyewa saat ini dapat menjadi berbeda di seluruh penyewa di masa depan.
Gunakan algoritma penembolokan di bawah ini untuk memastikan penembolokan tangguh dan aman

Algoritma penembolokan metadata kunci:

Pustaka standar kami menerapkan penembolokan kunci yang tangguh dan aman. Disarankan untuk menggunakannya untuk menghindari cacat halus dalam implementasi. Untuk implementasi kustom, berikut adalah algoritma kasar:

Pertimbangan umum:

Layanan yang memvalidasi token harus memiliki cache yang mampu menyimpan banyak kunci yang berbeda (10-1000).
Kunci harus di-cache satu per satu, menggunakan ID kunci ("kid" dalam spesifikasi metadata kunci OIDC) sebagai kunci cache.
Waktu hidup kunci dalam cache harus dikonfigurasi hingga 24 jam, dengan refresh terjadi setiap jam. Ini memastikan sistem dapat merespons dengan cepat kunci yang dihapus, tetapi memiliki durasi cache yang cukup untuk tidak terpengaruh oleh masalah dalam mengambil kunci.
Kunci harus disegarkan:
- Setelah memulai proses atau ketika cache kosong
- Secara berkala (disarankan setiap 1 jam) sebagai pekerjaan latar belakang
- Secara dinamis jika token yang diterima ditandatangani dengan kunci yang tidak diketahui (anak atau id tidak dikenal di header)

Prosedur KeyRefresh (Algoritma konseptual dari IdentityModel)

Inisialisasi

Manajer konfigurasi disiapkan dengan alamat tertentu untuk mengambil data konfigurasi dan antarmuka yang diperlukan untuk mengambil dan memvalidasi data ini.
Pemeriksaan Konfigurasi

Sebelum mengambil data baru, sistem terlebih dahulu memeriksa apakah data yang ada masih valid berdasarkan interval refresh yang telah ditentukan sebelumnya.
Pengambilan Data Jika data ketinggalan jaman atau hilang, sistem mengunci untuk memastikan hanya satu utas yang mengambil data baru untuk menghindari duplikasi (dan kelelahan utas). Sistem kemudian mencoba mengambil data konfigurasi terbaru dari titik akhir tertentu.
Validasi

Setelah data baru diambil, data divalidasi untuk memastikan data memenuhi standar yang diperlukan dan tidak rusak. Metadata hanya diterima ketika permintaan masuk berhasil divalidasi dengan kunci baru.
Penanganan Kesalahan

Jika terjadi kesalahan selama pengambilan data, kesalahan tersebut dicatat. Sistem terus beroperasi dengan konfigurasi baik terakhir yang diketahui jika data baru tidak dapat diambil
Pembaruan Otomatis Sistem secara berkala memeriksa dan memperbarui data konfigurasi secara otomatis berdasarkan interval refresh (merekomendasikan 12 jam dengan jitter plus atau minus 1 jam). Ini juga dapat meminta pembaruan secara manual jika diperlukan, memastikan bahwa data selalu terkini.
Validasi token dengan kunci baru Jika token tiba dengan kunci penandatanganan yang belum diketahui dari konfigurasi, sistem mencoba mengambil konfigurasi dengan panggilan sinkronisasi di jalur panas untuk menangani kunci baru dalam metadata di luar pembaruan reguler yang diharapkan (tetapi tidak lebih sering dari 5 menit)

Pendekatan ini memastikan bahwa sistem selalu menggunakan data konfigurasi terbaru dan valid, sambil menangani kesalahan dengan baik dan menghindari operasi redundan.

Implementasi .NET dari algoritma ini tersedia dari BaseConfigurationManager. Hal ini dapat berubah berdasarkan ketahanan dan evaluasi keamanan. Lihat juga penjelasan di sini

Prosedur KeyRefresh (kode pseudo):

Prosedur ini menggunakan tanda waktu global (lastSuccessfulRefreshTime) untuk mencegah kondisi yang terlalu sering menyegarkan kunci.

OpenID Connect (OIDC)

KeyRefresh(issuer)
{
  // Store cache entries and last successful refresh timestamp per distinct 'issuer'
 
  if (LastSuccessfulRefreshTime is set and more recent than 5 minutes ago) 
    return // without refreshing
 
  // Load keys URI using the tenant-specific OIDC configuration endpoint ('issuer' is the input parameter)
  oidcConfiguration = download JSON from "{issuer}/.well-known/openid-configuration"
 
  // Load list of keys from keys URI
  keyList = download JSON from jwks_uri property of oidcConfiguration
 
  foreach (key in keyList) 
  {
    cache entry = lookup in cache by kid property of key
    if (cache entry found) 
      set expiration of cache entry to now + 24h 
    else 
      add key to cache with expiration set to now + 24h
  }
 
  set LastSuccessfulRefreshTime to now // current timestamp
}

Prosedur Startup Layanan:

KeyRefresh untuk memperbarui kunci
Luncurkan pekerjaan latar belakang yang memanggil KeyRefresh setiap jam

Prosedur TokenValidation untuk memvalidasi kunci (kode pseudo):

ValidateToken(token)
{
  kid = token.header.kid // get key id from token header
  issuer = token.body.iss // get issuer from 'iss' claim in token body
 
  key = lookup in cache by issuer and kid
  if (key found)
  {
     validate token with key and return
  }
  else // key is not found in the cache
  {
    call KeyRefresh(issuer) // to opportunistically refresh the keys for the issuer
    key = lookup in cache by issuer and kid
    if (key found)
    {
      validate token with key and return
    }
    else // key is not found in the cache even after refresh
    {
      return token validation error
    }
  }
}

Cara menilai apakah aplikasi Anda akan terdampak, dan apa yang harus dilakukan tentang terkait hal tersebut

Bagaimana aplikasi Anda menangani rollover kunci tergantung pada variabel seperti jenis aplikasi atau protokol identitas, dan pustaka apa yang digunakan. Bagian di bawah ini menilai apakah jenis aplikasi yang paling umum terdampak oleh rollover kunci, dan memberikan panduan cara memperbarui aplikasi untuk mendukung rollover otomatis atau memperbarui kunci secara manual.

Aplikasi klien native yang mengakses sumber daya
Aplikasi web/API yang mengakses sumber daya
Aplikasi web/API yang melindungi sumber daya dan dibangun menggunakan Azure App Services
Aplikasi web/API yang melindungi sumber daya menggunakan ASP.NET OWIN OpenID Connect, WS-Fed, atau WindowsAzureActiveDirectoryBearerAuthentication middleware
Aplikasi web/API yang melindungi sumber daya menggunakan middleware ASP.NET Core OpenID Connect atau JwtBearerAuthentication
Aplikasi web/API yang melindungi sumber daya menggunakan modul Node.js passport-azure-ad
Aplikasi web/API yang melindungi sumber daya dan dibuat dengan Visual Studio 2015 atau versi lebih baru
Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013
API web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013
Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2012
Aplikasi web/API yang melindungi sumber daya menggunakan pustaka lain atau menerapkan protokol yang didukung secara manual

Panduan ini tidak berlaku untuk:

Aplikasi yang ditambahkan dari Galeri Aplikasi Microsoft Entra (termasuk Kustom) memiliki panduan terpisah mengenai kunci penandatanganan. Informasi selengkapnya.
Aplikasi lokal yang diterbitkan melalui proksi aplikasi tidak perlu khawatir tentang kunci penandatanganan.

Aplikasi klien native yang mengakses sumber daya

Aplikasi yang hanya mengakses sumber daya (misalnya, Microsoft Graph, KeyVault, Outlook API, dan API Microsoft lainnya) hanya mendapatkan token dan meneruskannya kepada pemilik sumber daya. Mengingat bahwa mereka tidak melindungi sumber daya apa pun, mereka tidak memeriksa token dan karena itu tidak perlu memastikannya ditandatangani dengan benar.

Aplikasi klien native, baik desktop atau seluler, termasuk dalam kategori ini dan dengan demikian tidak terdampak oleh rollover.

Aplikasi web/API yang mengakses sumber daya

Aplikasi yang hanya mengakses sumber daya (seperti Microsoft Graph, KeyVault, Outlook API, dan API Microsoft lainnya) hanya mendapatkan token dan meneruskannya kepada pemilik sumber daya. Mengingat bahwa mereka tidak melindungi sumber daya apa pun, mereka tidak memeriksa token dan karena itu tidak perlu memastikannya ditandatangani dengan benar.

Aplikasi web dan API web yang menggunakan alur aplikasi saja (kredensial klien/sertifikat klien) untuk meminta token dimasukkan dalam kategori ini, dan dengan demikian tidak terdampak oleh rollover.

Aplikasi web/API yang melindungi sumber daya dan dibangun menggunakan Azure App Services

Fungsionalitas Autentikasi / Otorisasi Azure App Services (EasyAuth) sudah memiliki logika yang diperlukan untuk menangani rollover kunci secara otomatis.

Aplikasi web/API yang melindungi sumber daya menggunakan ASP.NET OWIN OpenID Connect, WS-Fed, atau WindowsAzureActiveDirectoryBearerAuthentication middleware

Jika aplikasi Anda menggunakan ASP.NET OWIN OpenID Connect, WS-Fed atau WindowsAzureActiveDirectoryBearerAuthentication middleware, aplikasi tersebut sudah memiliki logika yang diperlukan untuk menangani rollover kunci secara otomatis.

Anda dapat mengonfirmasi bahwa aplikasi Anda menggunakan salah satu kunci ini dengan mencari salah satu cuplikan berikut dalam file Startup.cs atau Startup.Auth.cs aplikasi Anda.

app.UseOpenIdConnectAuthentication(
    new OpenIdConnectAuthenticationOptions
    {
        // ...
    });

app.UseWsFederationAuthentication(
    new WsFederationAuthenticationOptions
    {
        // ...
    });

app.UseWindowsAzureActiveDirectoryBearerAuthentication(
    new WindowsAzureActiveDirectoryBearerAuthenticationOptions
    {
        // ...
    });

Aplikasi web/API yang melindungi sumber daya menggunakan middleware .NET Core OpenID Connect atau JwtBearerAuthentication

Jika aplikasi Anda menggunakan middleware ASP.NET OWIN OpenID Connect atau JwtBearerAuthentication, aplikasi anda sudah memiliki logika yang diperlukan untuk menangani rollover kunci secara otomatis.

Anda dapat mengonfirmasi bahwa aplikasi Anda menggunakan salah satu kunci ini dengan mencari salah satu cuplikan berikut dalam Startup.cs atau Startup.Auth.cs aplikasi Anda

app.UseOpenIdConnectAuthentication(
     new OpenIdConnectAuthenticationOptions
     {
         // ...
     });

app.UseJwtBearerAuthentication(
    new JwtBearerAuthenticationOptions
    {
     // ...
     });

Aplikasi web/API yang melindungi sumber daya menggunakan modul Node.js `passport-azure-ad`

Jika aplikasi Anda menggunakan modul Node.js passport-ad, aplikasi tersebut sudah memiliki logika yang diperlukan untuk menangani rollover kunci secara otomatis.

Anda dapat mengonfirmasi bahwa aplikasi Anda passport-ad dengan mencari cuplikan berikut di app.js aplikasi Anda

var OIDCStrategy = require('passport-azure-ad').OIDCStrategy;

passport.use(new OIDCStrategy({
    //...
));

Aplikasi web/API yang melindungi sumber daya dan dibuat dengan Visual Studio 2015 atau versi lebih baru

Jika aplikasi Anda dibuat menggunakan templat aplikasi web di Visual Studio 2015 atau versi lebih baru, dan Anda memilih Akun Kantor atau Sekolah dari menu Ubah Autentikasi, aplikasi tersebut sudah memiliki logika yang diperlukan untuk menangani rollover kunci secara otomatis. Logika ini, disematkan di middleware OWIN OpenID Connect, mengambil, dan menyimpan kunci dari dokumen penemuan OpenID Connect dan secara berkala merefreshnya.

Jika Anda menambahkan autentikasi ke solusi Anda secara manual, aplikasi Anda kemungkinan tidak memiliki logika rollover kunci yang diperlukan. Anda dapat menulisnya sendiri, atau mengikuti langkah-langkah dalam aplikasi Web / API menggunakan pustaka lain atau menerapkan protokol yang didukung secara manual.

Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013

Jika aplikasi Anda dibuat menggunakan templat aplikasi web di Visual Studio 2013 atau versi lebih baru, dan Anda memilih Akun Organisasi dari menu Ubah Autentikasi, aplikasi tersebut sudah memiliki logika yang diperlukan untuk menangani rollover kunci secara otomatis. Logika ini menyimpan pengidentifikasi unik organisasi Anda, dan informasi kunci penandatanganan dalam dua tabel database terkait proyek. Anda dapat menemukan untai sambungan untuk database dalam file Web.config proyek.

Jika Anda menambahkan autentikasi ke solusi Anda secara manual, aplikasi Anda kemungkinan tidak memiliki logika rollover kunci yang diperlukan. Anda perlu menulisnya sendiri, atau mengikuti langkah-langkah dalam Aplikasi web / API menggunakan pustaka lain atau menerapkan protokol yang didukung secara manual.

Langkah-langkah berikut membantu Anda memverifikasi bahwa logika berfungsi dengan baik di aplikasi Anda.

Di Visual Studio 2013, buka solusi, lalu pilih pada tab Server Explorer di jendela kanan.
Perluas Sambungan Data, DefaultConnection, lalu Tabel. Temukan tabel IssuingAuthorityKeys, klik kanan tabel, lalu pilih Perlihatkan Data Tabel.
Dalam tabel IssuingAuthorityKeys, minimal akan ada satu baris yang sesuai dengan nilai thumbprint untuk kunci. Hapus semua baris dalam tabel.
Klik kanan tabel Penyewa, lalu pilih Perlihatkan Data Tabel.
Dalam tabel Penyewa, minimal akan ada satu baris yang sesuai dengan pengidentifikasi penyewa direktori unik. Hapus semua baris dalam tabel. Jika Anda tidak menghapus baris di tabel Penyewa dan tabel IssuingAuthorityKeys , Anda mendapatkan kesalahan saat runtime.
Membuat dan menjalankan aplikasi. Setelah masuk ke akun, Anda dapat menghentikan aplikasi.
Kembali ke Penjelajah Server dan lihat nilai dalam tabel IssuingAuthorityKeys dan Penyewa. Anda akan melihat bahwa mereka secara otomatis diisi ulang dengan informasi yang sesuai dari dokumen metadata federasi.

API web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013

Jika Anda membuat aplikasi API web di Visual Studio 2013 menggunakan templat API Web, lalu memilih Akun Organisasi dari menu Ubah Autentikasi, Anda sudah memiliki logika yang diperlukan di aplikasi Anda.

Jika Anda mengonfigurasi autentikasi secara manual, ikuti petunjuk di bawah ini untuk mempelajari cara mengonfigurasi API web Anda untuk memperbarui informasi kuncinya secara otomatis.

Cuplikan kode berikut menunjukkan cara mendapatkan kunci terbaru dari dokumen metadata federasi, lalu menggunakan JWT Token Handler untuk memvalidasi token. Cuplikan kode mengasumsikan bahwa Anda akan menggunakan mekanisme penembolokan Anda sendiri untuk mempertahankan kunci untuk memvalidasi token di masa mendatang dari platform identitas Microsoft, baik itu dalam database, file konfigurasi, atau di tempat lain.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.IdentityModel.Tokens;
using System.Configuration;
using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.IdentityModel.Metadata;
using System.ServiceModel.Security;
using System.Threading;

namespace JWTValidation
{
    public class JWTValidator
    {
        private string MetadataAddress = "[Your Federation Metadata document address goes here]";

        // Validates the JWT Token that's part of the Authorization header in an HTTP request.
        public void ValidateJwtToken(string token)
        {
            JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler()
            {
                // Do not disable for production code
                CertificateValidator = X509CertificateValidator.None
            };

            TokenValidationParameters validationParams = new TokenValidationParameters()
            {
                AllowedAudience = "[Your App ID URI goes here]",
                ValidIssuer = "[The issuer for the token goes here, such as https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/]",
                SigningTokens = GetSigningCertificates(MetadataAddress)

                // Cache the signing tokens by your desired mechanism
            };

            Thread.CurrentPrincipal = tokenHandler.ValidateToken(token, validationParams);
        }

        // Returns a list of certificates from the specified metadata document.
        public List<X509SecurityToken> GetSigningCertificates(string metadataAddress)
        {
            List<X509SecurityToken> tokens = new List<X509SecurityToken>();

            if (metadataAddress == null)
            {
                throw new ArgumentNullException(metadataAddress);
            }

            using (XmlReader metadataReader = XmlReader.Create(metadataAddress))
            {
                MetadataSerializer serializer = new MetadataSerializer()
                {
                    // Do not disable for production code
                    CertificateValidationMode = X509CertificateValidationMode.None
                };

                EntityDescriptor metadata = serializer.ReadMetadata(metadataReader) as EntityDescriptor;

                if (metadata != null)
                {
                    SecurityTokenServiceDescriptor stsd = metadata.RoleDescriptors.OfType<SecurityTokenServiceDescriptor>().First();

                    if (stsd != null)
                    {
                        IEnumerable<X509RawDataKeyIdentifierClause> x509DataClauses = stsd.Keys.Where(key => key.KeyInfo != null && (key.Use == KeyType.Signing || key.Use == KeyType.Unspecified)).
                                                             Select(key => key.KeyInfo.OfType<X509RawDataKeyIdentifierClause>().First());

                        tokens.AddRange(x509DataClauses.Select(token => new X509SecurityToken(new X509Certificate2(token.GetX509RawData()))));
                    }
                    else
                    {
                        throw new InvalidOperationException("There is no RoleDescriptor of type SecurityTokenServiceType in the metadata");
                    }
                }
                else
                {
                    throw new Exception("Invalid Federation Metadata document");
                }
            }
            return tokens;
        }
    }
}

Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2012

Jika aplikasi Anda dibangun di Visual Studio 2012, Anda mungkin menggunakan Identitas dan Alat Akses untuk mengonfigurasi aplikasi Anda. Kemungkinan juga Anda menggunakan Validasi Registri Nama Penerbit (VINR). VINR bertanggung jawab untuk memelihara informasi tentang penyedia identitas tepercaya (platform identitas Microsoft), dan kunci yang digunakan untuk memvalidasi token yang diterbitkan oleh mereka. VINR juga memudahkan untuk memperbarui secara otomatis informasi kunci yang disimpan dalam file Web.config, dengan mengunduh dokumen metadata federasi terbaru yang terkait dengan direktori Anda, memeriksa apakah konfigurasi sudah kedaluwarsa dengan dokumen terbaru, dan memperbarui aplikasi untuk menggunakan kunci baru jika dibutuhkan.

Jika Anda membuat aplikasi menggunakan salah satu sampel kode atau dokumentasi panduan yang disediakan oleh Microsoft, logika rollover kunci sudah disertakan dalam proyek Anda. Anda akan melihat bahwa kode di bawah ini sudah ada di proyek Anda. Jika aplikasi Anda belum memiliki logika ini, ikuti langkah-langkah di bawah ini untuk menambahkannya dan memverifikasi bahwa aplikasi berfungsi dengan benar.

Di Penjelajah Solusi, tambahkan referensi ke rakitan System.IdentityModel untuk proyek yang sesuai.
Buka file Global.asax.cs dan tambahkan yang berikut ini menggunakan direktif:
```
using System.Configuration;
using System.IdentityModel.Tokens;
```

Tambahkan metode berikut ke file Global.asax.cs :

protected void RefreshValidationSettings()
{
 string configPath = AppDomain.CurrentDomain.BaseDirectory + "\\" + "Web.config";
 string metadataAddress =
               ConfigurationManager.AppSettings["ida:FederationMetadataLocation"];
 ValidatingIssuerNameRegistry.WriteToConfig(metadataAddress, configPath);
}

Panggil metode RefreshValidationSettings() dalam metode Application_Start() di Global.asax.cs seperti yang ditunjukkan:
```
protected void Application_Start()
{
 AreaRegistration.RegisterAllAreas();
 ...
 RefreshValidationSettings();
}
```

Setelah Anda mengikuti langkah-langkah ini, Web.config aplikasi Anda akan diperbarui dengan informasi terbaru dari dokumen metadata federasi, termasuk kunci terbaru. Pembaruan ini akan dilakukan setiap kali kumpulan aplikasi Anda mendaur ulang di IIS; secara default IIS diatur untuk mendaur ulang aplikasi setiap 29 jam.

Ikuti langkah-langkah di bawah ini untuk memverifikasi bahwa logika rollover kunci berfungsi.

Setelah Anda memverifikasi bahwa aplikasi Anda menggunakan kode di atas, buka file Web.config dan navigasikan ke< blok issuerNameRegistry>, khususnya mencari beberapa baris berikut:

<issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry">
     <authority name="https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/">
       <keys>
         <add thumbprint="AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00" />
       </keys>

Dalam pengaturan <tambahkan thumbprint="">, ubah thumbprint dengan mengganti karakter apa pun menjadi karakter yang berbeda. Simpan file Web.config.
Buat aplikasi, lalu jalankan. Jika Anda dapat menyelesaikan proses masuk, aplikasi Anda berhasil memperbarui kunci dengan mengunduh informasi yang diperlukan dari dokumen metadata federasi direktori Anda. Jika Anda mengalami masalah saat masuk, pastikan perubahan dalam aplikasi Anda sudah benar dengan membaca artikel Menambahkan Masuk ke Aplikasi Web Anda Menggunakan platform identitas Microsoft, atau mengunduh dan memeriksa sampel kode berikut: Aplikasi Cloud Multipenyewa untuk ID Microsoft Entra.

Aplikasi web/API yang melindungi sumber daya menggunakan pustaka lain atau menerapkan protokol yang didukung secara manual

Jika Anda menggunakan beberapa pustaka lain atau menerapkan protokol yang didukung secara manual, Anda harus meninjau pustaka atau implementasi Anda untuk memastikan bahwa kunci diambil dari dokumen penemuan OpenID Connect atau dokumen metadata federasi. Salah satu cara untuk memeriksanya adalah dengan melakukan pencarian dalam kode Anda atau kode pustaka, untuk setiap panggilan ke dokumen penemuan OpenID atau dokumen metadata federasi.

Jika kunci tersebut disimpan di suatu tempat atau dikodekan secara permanen dalam aplikasi Anda, Anda dapat mengambil kunci secara manual dan memperbaruinya sesuai dengan melakukan rollover manual, sesuai petunjuk di akhir dokumen panduan ini. Sangat disarankan agar Anda meningkatkan aplikasi untuk mendukung rollover otomatis menggunakan pendekatan yang diuraikan dalam artikel ini untuk menghindari gangguan dan biaya di masa mendatang, jika platform identitas Microsoft meningkatkan frekuensi rollover atau melakukan rollover out-of-band darurat.

Cara menguji aplikasi Anda untuk menentukan apakah aplikasi tersebut akan terdampak

Anda dapat memvalidasi apakah aplikasi Anda mendukung rollover kunci otomatis dengan menggunakan skrip PowerShell berikut.

Untuk memeriksa dan memperbarui kunci penandatanganan dengan PowerShell, Anda memerlukan modul MSIdentityTools PowerShell.

Instal modul MSIdentityTools PowerShell:
```
Install-Module -Name MSIdentityTools
```
Masuk menggunakan perintah Connect-MgGraph dengan akun admin untuk menyetujui cakupan yang diperlukan:
```
 Connect-MgGraph -Scope "Application.ReadWrite.All"
```
Dapatkan daftar thumbprint kunci penandatanganan yang tersedia:
```
Get-MsIdSigningKeyThumbprint
```
Pilih salah satu thumbprint kunci dan konfigurasikan ID Microsoft Entra untuk menggunakan kunci tersebut dengan aplikasi Anda (dapatkan ID aplikasi dari pusat admin Microsoft Entra):
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>
```
Uji aplikasi web dengan masuk untuk mendapatkan token baru. Perubahan pembaruan kunci bersifat instan, tetapi pastikan Anda menggunakan sesi browser baru (menggunakan, misalnya, "InPrivate", "Incognito" Chrome, atau mode "Privat" Firefox) untuk memastikan Anda mengeluarkan token baru.
Untuk setiap thumbprint kunci penandatanganan yang ditampilkan, jalankan cmdlet Update-MsIdApplicationSigningKeyThumbprint dan uji proses masuk aplikasi web Anda.
Jika proses masuk aplikasi web Anda benar, artinya aplikasi web mendukung rollover otomatis. Jika tidak, ubah aplikasi Anda untuk mendukung rollover manual. Lihat Membuat proses rollover manual untuk informasi lebih lanjut.

Jalankan skrip berikut untuk kembali ke perilaku normal:

Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default

Cara melakukan rollover manual jika aplikasi Anda tidak mendukung rollover otomatis

Jika aplikasi Anda tidak mendukung rollover otomatis, Anda harus membuat proses yang memantau kunci penandatanganan platform identitas Microsoft secara berkala dan melakukan rollover manual yang sesuai.

Untuk memeriksa dan memperbarui kunci penandatanganan dengan PowerShell, Anda memerlukan MSIdentityTools modul PowerShell.

MSIdentityTools Instal modul PowerShell:
```
Install-Module -Name MSIdentityTools
```
Dapatkan kunci penandatanganan terbaru (dapatkan ID penyewa dari pusat admin Microsoft Entra):
```
Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
```
Bandingkan kunci ini dengan kunci aplikasi Anda yang dikodekan secara permanen atau dikonfigurasi yang akan digunakan saat ini.
Jika kunci terbaru berbeda dari kunci yang digunakan aplikasi Anda, unduh kunci penandatanganan terbaru:
```
Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
```
Perbarui kode atau konfigurasi aplikasi Anda untuk menggunakan kunci baru.
Konfigurasikan ID Microsoft Entra untuk menggunakan kunci terbaru tersebut dengan aplikasi Anda (dapatkan ID aplikasi dari pusat admin Microsoft Entra):
```
Get-MsIdSigningKeyThumbprint -Latest | Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId>
```
Uji aplikasi web dengan masuk untuk mendapatkan token baru. Perubahan pembaruan kunci bersifat instan, tetapi pastikan Anda menggunakan sesi browser baru untuk memastikan Anda mengeluarkan token baru. Misalnya, gunakan "InPrivate", "Incognito" Chrome dari Microsoft Edge, atau mode "Privat" Firefox.

Jika Anda mengalami masalah, kembali ke kunci yang sebelumnya Anda gunakan dan hubungi dukungan Azure:

Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <PreviousKeyThumbprint>

Setelah Anda memperbarui aplikasi untuk mendukung rollover manual, kembalikan ke perilaku normal:
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
```

Bagikan melalui

Rollover kunci penandatanganan di platform identitas Microsoft

Ikhtisar kunci penandatanganan di platform identitas Microsoft

Praktik terbaik untuk penembolokan dan validasi metadata kunci

Algoritma penembolokan metadata kunci:

Pertimbangan umum:

Prosedur KeyRefresh (Algoritma konseptual dari IdentityModel)

Prosedur KeyRefresh (kode pseudo):

Prosedur Startup Layanan:

Prosedur TokenValidation untuk memvalidasi kunci (kode pseudo):

Cara menilai apakah aplikasi Anda akan terdampak, dan apa yang harus dilakukan tentang terkait hal tersebut

Aplikasi klien native yang mengakses sumber daya

Aplikasi web/API yang mengakses sumber daya

Aplikasi web/API yang melindungi sumber daya dan dibangun menggunakan Azure App Services

Aplikasi web/API yang melindungi sumber daya menggunakan ASP.NET OWIN OpenID Connect, WS-Fed, atau WindowsAzureActiveDirectoryBearerAuthentication middleware

Aplikasi web/API yang melindungi sumber daya menggunakan middleware .NET Core OpenID Connect atau JwtBearerAuthentication

Aplikasi web/API yang melindungi sumber daya menggunakan modul Node.js `passport-azure-ad`

Aplikasi web/API yang melindungi sumber daya dan dibuat dengan Visual Studio 2015 atau versi lebih baru

Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013

API web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013

Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2012

Aplikasi web/API yang melindungi sumber daya menggunakan pustaka lain atau menerapkan protokol yang didukung secara manual

Cara menguji aplikasi Anda untuk menentukan apakah aplikasi tersebut akan terdampak

Cara melakukan rollover manual jika aplikasi Anda tidak mendukung rollover otomatis

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Rollover kunci penandatanganan di platform identitas Microsoft

Ikhtisar kunci penandatanganan di platform identitas Microsoft

Praktik terbaik untuk penembolokan dan validasi metadata kunci

Algoritma penembolokan metadata kunci:

Pertimbangan umum:

Prosedur KeyRefresh (Algoritma konseptual dari IdentityModel)

Prosedur KeyRefresh (kode pseudo):

Prosedur Startup Layanan:

Prosedur TokenValidation untuk memvalidasi kunci (kode pseudo):

Cara menilai apakah aplikasi Anda akan terdampak, dan apa yang harus dilakukan tentang terkait hal tersebut

Aplikasi klien native yang mengakses sumber daya

Aplikasi web/API yang mengakses sumber daya

Aplikasi web/API yang melindungi sumber daya dan dibangun menggunakan Azure App Services

Aplikasi web/API yang melindungi sumber daya menggunakan ASP.NET OWIN OpenID Connect, WS-Fed, atau WindowsAzureActiveDirectoryBearerAuthentication middleware

Aplikasi web/API yang melindungi sumber daya menggunakan middleware .NET Core OpenID Connect atau JwtBearerAuthentication

Aplikasi web/API yang melindungi sumber daya menggunakan modul Node.js passport-azure-ad

Aplikasi web/API yang melindungi sumber daya dan dibuat dengan Visual Studio 2015 atau versi lebih baru

Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013

API web yang melindungi sumber daya dan dibuat dengan Visual Studio 2013

Aplikasi web yang melindungi sumber daya dan dibuat dengan Visual Studio 2012

Aplikasi web/API yang melindungi sumber daya menggunakan pustaka lain atau menerapkan protokol yang didukung secara manual

Cara menguji aplikasi Anda untuk menentukan apakah aplikasi tersebut akan terdampak

Cara melakukan rollover manual jika aplikasi Anda tidak mendukung rollover otomatis

Saran dan Komentar

Sumber Daya Tambahan:

Aplikasi web/API yang melindungi sumber daya menggunakan modul Node.js `passport-azure-ad`