Azure SignalR Service의 연결 문자열

아티클
12/12/2024

Azure SignalR Service에 연결하는 방법에 대한 정보를 포함하는 연결 문자열입니다. 이 문서에서는 연결 문자열의 기본 사항과 애플리케이션에서 연결 문자열을 구성하는 방법을 알아봅니다.

Important

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다.

연결 문자열에는 애플리케이션이 Azure Web PubSub 서비스에 액세스하는 데 필요한 권한 부여 정보가 포함됩니다. 연결 문자열 내의 액세스 키는 서비스의 루트 암호와 비슷합니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 Microsoft Entra ID를 사용하여 연결 문자열 보호합니다.

액세스 키를 다른 사용자에게 배포하거나 하드 코딩하거나 다른 사용자가 액세스할 수 있는 일반 텍스트로 저장하지 않도록 합니다. 키가 손상되었다고 생각되면 키를 교체하세요.

연결 문자열이란?

애플리케이션이 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입니다.

다음 표에는 연결 문자열의 키/값 쌍에 대한 유효한 이름이 모두 나열되어 있습니다.

키	설명	필수	기본값	예제 값
`Endpoint`	Azure SignalR Service 인스턴스의 URL입니다.	예	해당 없음	`https://foo.service.signalr.net`
`Port`	Azure SignalR Service 인스턴스가 수신 대기 중인 포트입니다.	아니요	`80` 또는 `443`(엔드포인트 URI 스키마에 따라 다름)	`8080`
`Version`	연결 문자열의 버전입니다.	아니요	`1.0`	`1.0`
`ClientEndpoint`	Azure Application Gateway 또는 Azure API Management와 같은 역방향 프록시의 URI입니다.	아니요	`null`	`https://foo.bar`
`AuthType`	인증 유형입니다. 기본적으로 이 서비스는 `AccessKey`를 사용하여 요청에 권한을 부여합니다. 대/소문자를 구분하지 않습니다.	아니요	`null`	`Azure`, , `azure.msiazure.app`

액세스키 사용

이 서비스는 AuthType이 null로 설정된 경우 로컬 인증 방법을 사용합니다.

키	설명	필수	기본값	예제 값
`AccessKey`	액세스 토큰을 빌드하기 위한 base64 형식의 키 문자열입니다.	예	`null`	`ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/`

Microsoft Entra ID 사용

이 서비스는 AuthType이 azure, azure.app 또는 azure.msi로 설정되면 Microsoft Entra 인증 방법을 사용합니다.

키	설명	필수	기본값	예제 값
`ClientId`	GUID는 Azure Application 또는 Azure ID입니다.	아니요	`null`	`00000000-0000-0000-0000-000000000000`
`TenantId`	Microsoft Entra ID에 있는 조직의 GUID입니다.	아니요	`null`	`00000000-0000-0000-0000-000000000000`
`ClientSecret`	Azure Application 인스턴스의 암호입니다.	아니요	`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 리소스를 엽니다. 키 탭에는 다음 형식으로 두 개의 연결 문자열(기본 및 보조)이 표시됩니다.

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 리소스에 대한 요청 권한 부여를 참조하세요.

참고 항목

액세스 키보다 더 안전하기 때문에 관리 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 및 클라이언트 암호와 같은 정보를 입력할 수 있습니다. 그러면 연결 문자열이 자동으로 생성됩니다. 복사한 후 애플리케이션에서 사용할 수 있습니다.

참고 항목

이 페이지에서 나가면 입력한 정보가 저장되지 않습니다. 애플리케이션에서 사용할 연결 문자열을 복사하고 저장해야 합니다.

액세스 토큰을 생성하고 유효성을 검사하는 방법에 대한 자세한 내용은 Azure SignalR Service 데이터 평면 REST API 참조에서 토큰을 통해 인증을 참조하세요.

클라이언트 및 서버 엔드포인트 제공

연결 문자열에는 앱 서버가 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;

애플리케이션에서 연결 문자열 구성

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 Microsoft Entra ID를 사용하여 연결 문자열 보호합니다.

애플리케이션에서 연결 문자열을 구성하는 방법에는 두 가지가 있습니다.

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 서비스를 사용하여 Azure Key Vault 및 App Configuration과 같은 구성 및 비밀을 관리할 수 있습니다. 해당 서비스에 대한 구성 공급자를 설정하는 방법을 알아보려면 해당 설명서를 참조하세요.

참고 항목

코드를 사용하여 연결 문자열을 직접 설정하는 경우에도 소스 코드에서 연결 문자열을 하드 코딩하지 않는 것이 좋습니다. 대신 Key Vault와 같은 비밀 저장소에서 연결 문자열을 읽고 AddAzureSignalR()에 전달합니다.

여러 연결 문자열 구성

Azure SignalR Service 서버가 여러 서비스 엔드포인트에 동시에 연결할 수 있으므로 서비스 인스턴스의 한도를 초과하는 더 많은 연결을 처리할 수 있습니다. 하나의 서비스 인스턴스가 다운된 경우 다른 서비스 인스턴스를 백업으로 사용할 수 있습니다. 여러 인스턴스를 사용하는 방법에 대한 자세한 내용은 여러 인스턴스를 사용하여 SignalR Service 스케일링을 참조하세요.

여러 인스턴스를 구성하는 방법에는 다음 두 가지가 있습니다.

코드를 통해:

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

나중에 구분할 수 있도록 각 서비스 엔드포인트에 이름과 형식을 할당할 수 있습니다.

구성을 통해:

지원되는 구성 공급자(예: 비밀 관리자, 환경 변수 또는 키 자격 증명 모음)를 사용하여 연결 문자열을 저장할 수 있습니다. 비밀 관리자를 사용하는 예제는 다음과 같습니다.
```
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의 연결 문자열

연결 문자열이란?

연결 문자열의 모양

액세스키 사용

Microsoft Entra ID 사용

연결 문자열을 가져오는 방법

Azure Portal

Azure CLI

Microsoft Entra 애플리케이션으로 연결

관리 ID로 인증

연결 문자열 생성기 사용

클라이언트 및 서버 엔드포인트 제공

애플리케이션에서 연결 문자열 구성

여러 연결 문자열 구성

피드백

추가 리소스