다음을 통해 공유

클라이언트에 대한 클라이언트 액세스 URL을 생성하는 방법

  • 아티클

브라우저 💻, 모바일 앱 📱 또는 IoT 디바이스 💡에 해당하는 클라이언트는 클라이언트 액세스 URL을 사용하여 리소스에 연결하고 인증합니다.

URL은 아래 패턴을 따릅니다.

  • MQTT 클라이언트의 경우 wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>입니다.
  • 다른 모든 클라이언트의 경우에는 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>입니다.

이 문서에서는 클라이언트 액세스 URL을 가져오는 여러 가지 방법을 보여 줍니다.

Azure Portal에서 복사

Azure Portal의 키 탭에는 다음 다이어그램과 같이 클라이언트 액세스 URL을 빠르게 생성하는 클라이언트 URL 생성기 도구가 있습니다. 여기에 입력된 값은 저장되지 않습니다.

MQTT 클라이언트의 경우 "클라이언트 액세스 URL" 텍스트 상자 앞에 있는 드롭다운 메뉴에서 "MQTT 클라이언트"를 선택해야 합니다.

Web PubSub 클라이언트 URL 생성기의 스크린샷.

서비스 SDK에서 생성

Web PubSub 서버 SDK를 사용하여 동일한 클라이언트 액세스 URL을 생성할 수 있습니다.

  1. 서버 SDK 시작에 따라 WebPubSubServiceClient 개체 service를 만듭니다.

  2. WebPubSubServiceClient.getClientAccessToken을 호출하여 클라이언트 액세스 URL을 생성합니다.

    • 클라이언트 액세스 토큰 생성

      // for web pubsub native clients
let token = await serviceClient.getClientAccessToken();

// for mqtt clients
let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });

    • 사용자 ID 구성

      let token = await serviceClient.getClientAccessToken({ userId: "user1" });

    • 토큰의 수명 구성

      let token = await serviceClient.getClientAccessToken({
  expirationTimeInMinutes: 5,
});

    • 이 클라이언트 액세스 URL을 사용하여 연결할 때 그룹 group1을 직접 조인할 수 있는 역할 구성

      let token = await serviceClient.getClientAccessToken({
  roles: ["webpubsub.joinLeaveGroup.group1"],
});

    • 클라이언트가 이 클라이언트 액세스 URL을 사용하여 연결할 때 직접 그룹 group1로 메시지를 보낼 수 있는 역할 구성

      let token = await serviceClient.getClientAccessToken({
  roles: ["webpubsub.sendToGroup.group1"],
});

    • 이 클라이언트 액세스 URL을 사용하여 연결되면 클라이언트가 조인하는 그룹 group1 구성

      let token = await serviceClient.getClientAccessToken({
  groups: ["group1"],
});

실제 코드에서는 일반적으로 서버 쪽에서 클라이언트 액세스 URL을 생성하는 논리를 호스트합니다. 클라이언트 요청이 들어오면 서버 쪽에서 일반 인증/권한 부여 워크플로를 사용하여 클라이언트 요청의 유효성을 검사할 수 있습니다. 유효한 클라이언트 요청만 클라이언트 액세스 URL을 다시 가져올 수 있습니다.

REST API에서 생성 :generateToken

Microsoft Entra ID를 사용하고 클라이언트 토큰 REST API 생성을 호출하여 토큰을 생성할 수도 있습니다.

참고 항목

Web PubSub에서는 Microsoft Entra ID 서비스 주체에 대한 Microsoft Entra ID 토큰을 수동으로 만들지 않는 것이 좋습니다. 각 Microsoft Entra ID 토큰의 유효 기간은 짧으며 일반적으로 1시간 이내에 만료됩니다. 이 기간이 지나면 수동으로 Microsoft Entra ID 토큰을 생성하여 바꿔야 합니다. 대신, 만료된 Microsoft Entra ID 토큰을 자동으로 생성하여 바꿔주는 SDK를 사용합니다.

  1. 애플리케이션에서 권한 부여에 따라 Microsoft Entra ID를 사용하도록 설정합니다.

  2. Microsoft Entra 토큰을 가져옵니다.

  3. Microsoft Entra 토큰을 사용하여 :generateToken을 호출합니다.

  4. 다음 정보를 수집합니다.

    값 이름 값을 가져오는 방법
    TenantId TenantId는 등록한 애플리케이션의 개요 창에 있는 디렉터리(테넌트) ID의 값입니다.
    ClientId ClientId는 등록한 애플리케이션의 개요 창에 있는 애플리케이션(클라이언트) ID 값입니다.
    ClientSecret ClientSecret은 1단계에서 추가한 클라이언트 암호의 값입니다.

  5. Microsoft ID 플랫폼에서 Microsoft Entra ID 토큰 가져오기

    CURL 도구를 사용하여 REST API를 호출하는 방법을 보여 줍니다. 해당 도구는 Windows 10/11에 번들로 제공되며, CURL 설치에 따라 도구를 설치할 수 있습니다.

    # set necessary values, replace the placeholders with your actual values
export TenantId=<your_tenant_id>
export ClientId=<your_client_id>
export ClientSecret=<your_client_secret>

curl -X POST "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=$ClientId" \
--data-urlencode "client_secret=$ClientSecret" \
--data-urlencode "scope=https://webpubsub.azure.com/.default"

    위의 curl 명령은 Microsoft ID 엔드포인트에 POST 요청을 보내 Microsoft Entra ID 토큰을 다시 가져옵니다. 응답에서 access_token 필드에 Microsoft Entra ID 토큰이 표시됩니다. 나중에 사용할 수 있도록 복사하여 저장합니다.

  6. Microsoft Entra ID 토큰을 사용하여 :generateToken을 호출합니다.

    # Replace the values in {} with your actual values.
export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

    MQTT 클라이언트에 대한 토큰을 생성해야 하는 경우 URL에 clientType=mqtt 매개 변수를 추가합니다.

    export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01&clientType=mqtt" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

    cURL 명령을 실행하면 다음과 같은 응답을 가져오게 됩니다.

    {
  "token": "ABCDEFG.ABC.ABC"
}