Microsoft Graph 웹훅과 앱 인증

REST API 웹훅의 두 요청을 연결하여 Microsoft Entra ID에서 앱용 토큰을 발급받고, 그 토큰으로 Microsoft Graph를 호출할 수 있습니다. 다음 구성은 공용 Microsoft Graph의 client credentials 흐름을 사용하여 지정한 사용자 사서함에서 메일을 보내는 예입니다. 실행할 때마다 사용자가 브라우저로 로그인하는 방식이 아니라 등록한 앱 자체의 권한으로 호출합니다.

앱 등록과 권한

Microsoft Entra ID에 애플리케이션을 등록하고 실제 Tenant ID, Application(Client) ID와 Client Secret을 준비합니다. Graph의 필요한 Application permissions를 설정하고 관리자의 동의를 받아야 합니다. 메일 발송 예제에는 Mail.Send 애플리케이션 권한이 필요합니다. 권한 구성을 변경하면 관리자 동의도 다시 받아야 합니다.

메일 발송은 지정한 사서함과 수신자에게 실제 영향을 주므로, 웹훅을 시험하기 전에 허용된 발신 사서함과 수신자를 정합니다. 이 예제의 앱 권한은 로그인한 개인의 위임 권한과 구분해야 합니다. Microsoft의 앱 전용 인증 계약에 등록과 동의 조건이 설명되어 있습니다.

REST API 소스

1. Data Connection에서 REST API 소스를 생성합니다.
2. Domains에 login.microsoftonline.com과 graph.microsoft.com을 추가합니다.
3. 두 도메인에 대해 소스의 자동 Authentication 방식은 선택하지 않습니다. 웹훅의 첫 Call이 토큰 교환을 수행합니다.
4. Additional secrets에 TenantId, ClientId, ClientSecret을 등록합니다.
5. 두 도메인의 HTTPS 포트 443으로 연결할 수 있는 외부 통신 정책을 Network connectivity에 연결하고 Save and continue를 선택합니다.

첫 번째 Call: 토큰 발급

토큰 요청은 다음과 같이 구성합니다. 경로의 Tenant ID와 본문 인증 정보에는 소스에 저장한 값을 참조합니다.

폼 본문은 application/x-www-form-urlencoded로 전송합니다. Client Secret을 URL 쿼리에 넣지 않습니다. .default는 앱에 미리 구성하고 관리자가 동의한 Graph 애플리케이션 권한을 요청합니다.

성공한 토큰 응답에는 access_token, token_type, expires_in 등이 포함됩니다. expires_in은 유효 기간을 초 단위로 나타냅니다. 업무 요청에 사용할 토큰은 access_token에서 추출합니다. 토큰 발급은 일반 업무 데이터 쓰기와 구분하여 Read API로 분류하고, 두 번째 메일 발송 Call은 Write API로 둡니다.

두 번째 Call: 메일 발송

두 번째 Call의 도메인은 토큰 서버가 아니라 https://graph.microsoft.com입니다.

헤더의 토큰은 @ > From a call에서 첫 Call을 선택하고 Extract by key에 access_token을 지정하여 참조합니다. 토큰 값만 넣지 말고 앞에 Bearer 와 공백을 포함합니다.

메일 본문에는 message 객체가 필요합니다. 다음은 구조를 보여 주는 가상 데이터입니다. 실제 구성에서는 승인된 수신자와 업무 내용으로 바꾸거나, 웹훅 입력 매개변수를 각 필드에 연결합니다.

{
  "message": {
    "subject": "웹훅 연결 예시",
    "body": {
      "contentType": "Text",
      "content": "Foundry 웹훅의 메일 본문 구성 예시입니다."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "recipient@example.com"
        }
      }
    ]
  }
}

saveToSentItems는 선택적 Boolean이며 기본값은 true입니다. 보낸 편지함에 저장하지 않으려는 경우에만 최상위 필드로 false를 지정합니다.

응답과 보관

Graph의 sendMail 성공 응답은 202 Accepted이며 응답 본문이 없습니다. 따라서 두 번째 Call에서 존재하지 않는 JSON 필드를 필수 출력으로 추출하지 않습니다. 202는 요청이 접수되었다는 의미이며, 처리 완료나 수신자에게 실제로 전달되었다는 보장은 아닙니다. 전달에는 Exchange Online의 제한과 처리 과정이 적용됩니다. sendMail 계약에 요청 및 응답 조건이 정의되어 있습니다.

Storage and retention에서 첫 번째 Call의 전체 응답 저장을 끕니다. 액세스 토큰을 이력에 보관하면 상세 이력 열람 권한을 가진 사용자가 볼 수 있습니다. 웹훅의 일반 실행 제한, 호출 간 응답 추출과 권한은 설정 참조에 설명되어 있습니다.