다음을 통해 공유

사용자 지정 웹후크 인증을 사용하여 MQTT 브로커로 인증

이 문서에서는 웹후크 또는 Azure 함수를 사용하여 Azure Event Grid 네임스페이스로 인증하는 방법을 보여 줍니다.

웹후크 인증을 사용하면 외부 HTTP 엔드포인트(웹후크 또는 함수)가 MQTT(Message Queuing Telemetry Transport) 연결을 동적으로 인증할 수 있습니다. 이 방식은 Microsoft Entra ID JSON Web Token 유효성 검사를 사용하여 안전한 액세스를 보장합니다.

클라이언트가 연결을 시도하면 브로커가 공유 액세스 서명 토큰, 사용자 이름 및 암호와 같은 자격 증명의 유효성을 검사하거나 인증서 해지 목록 검사를 수행하는 사용자 정의 HTTP 엔드포인트를 호출합니다. 웹후크는 요청을 평가하고 세분화된 권한 부여를 위한 선택적 메타데이터와 함께 연결을 허용하거나 거부하는 결정을 반환합니다. 이 방법은 다양한 디바이스 플릿 및 사용 사례에서 유연하고 중앙 집중식 인증 정책을 지원합니다.

필수 조건

  • 시스템이 할당한 관리 ID 또는 사용자가 할당한 관리 ID가 있는 Event Grid 네임스페이스
  • 외부 웹후크 또는 Azure 함수
  • Event Grid 네임스페이스의 관리 ID에 Azure 함수 또는 웹후크에 대해 부여된 액세스 권한

고수준 단계

네임스페이스에 사용자 지정 웹후크 인증을 사용하려면 다음 단계를 수행합니다.

  1. 네임스페이스를 만들고 해당 하위 리소스를 구성합니다.
  2. Event Grid 네임스페이스에서 관리 ID를 사용합니다.
  3. 관리 ID에 Azure 함수 또는 웹후크에 대한 액세스 권한을 부여합니다.
  4. Event Grid 네임스페이스에서 사용자 지정 웹후크 설정 구성
  5. 클라이언트를 Event Grid 네임스페이스에 연결하고 웹후크 또는 함수를 통해 인증을 받습니다.

네임스페이스 만들기 및 해당 하위 리소스 구성

네임스페이스를 만들고 해당 하위 리소스를 구성하려면 빠른 시작: Azure Portal을 사용하여 Event Grid 네임스페이스에서 MQTT 메시지 게시 및 구독의 지침에 따릅니다. 클라이언트 ID는 제공된 토큰에서 나오므로 인증서 및 클라이언트 만들기 단계를 건너뜁니다. 클라이언트 특성은 클라이언트 토큰의 사용자 지정 클레임을 기반으로 합니다. 클라이언트 특성은 클라이언트 그룹 쿼리, 항목 템플릿 변수 및 라우팅 보강 구성에 사용됩니다.

Event Grid 네임스페이스에서 관리 ID 사용

Event Grid 네임스페이스에서 시스템이 할당한 관리 ID를 사용하도록 설정하려면 다음 명령을 사용합니다.

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"

Azure Portal을 사용하여 시스템 및 사용자 할당 ID를 구성하는 방법에 대한 자세한 내용은 Event Grid 네임스페이스에 관리 ID 사용을 참조하세요.

관리 ID에 함수 또는 웹후크에 대한 적절한 액세스 권한 부여

Event Grid 네임스페이스의 관리 ID에 대상 Azure 함수 또는 웹후크에 대한 적절한 액세스 권한을 부여합니다.

Azure 함수에 대한 사용자 지정 인증을 설정하려면 다음 단계를 수행합니다.

Microsoft Entra 앱 만들기

  1. Microsoft Entra ID에서 Microsoft Entra 앱을 만듭니다.

  2. 앱의 개요 페이지에서 애플리케이션(클라이언트) ID 값을 기록해 둡니다.

    애플리케이션(클라이언트) ID가 강조 표시된 Microsoft Entra ID 앱의 개요 페이지를 보여주는 스크린샷

  3. 왼쪽 메뉴에서 API 표시를 선택합니다. 애플리케이션 ID URI 옆에 있는 추가를 선택합니다.

  4. 애플리케이션 ID URI 편집 창에서 애플리케이션 ID URI 값을 기록한 다음 저장을 선택합니다.

    Microsoft Entra 앱의 애플리케이션 ID URI를 보여 주는 스크린샷

Azure 함수에 대한 인증 설정

Azure Portal에서 만든 기본 Azure 함수가 있는 경우 인증을 설정하고 관리 ID를 사용하여 만든 Microsoft Entra ID 토큰의 유효성을 검사합니다.

  1. Azure Functions 앱으로 이동합니다.

  2. 왼쪽 메뉴에서 인증을 선택한 다음 ID 공급자 추가를 선택합니다.

    인증 페이지를 보여주는 스크린샷

  3. ID 공급자 추가 페이지의 ID 공급자 드롭다운 목록에서 Microsoft를 선택합니다.

  4. 앱 등록 섹션에서 다음 속성에 대한 값을 지정합니다.

    1. 애플리케이션(클라이언트) ID: 앞에서 언급한 Microsoft Entra 앱의 클라이언트 ID를 입력합니다.

    2. 발급자 URL: 발급자 URL을 https://login.microsoftonline.com/<tenantid>/v2.0 형식으로 추가합니다.

      Microsoft를 ID 공급자로 사용하여 ID 공급자 추가를 보여 주는 스크린샷

  5. 허용되는 토큰 대상 그룹의 경우 앞에서 설명한 Microsoft Entra 앱의 애플리케이션 ID URI 값을 추가합니다.

  6. 추가 검사 섹션의 클라이언트 애플리케이션 개발에서 특정 클라이언트 애플리케이션의 요청 허용을 선택합니다.

  7. 허용되는 클라이언트 애플리케이션 창에서 토큰을 생성하는 데 사용되는 시스템이 할당한 관리 ID의 클라이언트 ID를 입력합니다. 이 ID는 Microsoft Entra ID 리소스의 엔터프라이즈 앱에서 찾을 수 있습니다.

  8. 특정 요구 사항에 따라 다른 설정을 선택한 다음 추가를 선택합니다.

이제 Microsoft Entra ID 토큰을 생성하고 사용합니다.

  1. 애플리케이션 ID URI가 있는 관리 ID를 리소스로 사용하여 Microsoft Entra ID 토큰을 생성합니다.
  2. 이 토큰을 사용하여 요청 헤더에 포함하여 Azure 함수를 호출합니다.

Event Grid 네임스페이스에서 사용자 지정 웹후크 인증 설정 구성

Azure Portal 및 Azure CLI를 사용하여 Event Grid 네임스페이스에서 사용자 지정 웹후크 인증 설정을 구성합니다. 먼저 네임스페이스를 만든 다음 업데이트합니다.

Azure Portal 사용

  1. Azure Portal에서 Event Grid 네임스페이스로 이동합니다.

  2. Event Grid 네임스페이스 페이지의 왼쪽 메뉴에서 구성을 선택합니다.

  3. 사용자 지정 웹후크 인증 섹션에서 다음 속성의 값을 지정합니다.

    1. 관리 ID 유형: 사용자 할당을 선택합니다.
    2. 웹후크 URL: Event Grid 서비스가 지정된 관리 ID를 사용하여 인증된 웹후크 요청을 보내는 URL 엔드포인트의 값을 입력합니다.
    3. 토큰 대상 그룹 URI: 전달 요청에 전달자 토큰으로 포함할 액세스 토큰을 가져오려면 Microsoft Entra 애플리케이션 ID 또는 URI의 값을 입력합니다.
    4. Microsoft Entra ID 테넌트 ID: 인증된 웹후크 전달을 위한 전달자 토큰을 획득하는 데 사용되는 Microsoft Entra 테넌트 ID의 값을 입력합니다.

  4. 적용을 선택합니다.

    Event Grid 네임스페이스에 대한 웹후크 인증의 구성을 보여 주는 스크린샷

Azure CLI 사용

사용자 지정 웹후크 인증 구성으로 네임스페이스를 업데이트하려면 다음 명령을 사용합니다.

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2025-04-01-preview \ 
    --identity-type UserAssigned \ 
    --identity-user-assigned-identities "/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX={}" \ 
    --set properties.isZoneRedundant=true \ 
        properties.topicSpacesConfiguration.state=Enabled \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.type=UserAssigned \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.userAssignedIdentity="/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.endpointUrl="https://XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryApplicationIdOrUri="api://XXXXXXXXXXX/.default" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryTenantId="XXXXXXXXXXX"

<NAMESPACE_NAME> 및 <RESOURCE_GROUP_NAME>을 실제 값으로 바꿉니다. 구독, 리소스 그룹, ID, 앱 ID, URL 및 테넌트 ID의 자리 표시자를 입력합니다. Event Grid MQTT 브로커에 대한 웹후크 기반 인증의 성능 및 안정성을 향상시키기 위해 웹후크 엔드포인트에 대해 HTTP/2 지원을 사용하도록 설정하는 것이 좋습니다.

웹후크 API 세부 정보

요청 헤더

권한 부여: 전달자 토큰

이 토큰은 웹후크를 호출하도록 구성된 관리 ID용 Microsoft Entra 토큰입니다.

요청 페이로드

{
    "clientId": "<string>",
    "userName": "<string>",
    "password": "<base64 encoded bytes>",
    "authenticationMethod": "<string>",
    "authenticationData": "<base64 encoded bytes>",
    "clientCertificate": "<certificate in PEM format>",
    "clientCertificateChain": "<certificates from chain in PEM format>"
}

페이로드 필드 설명

분야 필수/선택 사항 설명
clientId 필수 MQTT CONNECT 패킷의 클라이언트 ID입니다.
userName 선택적 MQTT CONNECT 패킷의 사용자 이름입니다.
password 선택적 Base64 인코딩 형식의 MQTT CONNECT 패킷 암호
authenticationMethod 선택적 MQTT CONNECT 패킷의 인증 방법(MQTT5에만 해당).
authenticationData 선택적 Base64 인코딩 형식의 MQTT CONNECT 패킷 인증 데이터(MQTT5만 해당)
clientCertificate 선택적 PEM 형식의 클라이언트 인증서입니다.
clientCertificateChain 선택적 클라이언트가 제공하는 기타 인증서는 클라이언트 인증서에서 인증 기관 인증서까지의 체인을 빌드하는 데 필요합니다.
userProperties 선택적 CONNECT 패킷의 사용자 속성(MQTT5에만 해당).

응답 페이로드

성공적인 응답

HTTP/1.1 200 OK 
Content-Type: application/json 

{ 
    "decision": "allow", 
    "clientAuthenticationName": "<string>", 
    "attributes": { 
        "attr": "<int/string/array_of_strings>", 
        ... 
    }, 
    "expiration": "<unix time format>" 
}

거부된 응답

HTTP/1.1 400 Bad Request 
Content-Type: application/json 

{ 
    "decision": "deny", 
    "errorReason": "<string>" 
}

응답 필드 설명

분야 설명
decision(필수) 인증 결과는 allow 또는 deny입니다.
clientAuthenticationName 클라이언트 인증 이름(ID 이름). (decision이 allow로 설정된 경우 필요합니다.)
attributes 특성이 있는 사전입니다. 키는 특성 이름이며 값은 int/string/array입니다. (decision이 allow로 설정된 경우 선택 사항입니다.)
expiration Unix 시간 형식의 만료 날짜입니다. (decision이 allow로 설정된 경우 선택 사항입니다.)
errorReason decision이 deny로 설정된 경우 표시되는 오류 메시지입니다. 이 오류가 기록됩니다. (decision이 deny로 설정된 경우 선택 사항입니다.)

지원되는 특성 형식의 예

"num_attr_pos": 1, 
"num_attr_neg": -1, 
"str_attr": "str_value", 
"str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
]

모든 올바른 데이터 유형(<int32/string/array_of_strings>에 적합한 숫자)이 특성으로 사용됩니다. 예를 들어 num_attr_pos, num_attr_neg, str_attr, str_list_attr 클레임은 올바른 데이터 유형을 가지며 특성으로 사용됩니다.

관련 콘텐츠

  • Last updated on