Microsoft Graph 애플리케이션 등록

Teams 세션 파이프라인은 앱 전용(데몬) 인증을 사용하여 Microsoft Graph에서 세션 기록, 녹음 파일 및 관련 아티팩트를 읽습니다. 즉, 사용자 로그인이나 세션당 대화형 동의가 없습니다. 이를 위해서는 관리자가 동의한 애플리케이션 권한으로 Azure AD 애플리케이션을 등록해야 합니다.

이 가이드에서는 다음 내용을 안내합니다.

앱 등록 만들기
클라이언트 비밀번호 만들기
파이프라인에 필요한 그래프 API 권한 부여
해당 권한에 대한 관리자 동의
(선택 사항) 애플리케이션 액세스 정책을 사용하여 특정 사용자로 앱 범위 지정

이 작업을 완료하려면 테넌트 관리자 권한(또는 사용자를 대신하여 동의를 부여하는 관리자)이 필요합니다. 수집한 값을 북마크에 추가하세요. 값은 마지막에 ~/.hermes/.env에 들어갑니다.

전제 조건

모임 기록 및 녹음을 생성하는 Teams Premium 또는 Teams 라이선스가 있는 Microsoft 365 테넌트
entra.microsoft.com에서 Azure Portal에 대한 관리자 액세스
그래프 변경 알림을 위해 공개적으로 연결 가능한 HTTPS 엔드포인트(나중에 웹훅 리스너 단계에서 설정)

1단계: 앱 등록 생성

테넌트 관리자로 entra.microsoft.com에 로그인합니다.
ID → 애플리케이션 → 앱 등록으로 이동합니다.
신규 등록을 클릭합니다.
작성:
- 이름: Hermes Teams Meeting Pipeline(또는 사용자가 인식할 수 있는 이름).
- 지원되는 계정 유형: 이 조직 디렉터리의 계정만 해당(단일 테넌트).
- 리디렉션 URI: 비워두세요. 앱 전용 인증에는 필요하지 않습니다.
등록을 클릭하세요.

앱의 개요 페이지로 이동하게 됩니다. 두 값을 복사합니다.

애플리케이션(클라이언트) ID → MSGRAPH_CLIENT_ID
디렉터리(테넌트) ID → MSGRAPH_TENANT_ID

2단계: 클라이언트 비밀번호 생성

왼쪽 탐색 메뉴에서 인증서 및 비밀을 엽니다.
새 클라이언트 비밀번호를 클릭합니다.
설명:hermes-graph-secret.만료: 순환 정책과 일치하는 값을 선택합니다(일반적으로 6~24개월).
추가를 클릭합니다.
값 열을 즉시 복사하세요. 한 번만 표시됩니다. 해당 값은 MSGRAPH_CLIENT_SECRET입니다.

비밀 ID열은 비밀이 아닙니다.값 열이 필요합니다.

3단계: 그래프 API 권한 부여

파이프라인은 최소한으로 실행 가능한 애플리케이션 권한 집합을 사용합니다. 필요한 것만 추가하세요. 각각은 앱이 테넌트 전체에서 읽을 수 있는 범위를 넓힙니다.

왼쪽 탐색 메뉴에서 API 권한을 엽니다.
권한 추가→Microsoft Graph→응용 프로그램 권한을 클릭합니다.
파이프라인에서 수행하려는 작업과 일치하는 권한을 아래 표에서 추가하세요.
추가한 후 <your tenant>에 대한 관리자 동의 부여를 클릭하세요. 상태 열은 모든 권한에 대해 녹색 확인 표시로 바뀌어야 합니다.

성적표 우선 요약에 필수

허가	앱이 수행할 수 있는 작업
`OnlineMeetings.Read.All`	Teams 온라인 모임 메타데이터(제목, 참가자, 참가 URL)를 읽어보세요.
`OnlineMeetingTranscript.Read.All`	Teams에서 생성된 모임 기록을 읽어보세요.

대체 녹음에 필요합니다(대본을 사용할 수 없는 경우).

허가	앱이 수행할 수 있는 작업
`OnlineMeetingRecording.Read.All`	오프라인 STT 처리를 위해 Teams 모임 녹음을 다운로드하세요.
`CallRecords.Read.All`	참여 URL만 알려진 경우 통화 기록에서 세션를 해결합니다.

아웃바운드 요약 전달에 필요(그래프 모드만 해당)

platforms.teams.extra.delivery_mode이 graph인 경우 파이프라인은 Teams 채널에 요약을 게시하거나 그래프 API를 통해 채팅합니다. 대신 incoming_webhook 배송 모드를 사용하는 경우에는 이 단계를 건너뛰세요.

허가	앱이 수행할 수 있는 작업
`ChannelMessage.Send`	앱을 대신하여 Teams 채널에 메시지를 게시합니다.
`Chat.ReadWrite.All`	1:1 및 그룹 채팅에 메시지를 게시하세요(`chat_id`을 전달 대상으로 설정한 경우에만 해당).

권장되지 않음

OnlineMeetings.ReadWrite.All / Chat.ReadWrite(.All 제외) - 파이프라인 요구 사항보다 넓습니다.
위임된 권한 — 파이프라인은 앱 전용(클라이언트 자격 증명) 흐름을 사용합니다. 위임된 권한은 사용자 로그인 없이는 작동하지 않습니다.

4단계: (권장) 애플리케이션 액세스 정책으로 앱 범위 지정

기본적으로 OnlineMeetings.Read.All과 같은 애플리케이션 권한은 테넌트의 모든 모임에 대한 액세스 권한을 앱에 부여합니다. 파트너 데모 및 개발 테넌트에게는 괜찮습니다. 프로덕션에서는 앱이 읽을 수 있는 사용자 세션를 제한하려고 할 것입니다.

Microsoft는 이를 위해 정확하게 Teams용 애플리케이션 액세스 정책을 제공합니다. 정책은 PowerShell 전용 표면입니다. 이에 대한 포털 UI가 없습니다.

MicrosoftTeams 모듈이 설치 및 연결된 관리자 PowerShell에서(Connect-MicrosoftTeams):

# Create a policy scoped to the Hermes app
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Restrict Hermes meeting pipeline to allow-listed users"

# Grant the policy to specific users whose meetings the pipeline may read
Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "alice@example.com"

Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "bob@example.com"

승인 후 전파에는 최대 30분이 걸릴 수 있습니다. 다음을 통해 확인하세요.

Test-CsApplicationAccessPolicy -Identity "alice@example.com" -AppId "<MSGRAPH_CLIENT_ID>"

정책이 없으면 모든 사용자의 세션를 읽을 수 있습니다. 이는 기술적으로 권한이 부여되는 것입니다. 프로덕션 테넌트에서는 이 단계를 건너뛰지 마세요.

5단계: Env 파일에 자격 증명 쓰기

수집한 세 가지 값을 ~/.hermes/.env에 입력하세요.

MSGRAPH_TENANT_ID=<directory-tenant-id>
MSGRAPH_CLIENT_ID=<application-client-id>
MSGRAPH_CLIENT_SECRET=<client-secret-value>

본인만 비밀을 읽을 수 있도록 파일 권한을 설정하세요.

chmod 600 ~/.hermes/.env

6단계: 토큰 흐름 확인

Hermes는 Graph 인증 연기 테스트를 제공합니다. Hermes 설치에서:

python -c "
import asyncio
from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
provider = MicrosoftGraphTokenProvider.from_env()
token = asyncio.run(provider.get_access_token())
print('Token acquired, length:', len(token))
print(provider.inspect_token_health())
"

성공적인 실행은 cached: True 및 3600 근처의 expires_in_seconds 값을 표시하는 긴 토큰 문자열과 상태 dict를 인쇄합니다. 실패하면 Azure 오류 코드와 함께 MicrosoftGraphTokenError이 생성됩니다. 가장 일반적인 것은 다음과 같습니다.

Azure 오류	의미	수정
`AADSTS7000215: Invalid client secret`	비밀번호 값이 일치하지 않거나 만료되었습니다.	2단계에서 새 비밀을 생성합니다. `.env`을 업데이트하세요.
`AADSTS700016: Application not found`	`MSGRAPH_CLIENT_ID` 또는 잘못된 테넌트가 잘못되었습니다.	1단계의 값이 동일한 앱에서 나온 것인지 다시 확인하세요.
`AADSTS90002: Tenant not found`	`MSGRAPH_TENANT_ID`에 오타가 있습니다.	앱 개요에서 디렉터리(테넌트) ID를 다시 복사합니다.
`insufficient_claims` 호출 시간(토큰 시간 아님)	토큰을 획득했지만 그래프가 401/403을 반환합니다.	3단계 관리자 동의를 건너뛰었거나 권한을 추가했지만 다시 동의하지 않았습니다. API 권한을 다시 방문하여 관리자 동의 부여를 다시 클릭하세요.

클라이언트 비밀번호 교체

Azure 클라이언트 비밀에는 강제 만료가 있습니다. 만료되기 전:

첫 번째 클라이언트 암호를 삭제하지 않고 2단계에서 두 번째 클라이언트 암호를 만듭니다.
~/.hermes/.env의 MSGRAPH_CLIENT_SECRET을 새 값으로 업데이트합니다.
새 비밀번호가 선택되도록 게이트웨이를 다시 시작하세요: hermes gateway restart.
위의 스모크 테스트를 통해 확인해보세요.
Azure Portal에서 이전 비밀을 삭제합니다.

다음 단계

자격 증명이 완전히 확인되면 다음을 계속 진행합니다.

웹훅 리스너 설정 — 그래프 변경 알림을 수신하는 msgraph_webhook 게이트웨이 플랫폼을 시작합니다.
파이프라인 구성 — Teams 미팅 파이프라인 런타임 및 운영자 CLI를 구성합니다.
아웃바운드 전달 - 요약을 Teams 채널이나 채팅으로 다시 전송합니다.

해당 페이지는 해당 런타임을 추가하는 PR과 함께 표시됩니다. 이 자격 증명 설정은 독립 실행형 전제 조건이며 미리 완료해도 안전합니다.

전제 조건​

1단계: 앱 등록 생성​

2단계: 클라이언트 비밀번호 생성​

3단계: 그래프 API 권한 부여​

성적표 우선 요약에 필수​

대체 녹음에 필요합니다(대본을 사용할 수 없는 경우).​

아웃바운드 요약 전달에 필요(그래프 모드만 해당)​

권장되지 않음​

4단계: (권장) 애플리케이션 액세스 정책으로 앱 범위 지정​

5단계: Env 파일에 자격 증명 쓰기​

6단계: 토큰 흐름 확인​

클라이언트 비밀번호 교체​

다음 단계​