String koneksi di Azure SignalR Service

string koneksi berisi informasi tentang cara menyambungkan ke Azure SignalR Service. Dalam artikel ini, Anda mempelajari dasar-dasar string koneksi dan cara mengonfigurasinya di aplikasi Anda.

Apa itu string koneksi

Saat aplikasi perlu terhubung ke Azure SignalR Service, aplikasi memerlukan informasi berikut:

• Titik akhir HTTP instans Azure SignalR Service
• Cara mengautentikasi dengan titik akhir layanan

String koneksi berisi informasi tersebut.

Seperti apa tampilan string koneksi

string koneksi terdiri dari serangkaian pasangan kunci/nilai yang dipisahkan oleh titik koma (;). String menggunakan tanda sama dengan (=) untuk menyambungkan setiap kunci dan nilainya. Kunci tidak peka huruf besar/kecil.

String koneksi umum mungkin terlihat seperti contoh ini:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

string koneksi berisi:

• Endpoint=https://<resource_name>.service.signalr.net: URL titik akhir sumber daya.
• AccessKey=<access_key>: Kunci untuk mengautentikasi dengan layanan. Saat Anda menentukan kunci akses di string koneksi, Azure SignalR Service SDK menggunakannya untuk menghasilkan token yang divalidasi layanan.
• Version: Versi string koneksi. Nilai defaultnya adalah 1.0.

Tabel berikut mencantumkan semua nama yang valid untuk pasangan kunci/nilai dalam string koneksi.

Menggunakan AccessKey

Layanan ini menggunakan metode autentikasi lokal saat AuthType diatur ke null.

Menggunakan ID Microsoft Entra

Layanan ini menggunakan metode autentikasi Microsoft Entra saat AuthType diatur ke azure, , azure.appatau azure.msi.

Layanan ini menggunakan nilai yang berbeda TokenCredential untuk menghasilkan token Microsoft Entra, tergantung pada parameter yang Anda berikan:

• type=azure

  • Layanan ini menggunakan DefaultAzureCredential:

    Endpoint=xxx;AuthType=azure
    

• type=azure.msi

  • Layanan ini menggunakan identitas terkelola yang ditetapkan pengguna (ManagedIdentityCredential(clientId)) jika string koneksi menggunakan clientId:

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>
    

  • Layanan ini menggunakan identitas terkelola yang ditetapkan sistem (ManagedIdentityCredential()):

    Endpoint=xxx;AuthType=azure.msi;
    

• type=azure.app

  Keduanya clientId dan tenantId diharuskan menggunakan aplikasi Microsoft Entra dengan perwakilan layanan.

  • Layanan ini menggunakan ClientSecretCredential(clientId, tenantId, clientSecret) jika string koneksi menggunakan clientSecret:

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>
    

  • Layanan ini menggunakan ClientCertificateCredential(clientId, tenantId, clientCertPath) jika string koneksi menggunakan clientCertPath:

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
    

Cara mendapatkan string koneksi

Anda dapat menggunakan portal Azure atau Azure CLI untuk mendapatkan string koneksi.

Portal Azure

Buka sumber daya Azure SignalR Service Anda di portal Azure. Tab Kunci memperlihatkan dua string koneksi (primer dan sekunder) dalam format berikut:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

Azure CLI

az signalr key list -g <resource_group> -n <resource_name>

Menyambungkan dengan aplikasi Microsoft Entra

Anda dapat menggunakan aplikasi Microsoft Entra untuk menyambungkan ke instans Azure SignalR Service Anda. Jika aplikasi memiliki izin yang tepat untuk mengakses Azure SignalR Service, aplikasi tidak memerlukan kunci akses.

Untuk menggunakan autentikasi Microsoft Entra, Anda perlu menghapus AccessKey dari string koneksi dan menambahkan AuthType=azure.app. Anda juga perlu menentukan kredensial aplikasi Microsoft Entra Anda, termasuk ID klien, rahasia klien, dan ID penyewa. String koneksi terlihat seperti contoh ini:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.app;ClientId=<client_id>;ClientSecret=<client_secret>;TenantId=<tenant_id>;Version=1.0;

Untuk informasi selengkapnya tentang cara mengautentikasi dengan menggunakan aplikasi Microsoft Entra, lihat Mengotorisasi permintaan ke sumber daya SignalR dengan aplikasi Microsoft Entra.

Mengautentikasi dengan identitas terkelola

Anda dapat menggunakan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna untuk mengautentikasi dengan Azure SignalR Service.

Untuk menggunakan identitas yang ditetapkan sistem, tambahkan AuthType=azure.msi ke string koneksi:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;Version=1.0;

Azure SignalR Service SDK secara otomatis menggunakan identitas server aplikasi Anda.

Untuk menggunakan identitas yang ditetapkan pengguna, sertakan ID klien identitas terkelola dalam string koneksi:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;ClientId=<client_id>;Version=1.0;

Untuk informasi selengkapnya tentang cara mengonfigurasi identitas terkelola, lihat Mengotorisasi permintaan ke sumber daya SignalR dengan identitas terkelola Microsoft Entra.

Menggunakan generator string koneksi

Membangun string koneksi secara manual bisa rumit dan rawan kesalahan. Untuk menghindari kesalahan, Azure SignalR Service menyediakan generator string koneksi untuk membantu Anda menghasilkan string koneksi yang menyertakan identitas Microsoft Entra seperti clientId dan tenantId. Untuk menggunakan alat ini, buka instans Azure SignalR Service Anda di portal Azure dan pilih String koneksi dari menu sebelah kiri.

Pada halaman ini, Anda dapat memilih di antara jenis autentikasi (kunci akses, identitas terkelola, atau aplikasi Microsoft Entra) dan memasukkan informasi seperti titik akhir klien, ID klien, dan rahasia klien. Kemudian string koneksi dibuat secara otomatis. Anda dapat menyalinnya dan menggunakannya di aplikasi Anda.

Untuk informasi selengkapnya tentang bagaimana token akses dihasilkan dan divalidasi, lihat bagian Mengautentikasi melalui token Microsoft Entra di referensi REST API bidang data Azure SignalR Service.

Menyediakan titik akhir klien dan server

string koneksi berisi titik akhir HTTP untuk server aplikasi agar tersambung ke Azure SignalR Service. Server mengembalikan titik akhir HTTP ke klien dalam respons negosiasi, sehingga klien dapat terhubung ke layanan.

Di beberapa aplikasi, mungkin ada komponen tambahan di depan Azure SignalR Service. Semua koneksi klien harus melalui komponen tersebut terlebih dahulu. Misalnya, Azure Application Gateway adalah layanan umum yang menyediakan keamanan jaringan tambahan.

Dalam kasus seperti itu, klien perlu terhubung ke titik akhir yang berbeda dari Azure SignalR Service. Alih-alih mengganti titik akhir secara manual di sisi klien, Anda dapat menambahkan ClientEndpoint ke string koneksi:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ClientEndpoint=https://<url_to_app_gateway>;Version=1.0;

Server aplikasi mengembalikan respons terhadap permintaan negosiasi klien. Respons berisi URL titik akhir yang benar untuk disambungkan klien. Untuk informasi selengkapnya tentang koneksi klien, lihat Internal Azure SignalR Service.

Demikian pula, jika server mencoba membuat koneksi server atau memanggil REST API ke layanan, Azure SignalR Service mungkin juga berada di belakang layanan lain seperti Azure Application Gateway. Dalam hal ini, Anda dapat menggunakan ServerEndpoint untuk menentukan titik akhir aktual untuk koneksi server dan REST API:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ServerEndpoint=https://<url_to_app_gateway>;Version=1.0;

Mengonfigurasi string koneksi di aplikasi Anda

String koneksi mentah muncul dalam artikel ini hanya untuk tujuan demonstrasi. Di lingkungan produksi, selalu lindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman dan mengamankan string koneksi Anda menggunakan ID Microsoft Entra dan mengotorisasi akses dengan ID Microsoft Entra.

Ada dua cara untuk mengonfigurasi string koneksi di aplikasi Anda.

Anda dapat mengatur string koneksi saat memanggil AddAzureSignalR() API:

services.AddSignalR().AddAzureSignalR("<connection_string>");

Atau Anda dapat memanggil AddAzureSignalR() tanpa argumen apa pun. SDK layanan mengembalikan string koneksi dari konfigurasi bernama Azure:SignalR:ConnectionString di penyedia konfigurasi Anda.

Di lingkungan pengembangan lokal, konfigurasi disimpan dalam file (appsettings.json atau secrets.json) atau dalam variabel lingkungan. Anda dapat menggunakan salah satu cara berikut untuk mengonfigurasi string koneksi:

• Gunakan manajer rahasia .NET (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>").
• Atur variabel lingkungan bernama Azure__SignalR__ConnectionString ke string koneksi. Titik dua perlu diganti dengan garis bawah ganda di penyedia konfigurasi variabel lingkungan.

Di lingkungan produksi, Anda dapat menggunakan layanan Azure lainnya untuk mengelola konfigurasi dan rahasia, seperti Azure Key Vault dan App Configuration. Lihat dokumentasi mereka untuk mempelajari cara menyiapkan penyedia konfigurasi untuk layanan tersebut.

Mengonfigurasi beberapa string koneksi

Azure SignalR Service memungkinkan server untuk terhubung ke beberapa titik akhir layanan secara bersamaan, sehingga dapat menangani lebih banyak koneksi yang berada di luar batas instans layanan. Saat satu instans layanan tidak berfungsi, Anda dapat menggunakan instans layanan lain sebagai cadangan. Untuk informasi selengkapnya tentang cara menggunakan beberapa instans, lihat Menskalakan SignalR Service dengan beberapa instans.

Ada dua cara untuk mengonfigurasi beberapa instans:

• Melalui kode:

  services.AddSignalR().AddAzureSignalR(options =>
      {
          options.Endpoints = new ServiceEndpoint[]
          {
              new ServiceEndpoint("<connection_string_1>", name: "name_a"),
              new ServiceEndpoint("<connection_string_2>", name: "name_b", type: EndpointType.Primary),
              new ServiceEndpoint("<connection_string_3>", name: "name_c", type: EndpointType.Secondary),
          };
      });
  

  Anda dapat menetapkan nama dan jenis ke setiap titik akhir layanan sehingga Anda dapat membedakannya nanti.

• Melalui konfigurasi:

  Anda dapat menggunakan penyedia konfigurasi yang didukung (misalnya, manajer rahasia, variabel lingkungan, atau brankas kunci) untuk menyimpan string koneksi. Berikut adalah contoh yang menggunakan manajer rahasia:

  dotnet user-secrets set Azure:SignalR:ConnectionString:name_a <connection_string_1>
  dotnet user-secrets set Azure:SignalR:ConnectionString:name_b:primary <connection_string_2>
  dotnet user-secrets set Azure:SignalR:ConnectionString:name_c:secondary <connection_string_3>
  

  Anda dapat menetapkan nama dan jenis ke setiap titik akhir dengan menggunakan nama konfigurasi yang berbeda dalam format berikut:

  Azure:SignalR:ConnectionString:<name>:<type>