KO
English
Deutsch
Español
Français
Italiano
Português
Nederlands
Polski
Bahasa Indonesia
Русский
Українська
العربية
עברית
日本語보안 이메일 솔루션 구축: 개발자를 위한 Microsoft Graph 메일 발송
By Mirko Peters ·
팟캐스트에 다시 오신 것을 환영합니다! 오늘 에피소드에서는 최신 이메일 전달 시스템의 아키텍처적 세부 사항을 깊이 있게 살펴보았습니다. 엔터프라이즈급 애플리케이션을 구축할 때, 하드코딩된 비밀번호와 암호화되지 않은 핸드셰이크가 포함된 레거시 SMTP 프로토콜에 의존하던 시대는 다행히 지났습니다. 오늘은 최신 ID 기반 API를 살펴보겠습니다. 구체적으로, Microsoft Graph API를 활용해 이메일을 안전하고 안정적으로, 대규모로 발송하는 방법을 알아봅니다.
Automatically translated with AI from the original post. Read the English original
팟캐스트에 다시 오신 것을 환영합니다! 오늘 에피소드에서는 최신 이메일 전달 시스템의 아키텍처적 세부 사항을 깊이 있게 살펴보았습니다. 엔터프라이즈급 애플리케이션을 구축할 때, 하드코딩된 비밀번호와 암호화되지 않은 핸드셰이크가 포함된 레거시 SMTP 프로토콜에 의존하던 시대는 다행히 지났습니다. 오늘은 최신 ID 기반 API를 살펴보겠습니다. 구체적으로, Microsoft Graph API를 활용해 이메일을 안전하고 안정적으로, 대규모로 발송하는 방법을 알아봅니다.
팟캐스트 내용을 따라 읽거나, 코드 스니펫을 직접 실행해 보거나, 코딩하면서 구현 패턴을 참고하고 싶은 분들을 위해 이 동반 블로그 글에서는 팟캐스트의 논의를 상세히 확장합니다. 개발자의 전체 여정을 단계별로 살펴보겠습니다. ID 공급자 설정, 토큰 안전하게 획득하기, 페이로드 구성하기, 일시적인 네트워크 장애 관리하기, 그리고 프로덕션 배포를 위한 아키텍처 보안 강화까지 다룹니다. 바로 시작하겠습니다.
Microsoft Graph Mail API 소개
수십 년 동안 애플리케이션에서 이메일을 보내려면 SMTP 서버에 연결하고, 기본 인증 자격 증명(환경 변수나 더 나쁘게는 구성 파일에 저장된 일반 텍스트 사용자 이름과 비밀번호인 경우가 많습니다)을 제공한 뒤 잘 되기만을 바라야 했습니다. 이 방식은 심각한 보안 위험을 안고 있습니다. 구성 파일이 유출되면 공격자는 해당 사서함에 대한 전체 액세스 권한을 얻게 됩니다. 또한 주요 클라우드 공급자들은 기본 인증을 점차 지원 중단하고, 최신 토큰 기반 ID 프레임워크로 전환하고 있습니다.
이제 Microsoft Graph API를 살펴보겠습니다. Microsoft Graph는 Microsoft 365의 데이터와 인텔리전스에 접근하는 관문입니다. Microsoft 365, Windows, Enterprise Mobility + Security 전반에서 생산성을 뒷받침하는 데이터에 접근할 수 있도록 통합된 프로그래밍 모델을 제공합니다. 이메일의 경우, Microsoft Graph Mail API를 사용하면 애플리케이션이 사용자를 대신하여, 또는 애플리케이션 자체로서 메일을 보낼 수 있으며, 이 모든 과정은 엄격한 OAuth 2.0 권한 부여 규칙에 따라 이루어집니다.
개발자가 전환해야 하는 이유는 무엇일까요? 무엇보다 보안입니다. Microsoft Entra ID(이전 명칭 Azure Active Directory)로 인증하면 저장된 비밀번호를 완전히 없앨 수 있습니다. 대신 애플리케이션은 암호화 키, 인증서 또는 관리 ID를 사용해 인증하며, 특정 작업을 실행할 권한과 맞바꾸는 단기 액세스 토큰을 받습니다. 둘째, Microsoft Graph는 풍부한 텔레메트리, 더 나은 감사 로깅, 그리고 더 넓은 Microsoft 생태계와의 깊은 통합을 제공합니다. 자동 청구 영수증, 시스템 알림, 사용자 대상 알림 중 무엇을 보내든, Microsoft Graph는 모든 트랜잭션 이메일 요구 사항을 위한 탄력적이고 현대적인 기반을 제공합니다.
Azure AD / Entra ID 앱 등록 및 권한 구성
코드를 한 줄이라도 작성하기 전에, Azure 테넌트 안에서 애플리케이션의 ID를 먼저 설정해야 합니다. 이 과정은 Microsoft Entra 관리 센터에서 앱 등록을 생성하는 것으로 시작합니다.
단계별 앱 등록
Microsoft Entra 관리 센터로 이동해 "앱 등록"을 선택한 다음 "새 등록"을 클릭합니다. 애플리케이션에 "Enterprise Notification Service"와 같이 설명이 드러나는 이름을 지정하고, 적절한 지원 계정 유형을 선택합니다. 대부분의 백엔드 서비스에는 "이 조직 디렉터리의 계정만"을 선택하는 것이 좋습니다. 생성이 끝나면 애플리케이션(클라이언트) ID와 디렉터리(테넌트) ID를 기록해 두십시오. 토큰 획득 로직을 구성할 때 이 값들이 필요합니다.
위임된 권한과 애플리케이션 권한의 차이
이 단계에서 내리게 될 가장 중요한 아키텍처 결정 중 하나는 위임된 권한과 애플리케이션 권한 중 하나를 선택하는 것입니다.
- 위임된 권한: 로그인한 사용자가 있는 앱에서 사용됩니다. 애플리케이션은 사용자를 대신하여 동작합니다. 메일 발송의 경우 일반적으로
Mail.Send권한이 필요합니다. 사용자가 앱을 실행하면, 애플리케이션이 자신의 ID를 사용해 메일을 보내는 데 동의해야 합니다. - 애플리케이션 권한: 로그인한 사용자가 없는 상태에서 실행되는 백그라운드 서비스, 데몬 또는 예약 작업에서 사용합니다. 이때 애플리케이션이 자체 ID로 동작합니다. 메일을 보내려면
Mail.Send애플리케이션 권한이 필요합니다. 이 권한을 부여하면 구성에 따라 앱이 조직 내 모든 사용자를 대신해 메일을 보낼 수 있으므로 관리자 동의가 필요합니다.
백그라운드 데몬이나 자동 알림 마이크로서비스에서는 반드시 애플리케이션 권한을 사용하게 됩니다. Azure Portal에서 Mail.Send 애플리케이션 권한을 할당한 후에는 테넌트 관리자가 "관리자 동의 허용" 버튼을 명시적으로 클릭해야 합니다. 이 관리자 승인이 없으면 Graph API를 호출할 때 앱이 HTTP 403 Forbidden 응답을 받게 됩니다.
보안을 유지하면서 토큰 획득하기
앱 등록을 구성하고 권한에 대한 동의까지 마쳤다면, 다음 단계는 OAuth 2.0 액세스 토큰을 안전하게 획득하는 것입니다. 비밀 정보를 코드에 하드코딩하지 마시고, 더 안전한 대안이 있다면 클라이언트 비밀은 사용하지 마십시오.
클라이언트 자격 증명 흐름
백엔드 애플리케이션은 사용자 인터페이스 없이 동작하므로 OAuth 2.0 클라이언트 자격 증명 부여(Client Credentials Grant) 흐름을 사용합니다. 이 흐름에서 애플리케이션은 클라이언트 ID와 증명 정보(클라이언트 비밀 또는 가능하면 비대칭 인증서)를 Microsoft ID 플랫폼의 토큰 발급 엔드포인트에 직접 제시합니다.
클라이언트 비밀이 널리 쓰이기는 하지만 만료되므로 수동으로 교체해야 하며, 이는 운영 부담과 서비스 중단 위험을 낳습니다. 인증서 기반 인증(CBA)을 사용하거나, 애플리케이션이 Azure 내부에서 실행된다면 관리 ID(Managed Identity)를 사용하시기를 강력히 권장합니다. 관리 ID를 사용하면 Azure가 토큰 수명 주기를 뒤에서 자동으로 처리하므로, 코드에서 자격 증명을 관리할 필요가 완전히 없어집니다.
코드에서 토큰 획득 구현하기
.NET 생태계에서 토큰을 획득하는 표준 방법은 Microsoft 인증 라이브러리(MSAL)를 사용하는 것입니다. MSAL은 토큰 캐싱, 자동 갱신 로직, 프로토콜 세부 사항을 기본으로 처리합니다.
다음은 Confidential Client Application을 초기화하고 토큰을 획득하는 방식을 개념적으로 보여주는 예시입니다.
// Conceptual initialization using MSAL
var confidentialClientApp = ConfidentialClientApplicationBuilder
.Create(clientId)
.WithClientSecret(clientSecret)
.WithTenantId(tenantId)
.Build();
string[] scopes = new[] { "https://graph.microsoft.com/.default" };
var authResult = await confidentialClientApp.AcquireTokenForClient(scopes)
.ExecuteAsync();
string accessToken = authResult.AccessToken;
범위(scope) 문자열 https://graph.microsoft.com/.default에 주목하십시오. 애플리케이션 권한을 사용할 때 .default 범위를 요청하면, ID 플랫폼은 앱 등록 단계에서 정적으로 구성되고 동의된 모든 애플리케이션 권한을 포함한 토큰을 발급합니다.
이메일 페이로드 구성 및 전송하기
유효한 JWT 액세스 토큰을 확보했다면 이제 Microsoft Graph API에 보낼 HTTP 요청을 구성할 차례입니다. 메일 전송 엔드포인트는 위임 권한을 사용하는지 애플리케이션 권한을 사용하는지에 따라 달라집니다.
엔드포인트 구조
애플리케이션 권한으로 특정 사용자를 대신해 메일을 보내는 경우 엔드포인트는 다음 구조를 따릅니다.
POST https://graph.microsoft.com/v1.0/users/{id-or-user-principal-name}/sendMail
이 방식을 사용하면 백그라운드 서비스가 notifications@yourcompany.com과 같이 지정된 서비스 계정에서 메일을 보낼 수 있습니다.
JSON 페이로드 작성하기
Microsoft Graph는 수신자, 제목, 본문 콘텐츠 형식(텍스트 또는 HTML), 선택적 첨부 파일 등 메시지 속성을 엄격하게 정의한 JSON 페이로드를 요구합니다. 다음은 올바르게 구성된 이메일 페이로드의 예시입니다.
{
"message": {
"subject": "System Status Update: Deployment Successful",
"body": {
"contentType": "HTML",
"content": "The scheduled deployment to the production cluster completed successfully at 03:00 UTC."
},
"toRecipients": [
{
"emailAddress": {
"address": "engineering-team@yourcompany.com"
}
}
],
"attachments": []
},
"saveToSentItems": "true"
}
saveToSentItems 속성에 특히 주의하십시오. 이 값을 true로 설정하면 발송된 메시지 사본이 발신 사서함의 보낸 편지함에 자동으로 저장되며, 이는 감사와 디버깅에 매우 유용합니다.
복원력 있는 실패 처리 및 재시도 구현하기
클라우드 API에 대한 네트워크 호출은 본질적으로 일시적 오류에 취약합니다. DNS 장애, 순간적인 라우팅 문제, 속도 제한(HTTP 429 Too Many Requests), 일시적인 서버 측 제한(HTTP 5xx 오류)은 운영 환경에서 결국 발생하게 됩니다. 메일 발송 로직이 이런 실패를 고려하지 않으면 메시지가 유실되어 사용자 경험이 깨지고 이해관계자들의 불만이 커질 것입니다.
견고한 재시도 정책 설계하기
높은 가용성을 확보하려면 Microsoft Graph API 호출을 복원력 있는 재시도 정책으로 감싸야 합니다. .NET 생태계의 Polly나 Node.js, Python, Java의 이에 상응하는 복원력 프레임워크를 사용하면 이를 손쉽게 구현할 수 있습니다.
재시도 전략을 설계할 때는 다음 핵심 원칙을 따르십시오.
- 지수 백오프(Exponential Backoff): 실패 직후 API를 연달아 호출하지 마십시오. 2초, 4초, 8초처럼 재시도할 때마다 대기 시간을 늘려, 하위 서비스가 복구될 시간을 확보하십시오.
- 지터(Jitter): 백오프 간격에 무작위성을 더하십시오. 마이크로서비스 100개가 동시에 실패한 뒤 고정된 간격으로 일제히 재시도하면, Graph API에 대한 자체 유발형 DDoS(분산 서비스 거부) 공격이 될 수 있습니다. 지터는 재시도 트래픽을 분산시킵니다.
- Retry-After 헤더 준수: Microsoft Graph가 애플리케이션을 조절(스로틀링)하면 HTTP 429 상태 코드와 함께
Retry-After헤더를 반환합니다. 이 헤더에는 다음 요청을 보내기 전까지 애플리케이션이 기다려야 하는 시간(초)이 담겨 있습니다. HTTP 클라이언트는 이 헤더를 반드시 확인하고 따라야 합니다.
지수 백오프와 지능형 스로틀링 관리를 함께 적용하면, 트래픽이 집중되는 시점에도 이메일 전송 서비스가 안정적으로 동작할 수 있습니다.
프로덕션 환경을 위한 모범 사례
이 블로그 글을 마무리하기 전에, 이메일 연동을 안전하고 성능 좋으며 장기적으로 유지 관리하기 쉬운 상태로 유지하기 위한 모범 사례 체크리스트를 살펴보겠습니다.
1. 메시지 큐를 활용한 비동기 처리
들어오는 웹 요청이나 API 호출 안에서 이메일을 동기적으로 보내지 마십시오. HTTP 요청이 곧바로 Microsoft Graph 호출을 유발하면, 사용자는 네트워크 왕복이 끝날 때까지 기다려야 하며, Graph에 잠깐이라도 장애가 생기면 웹 요청도 실패합니다. 대신 이메일 페이로드를 메시지 큐(Azure Service Bus, RabbitMQ, AWS SQS 등)에 넣고, 별도의 백그라운드 워커가 큐에서 항목을 가져와 Graph API 호출을 비동기로 실행하도록 구성하십시오.
2. 모니터링 및 알림
이메일 발송 파이프라인에 충분한 로깅과 메트릭을 구현하십시오. 총 발송 메시지 수, 실패율, 평균 재시도 횟수, 토큰 획득 지연 시간 같은 지표를 추적하십시오. 이상 오류 급증에 대한 알림도 설정하십시오. 예를 들어 HTTP 403 또는 429 오류율이 특정 임계값을 넘으면 운영팀에 즉시 알림이 가도록 해야 합니다.
3. 최소 권한 원칙
Azure AD 앱 등록을 주기적으로 점검하십시오. 애플리케이션에 조직 전체에 대한 광범위한 권한이 정말 필요한가요, 아니면 특정 사서함으로만 접근을 제한할 수 있나요? 더 이상 사용하지 않는 애플리케이션이 정리되고 접근 권한이 회수되도록, 동의 부여 내역을 주기적으로 검토하십시오.
결론
레거시 SMTP에서 벗어나 Microsoft Graph API를 채택하는 것은 애플리케이션 아키텍처를 현대화하는 데 큰 진전입니다. 견고한 앱 등록 구성, 안전한 토큰 획득 흐름, 구조화된 페이로드, 탄력적인 재시도 로직, 비동기 큐잉을 함께 적용하면 신뢰할 수 있는 엔터프라이즈급 이메일 엔진을 구축할 수 있습니다.
팟캐스트와 이 블로그 글을 함께 읽어 주셔서 감사합니다. 이 가이드가 도움이 되셨다면 팟캐스트를 구독하시고, 이 글을 동료 엔지니어들과 공유해 주시며, 다음 에피소드에서 다뤘으면 하는 주제를 댓글로 남겨 주십시오. 즐거운 코딩 되십시오!