Azure SignalR Service での接続文字列

[アーティクル]
08/09/2024

接続文字列には、Azure SignalR Service に接続する方法に関する情報が含まれています。この記事では、接続文字列の基礎と、アプリケーションでのその構成方法について説明します。

接続文字列とは

アプリケーションで Azure SignalR Service に接続する必要がある場合は、次の情報が必要になります。

Azure SignalR Service インスタンスの HTTP エンドポイント
サービスエンドポイントで認証を行う方法

接続文字列には、そのような情報が含まれています。

接続文字列の表記

接続文字列は、セミコロン (;) で区切られた、一連のキーと値のペアで構成されています。この文字列では、等号 (=) を使用して各キーとその値を接続します。キーでは大文字と小文字は区別されません。

一般的な接続文字列の表記は次の例のようになります。

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

接続文字列には、次のものが含まれています。

Endpoint=https://<resource_name>.service.signalr.net: リソースのエンドポイント URL。
AccessKey=<access_key>: サービスで認証を行うためのキー。接続文字列にアクセスキーを指定すると、Azure SignalR Service SDK がそれを使用して、サービスが検証するトークンを生成します。
Version: 接続文字列のバージョン。既定値は 1.0 です。

次の表に、接続文字列内で有効な、すべてのキーと値のペアの名前を示しています。

Key	説明	必須	規定値	例値
`Endpoint`	Azure SignalR Service インスタンスのURL。	はい	適用なし	`https://foo.service.signalr.net`
`Port`	Azure SignalR Service インスタンスでリッスンしているポート。	いいえ	エンドポイント URI スキーマに応じて、`80` または `443`	`8080`
`Version`	接続文字列のバージョン。	いいえ	`1.0`	`1.0`
`ClientEndpoint`	Azure Application Gateway や Azure API Management などのリバースプロキシの URI。	いいえ	`null`	`https://foo.bar`
`AuthType`	認証の種類。既定では、サービスは `AccessKey` を使用して要求を承認します。大文字と小文字の区別はありません。	いいえ	`null`	`Azure`、`azure.msi`、`azure.app`

AccessKey を使用する

AuthType が null に設定されている場合、サービスはローカルの認証方法を使用します。

Key	説明	必須	規定値	例値
`AccessKey`	アクセストークンをビルドする Base64 形式のキー文字列。	はい	`null`	`ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/`

Microsoft Entra ID を使用する

AuthType が azure、azure.app、または azure.msi に設定されている場合、サービスは Microsoft Entra の認証方法を使用します。

Key	説明	必須	規定値	例値
`ClientId`	Azure アプリケーションまたは Azure ID の GUID。	いいえ	`null`	`00000000-0000-0000-0000-000000000000`
`TenantId`	Microsoft Entra ID の組織の GUID。	いいえ	`null`	`00000000-0000-0000-0000-000000000000`
`ClientSecret`	Azure アプリケーションインスタンスのパスワード。	いいえ	`null`	`*********************.**************`
`ClientCertPath`	Azure アプリケーションインスタンスへのクライアント証明書ファイルの絶対パス。	いいえ	`null`	`/usr/local/cert/app.cert`

サービスは、指定したパラメーターに応じて、さまざまな TokenCredential 値を使用して Microsoft Entra トークンを生成します。

type=azure
- サービスでは、DefaultAzureCredential を使用します。
```
Endpoint=xxx;AuthType=azure
```
type=azure.msi
- 接続文字列で clientId を使用している場合、サービスではユーザー割り当てマネージド ID (ManagedIdentityCredential(clientId)) を使用します。
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>
```
- サービスでは、システム割り当てマネージド ID (ManagedIdentityCredential()) を使用します。
```
Endpoint=xxx;AuthType=azure.msi;
```
type=azure.app

clientId と tenantId の両方で、スプリンシパルのある Microsoft Entra アプリケーションする必要があります。
- 接続文字列で clientSecret を使用する場合、サービスでは ClientSecretCredential(clientId, tenantId, clientSecret) を使用します。
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>
```
- 接続文字列で clientCertPath を使用する場合、サービスでは ClientCertificateCredential(clientId, tenantId, clientCertPath) を使用します。
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
```

接続文字列を取得する方法

Azure portal または Azure CLI を使用して、接続文字列を取得できます。

Azure Portal

Azure portal で、Azure SignalR Service リソースを開きます。 [キー] タブに、次の形式の 2 つの接続文字列 (プライマリとセカンダリ) が表示されます。

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>

Microsoft Entra アプリケーションで接続する

Microsoft Entra アプリケーションを使用して、Azure SignalR Service インスタンスに接続できます。 Azure SignalR Service にアクセスするための適切なアクセス許可をアプリケーションが持っている場合、アクセスキーは必要ありません。

Microsoft Entra 認証を使うには、接続文字列から AccessKey を削除して、AuthType=azure.app を追加する必要があります。また、クライアント ID、クライアントシークレット、テナント ID など、Microsoft Entra アプリケーションの資格情報も指定する必要があります。接続文字列は次の例のようになります。

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

Microsoft Entra アプリケーションを使用して認証する方法の詳細については、Microsoft Entra アプリケーションで SignalR リソースへの要求を認証する方法に関する記事を参照してください。

マネージド ID による認証

システム割り当てまたはユーザー割り当てのマネージド ID は Azure SignalR Service での認証に使用できます。

システム割り当て ID を使用するには、接続文字列に AuthType=azure.msi を追加します。

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

Azure SignalR Service SDK では、アプリサーバーの ID が自動的に使用されます。

ユーザー割り当て ID を使用するには、接続文字列にマネージド ID のクライアント ID を含めます。

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

マネージド ID を構成する方法の詳細については、「Microsoft Entra マネージド ID を使用して SignalR リソースへの要求を承認する方法に関する記事を参照してください。

Note

アクセスキーよりも安全であるため、マネージド ID を使用して Azure SignalR Service で認証することを強くお勧めします。認証にアクセスキーを使用しない場合は、Azure portal で完全に無効にすることを検討してください ([キー]>[アクセスキー]>[無効にする] の順に選択します)。

アクセスキーを使用する場合は、定期的にローテーションすることをお勧めします。詳細については、「Azure SignalR Service のアクセスキーのローテーション」を参照してください。

接続文字列ジェネレーターを使用する

接続文字列を手動でビルドするのは、煩雑でエラーが発生しやすい場合があります。間違いを避けるために、Azure SignalR Service には、clientId や tenantId などの Microsoft Entra ID を含む接続文字列の生成を助ける接続文字列ジェネレーターが用意されています。このツールを使用するには、Azure portal で Azure SignalR Service インスタンスを開き、左側のメニューから [接続文字列] を選択します。

Azure portal での、Azure SignalR Service の接続文字列ジェネレーターを示すスクリーンショット。

このページでは、認証の種類 (アクセスキー、マネージド ID、Microsoft Entra アプリケーション) を選択し、クライアントエンドポイント、クライアント ID、クライアントシークレットなどの情報を入力できます。その後、接続文字列が自動的に生成されます。それをコピーして、アプリケーションで使うことができます。

Note

入力した情報は、ページを離れると保持されません。アプリケーションで使用するには、接続文字列をコピーして保存する必要があります。

アクセストークンの生成と検証方法の詳細については、Azure SignalR Service データプレーン REST API リファレンスのMicrosoft Entra トークンを使用した認証に関するセクションを参照してください。

クライアントとサーバーのエンドポイントを指定する

接続文字列には、Azure SignalR Service に接続するためのアプリサーバーの HTTP エンドポイントが含まれています。クライアントがサービスに接続できるように、サーバーはネゴシエーション応答でクライアントに HTTP エンドポイントを返します。

一部のアプリケーションでは、Azure SignalR Service の前に追加のコンポーネントが存在する場合があります。すべてのクライアント接続は、まずそのコンポーネントを経由する必要があります。たとえば、Azure Application Gateway は、追加のネットワークセキュリティを提供する一般的なサービスです。

このような場合、クライアントは Azure SignalR Service とは異なるエンドポイントに接続する必要があります。クライアント側でエンドポイントを手動で置き換える代わりに、接続文字列に ClientEndpoint を追加することができます。

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

アプリサーバーは、クライアントのネゴシエーション要求に対する応答を返します。その応答には、接続するクライアントの正しいエンドポイント URL が含まれています。クライアント接続の詳細については、「Azure SignalR Service の内部」を参照してください。

同様に、サーバーでサーバー接続を行ったり、REST API を呼び出したりする場合は、Azure SignalR Service が Azure Application Gateway のような別のサービスの背後にある場合もあります。その場合は、ServerEndpoint を使って、サーバー接続と REST API の実際のエンドポイントを指定できます。

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

アプリケーションで接続文字列を構成する

アプリケーションで接続文字列を構成するには、2 つの方法があります。

AddAzureSignalR() API を呼び出すときに、接続文字列を設定できます。

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

または、引数を指定せずに AddAzureSignalR() を呼び出すこともできます。サービス SDK は、構成プロバイダーにある Azure:SignalR:ConnectionString という名前の構成から接続文字列を返します。

ローカル開発環境では、構成はファイル (appsettings.json または secrets.json) または環境変数に格納されます。接続文字列を構成するには、次の方法のいずれかを使用できます。

.NET シークレットマネージャー (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>") を使用します。
Azure__SignalR__ConnectionString という名前の環境変数を接続文字列に設定します。コロンは、環境変数構成プロバイダーの二重アンダースコアに置き換える必要があります。

運用環境では、Azure Key Vault や App Configuration などの他の Azure サービスを使用して、構成とシークレットを管理できます。それらのサービス用に構成プロバイダーを設定する方法については、それぞれのドキュメントをご覧ください。

Note

コードを使用して接続文字列を直接設定する場合でも、ソースコードで接続文字列をハードコーディングすることはお勧めしません。代わりに、Key Vault などのシークレットストアから接続文字列を読み取り、AddAzureSignalR() に渡します。

複数の接続文字列を構成する

Azure SignalR Service を使うと、サーバーで複数のサービスエンドポイントに同時に接続できるため、サービスインスタンスの制限を超える数の接続を処理できます。 1 つのサービスインスタンスがダウンした場合は、他のサービスインスタンスをバックアップとして使用できます。複数のインスタンスの使用方法の詳細については、「複数のインスタンスがある SignalR Service のスケーリング」を参照してください。

複数のインスタンスを構成する方法は 2 つあります。

コードによる方法:

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),
        };
    });

後で区別できるように、各サービスエンドポイントに名前と種類を割り当てることができます。

構成ファイルによるリモート処理:

サポートされている任意の構成プロバイダー (シークレットマネージャー、環境変数、Key Vault など) を使って、接続文字列を格納できます。シークレットマネージャーを使用する例を次に示します。
```
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>
```
次の形式で異なる構成名を使用することで、エンドポイントごとに名前と種類を割り当てることができます。
```
Azure:SignalR:ConnectionString:<name>:<type>
```

次の方法で共有

Azure SignalR Service での接続文字列

接続文字列とは

接続文字列の表記

AccessKey を使用する

Microsoft Entra ID を使用する

接続文字列を取得する方法

Azure Portal

Azure CLI

Microsoft Entra アプリケーションで接続する

マネージド ID による認証

接続文字列ジェネレーターを使用する

クライアントとサーバーのエンドポイントを指定する

アプリケーションで接続文字列を構成する

複数の接続文字列を構成する

フィードバック

その他のリソース