PowerShell과 Microsoft Graph로 관리 ID 흐름 마스터하기

By Mirko Peters · 2026-08-28

팟캐스트 블로그에 다시 오신 것을 환영합니다! 하드코딩된 암호를 사용하거나, 번거로운 클라이언트 비밀을 관리하거나, 자동화 스크립트에서 자격 증명이 유출될까 걱정해 본 적이 있다면 이 글이 도움이 될 것입니다…

Automatically translated with AI from the original post. Read the English original

팟캐스트 블로그에 다시 오신 것을 환영합니다! 하드코딩된 암호를 사용하거나, 번거로운 클라이언트 비밀을 관리하거나, 자동화 스크립트에서 자격 증명이 유출될까 걱정해 본 적이 있다면 이 글이 도움이 될 것입니다. 클라우드 자동화에서는 보안을 바라보는 방식부터 바뀌어야 합니다. 관리자가 주변을 살피지 않고도 일반 텍스트 구성 파일이나 환경 변수에 자격 증명을 안전하게 숨겨 둘 수 있던 시절은 지났습니다. 오늘은 클라우드 네이티브 인증을 깊이 살펴보며, Azure의 관리 ID를 PowerShell 스크립트에서 활용해 민감한 자격 증명을 저장하지 않고도 Microsoft Graph에 안전하게 인증하는 방법을 알아보겠습니다.

Microsoft 365 환경을 자동화하는 것은 더 이상 있으면 좋은 기술이 아니라 운영상 반드시 필요한 역량입니다. 그러나 PowerShell과 Microsoft Graph API를 함께 사용하다 보면 권한 요청, 조절(throttling) 제한, 복잡한 토큰 획득 흐름이 얽힌 미로처럼 느껴질 때가 있습니다. ID 중심의 최신 워크플로로 사고방식을 전환하면 Azure 내부에서 실행되는 워크로드에 대해 자격 증명 관리를 아예 없앨 수 있습니다. 이번 글에서는 사전 요구 사항, Azure AD 앱 등록, 토큰 획득 흐름, 스크립트 최적화를 차례로 살펴보며 클라우드 네이티브 인증의 핵심 구성 요소를 자세히 설명하겠습니다. 이 워크플로를 더 깊이 알고 싶다면 함께 제공되는 팟캐스트 에피소드 Use Managed Identity with PowerShell for Microsoft Graph를 꼭 들어 보시기 바랍니다.

PowerShell + Graph API 사전 요구 사항

PowerShell과 Graph API로 Microsoft 365 작업을 자동화하기 전에 시스템과 환경을 올바르게 준비해야 합니다. 이 준비 과정은 원활한 실행과 Microsoft Graph 리소스에 대한 안전한 접근을 보장합니다.

PowerShell 모듈 설치

Microsoft Graph API와 상호 작용하려면 적절한 PowerShell 모듈을 설치해야 합니다. Microsoft Graph PowerShell SDK는 이 통합에 필요한 모든 cmdlet을 제공합니다. 오류를 방지하려면 시스템이 다음 최소 요구 사항을 충족하는지 확인하십시오.

Install-Module PowerShellGet -Force를 실행하여 PowerShellGet을 업데이트하고, Set-ExecutionPolicy RemoteSigned로 실행 정책을 설정할 수 있습니다. 그다음 다음 명령으로 Microsoft Graph 모듈을 설치하십시오.

Install-Module Microsoft.Graph -Scope CurrentUser

이 명령은 최신 안정 버전의 모듈을 다운로드하여 Microsoft Graph 엔드포인트를 손쉽게 호출할 수 있게 해 줍니다.

Microsoft 365 환경 설정

자동화를 위해서는 Microsoft 365 환경을 올바르게 구성하는 것이 무엇보다 중요합니다. 시작하려면 다음 단계를 따르십시오.

1. 시스템이 요구 사항을 충족하는지 확인하십시오: PowerShell 7.2 이상, .NET Framework 4.7.2 이상, 최신 PowerShellGet 모듈.
2. 위에서 설명한 대로 Microsoft Graph PowerShell 모듈을 설치하십시오.
3. 모듈을 가져온 다음 필요한 범위(scope)로 인증하여 Microsoft 365 테넌트에 연결하십시오. 예를 들면 다음과 같습니다.

Connect-MgGraph -Scopes "User.ReadWrite.All","Directory.ReadWrite.All"

이 명령을 실행하면 로그인 창이 표시되며, 세션에 사용자 및 디렉터리 데이터를 읽고 쓸 수 있는 권한이 부여됩니다. 자동화 요구에 따라 범위를 조정할 수 있습니다.

권한과 범위 이해하기

권한과 범위는 스크립트가 Microsoft 365에서 무엇에 접근하고 무엇을 수정할 수 있는지를 정의합니다. Microsoft Graph API는 두 가지 주요 권한 유형을 사용합니다.

• 위임된 권한: 사용자가 로그인한 상태에서 스크립트를 실행할 때 적용됩니다. 사용자가 소유하거나 액세스할 수 있는 데이터로 액세스 범위가 제한됩니다.
• 애플리케이션 권한: 로그인한 사용자 없이도 앱이나 스크립트가 조직 전체의 데이터에 액세스할 수 있도록 합니다. 백그라운드 자동화와 관리 ID 흐름에서 일반적으로 사용됩니다.

일반적인 권한으로는 읽기 전용 액세스를 위한 *.Read.All과 전체 읽기 및 쓰기 기능을 위한 *.ReadWrite.All이 있습니다. 예를 들어 SecurityActions.Read.All은 보안 작업을 조회할 수 있게 하고, SecurityActions.ReadWrite.All은 보안 작업을 수정할 수 있게 합니다.

애플리케이션 권한에는 관리자 동의가 필요합니다. 보안을 보장하려면 테넌트 관리자가 이러한 권한을 승인해야 합니다. 또한 민감한 데이터에 액세스하려면 사용자에게 Security Reader와 같은 적절한 Microsoft Entra 역할이 있어야 합니다. 이러한 역할 기반 액세스는 추가적인 보안 계층을 제공합니다.

Microsoft Graph PowerShell SDK로 연결할 때는 스크립트에 필요한 범위만 지정하십시오. 이는 최소 권한 원칙을 따르는 방법으로, 보안 위험을 줄여 줍니다. 앱에 부여된 권한은 해당 앱의 모든 사용자에게 적용되므로 정기적으로 검토하고 관리하십시오.

Azure AD의 앱 ID

새 앱 등록

PowerShell과 Graph API로 Microsoft 365 작업을 자동화하려면 먼저 Azure Active Directory(Azure AD)에 애플리케이션을 등록해야 합니다. 이 앱은 스크립트가 Microsoft Graph에 안전하게 액세스할 때 사용하는 ID 역할을 합니다. 다음 단계에 따라 앱을 등록하십시오.

1. Azure Portal을 열고 Azure Active Directory > 앱 등록 > 새 등록으로 이동합니다.
2. "My Graph Automation App"처럼 의미 있는 앱 이름을 지정합니다.
3. 지원되는 계정 유형을 선택합니다.
   • 단일 테넌트: Azure AD 테넌트의 사용자만 로그인할 수 있습니다.
   • 다중 테넌트: 모든 Azure AD 테넌트의 사용자가 로그인할 수 있습니다.
   • 다중 테넌트 및 개인 계정: Azure AD 사용자와 개인 Microsoft 계정을 모두 포함합니다.
4. 앱 유형에 따라 리디렉션 URI를 설정합니다.
   • 웹 앱은 https://yourapp.com/auth/callback과 같은 URL을 사용합니다.
   • 단일 페이지 앱은 https://yourapp.com을 사용합니다.
   • 모바일 또는 데스크톱 앱은 https://login.microsoftonline.com/common/oauth2/nativeclient를 사용합니다.
5. 등록을 클릭하여 앱을 만듭니다.

이 과정에서 테넌트에 고유한 애플리케이션 ID가 생성됩니다. 이 ID를 사용해 토큰을 요청하고 Microsoft Graph API를 호출합니다.

API 권한 구성

앱을 등록한 후에는 앱에 필요한 API 권한을 구성해야 합니다. 이 권한은 앱이 Microsoft 365에서 액세스하거나 수정할 수 있는 범위를 제어합니다. 권한을 설정하려면 다음을 따르십시오.

1. 앱 등록에서 API 권한 > 권한 추가 > Microsoft Graph로 이동합니다.
2. 스크립트가 사용자 상호 작용 없이 실행되거나 관리 ID 컨텍스트에서 실행되면 애플리케이션 권한을, 대화형으로 실행되면 위임된 권한을 선택합니다.
3. User.Read.All이나 Directory.Read.All처럼 앱에 필요한 특정 권한을 선택합니다.
4. 권한 추가를 클릭하여 적용합니다.

⚠️ 항상 최소 권한 원칙을 적용하십시오. 보안 위험을 줄이려면 앱에 필요한 권한만 할당하십시오.

일부 권한은 앱에서 사용하기 전에 관리자 동의가 필요합니다. Azure Portal에서 [테넌트 이름]에 대한 관리자 동의 부여를 클릭하여 동의를 부여할 수 있습니다. 앱에 과도한 권한이 부여되지 않도록 권한을 정기적으로 검토하십시오.

클라이언트 비밀 또는 인증서 생성

관리 ID를 사용하지 않는 경우 앱이 Azure AD로 안전하게 인증하려면 자격 증명이 필요합니다. 클라이언트 비밀 또는 인증서를 사용할 수 있습니다. 두 방식 모두 토큰을 요청할 때 앱의 ID를 증명합니다.

클라이언트 비밀을 만들려면 앱 등록에서 인증서 및 암호로 이동한 후 새 클라이언트 비밀을 선택하고, 설명을 입력한 다음 만료 기간을 설정합니다. 인증서의 경우 같은 섹션에서 유효한 인증서 파일을 업로드합니다.

액세스 토큰 가져오기

OAuth 2.0 이해하기

OAuth 2.0은 PowerShell + Graph API를 사용할 때 Microsoft Graph API에 대한 액세스를 보호하는 데 중요한 역할을 합니다. 신뢰할 수 있는 게이트키퍼 역할을 하여 애플리케이션이 안전하게 인증하고 액세스 토큰을 얻을 수 있도록 합니다. 이 토큰은 디지털 키 역할을 하여, 자격 증명을 직접 노출하지 않고도 스크립트가 Microsoft Graph 엔드포인트를 호출할 권한을 부여합니다.

OAuth 2.0을 사용하려면 먼저 Azure Active Directory(Azure AD)에 애플리케이션을 등록해야 합니다. 이 등록을 통해 애플리케이션 ID와 비밀 또는 인증서 같은 클라이언트 자격 증명이 제공됩니다. 스크립트가 액세스 토큰을 요청하면 이러한 자격 증명을 Azure AD에 제시합니다. 그러면 Azure AD가 ID를 확인하고 수명이 짧은 토큰을 발급합니다. 스크립트는 이 토큰을 API 요청에 포함하여 요청한 리소스에 접근할 권한이 있음을 증명합니다.

이 과정을 통해 Microsoft 365 데이터에 대한 안전하고 통제된 액세스가 보장됩니다. 또한 세분화된 권한을 지원하므로 스크립트는 필요한 액세스 권한만 얻게 됩니다. OAuth 2.0 표준을 따르면 무단 액세스로부터 환경을 보호하는 동시에 PowerShell + Graph API로 강력한 자동화를 구현할 수 있습니다.

PowerShell로 토큰 요청하기

다양한 시나리오에 맞춘 여러 인증 흐름을 사용하여 액세스 토큰을 가져올 수 있습니다. 각 흐름은 보안과 사용 편의성의 균형을 다르게 유지합니다. Microsoft Graph API는 다음과 같은 일반적인 흐름을 지원합니다.

• 디바이스 코드 흐름: 브라우저나 입력 기능이 없는 디바이스 또는 스크립트에 적합합니다. 별도의 디바이스에서 인증하므로 안전하고 사용하기 편리합니다.
• 인증서 기반 흐름: 헤드리스 자동화를 위해 설계되었으며, 비밀번호 대신 인증서를 사용하여 无인 스크립트의 보안을 강화합니다.
• 관리 ID 흐름: Azure Functions나 가상 머신과 같은 클라우드 네이티브 환경에 가장 적합합니다. 이 흐름은 Azure의 관리 ID를 활용하여 비밀을 저장하지 않고 토큰을 가져옵니다.

디바이스 코드 흐름

디바이스 코드 흐름은 입력이 쉽지 않은 디바이스나 로컬에서 스크립트를 실행할 때 효과적입니다. 휴대폰이나 PC 브라우저처럼 다른 디바이스에서 대화형으로 인증할 수 있습니다.

PowerShell에서 디바이스 코드 흐름을 사용하는 방법은 다음과 같습니다.

1. 다음 명령을 실행하여 디바이스 코드 인증을 시작합니다.

   Connect-MgGraph -Scopes "User.Read.All" -DeviceCode

2. PowerShell에 코드와 URL이 표시됩니다. 아무 디바이스에서나 브라우저로 해당 URL을 엽니다.
3. PowerShell에 표시된 코드를 입력하고 Microsoft 365 계정으로 로그인합니다.
4. 인증이 성공하면 PowerShell이 액세스 토큰을 가져오고 세션을 연결합니다.

💡 디바이스 코드 흐름은 보안과 사용 편의성의 균형을 맞춥니다. 스크립트에 자격 증명을 포함하지 않아도 되며, 수동 또는 반자동 작업에 적합합니다.

인증서 기반 흐름

인증서 기반 흐름은 사용자 상호 작용 없이 실행되는 자동화 스크립트에 적합합니다. 클라이언트 비밀 대신 인증서를 사용하여 앱의 ID를 증명합니다. 이 방식은 비밀 유출과 관련된 위험을 줄여 줍니다.

이 흐름을 사용하려면 다음 단계를 따르십시오.

1. Azure AD에 앱을 등록하고 인증서 및 암호에서 인증서를 업로드합니다.
2. 스크립트를 실행하는 컴퓨터에 인증서를 안전하게 저장합니다.
3. 인증서 지문(thumbprint), 클라이언트 ID, 테넌트 ID를 지정하여 PowerShell로 토큰을 요청합니다.

다음은 PowerShell에서 인증서를 사용해 토큰을 가져오는 방법을 간략하게 보여 주는 예제입니다.

$tenantId = "YOUR_TENANT_ID"
$clientId = "YOUR_CLIENT_ID"
$certThumbprint = "YOUR_CERT_THUMBPRINT"
$cert = Get-Item Cert:\CurrentUser\My\$certThumbprint
$body = @{
    grant_type = "client_credentials"
    client_id = $clientId
    scope = "https://graph.microsoft.com/.default"
    client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    client_assertion = New-JwtToken -Certificate $cert -TenantId $tenantId -ClientId $clientId
}
$tokenResponse = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -Body $body
$accessToken = $tokenResponse.access_token

⚠️ 인증서를 관리할 때는 주의가 필요합니다. 개인 키를 보호하고, 보안을 유지하려면 인증서를 정기적으로 교체하십시오.

관리 ID(Managed Identity) 흐름

관리 ID 흐름은 Azure Virtual Machines, Azure Functions, Azure Automation과 같은 Azure 서비스 내에서 PowerShell 및 Graph API 스크립트를 실행할 때 가장 효과적입니다. Azure가 리소스에 ID를 자동으로 할당하므로 자격 증명을 직접 관리할 필요가 없습니다.

관리 ID를 사용해 액세스 토큰을 가져오려면 다음 단계를 따르십시오.

1. Azure 리소스에서 관리 ID(시스템 할당 또는 사용자 할당)를 사용하도록 설정합니다.
2. Microsoft Graph PowerShell 또는 Graph Explorer를 통해 Azure AD에서 이 ID에 필요한 Microsoft Graph API 권한을 할당합니다.
3. PowerShell을 사용하여 로컬 Azure 인스턴스 메타데이터 서비스(IMDS)에 토큰을 요청합니다.

관리 ID를 통해 토큰을 가져오는 PowerShell 코드 예제는 다음과 같습니다.

$resource = "https://graph.microsoft.com"
$tokenAuthUri = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource"
$headers = @{ Metadata = "true" }
$response = Invoke-RestMethod -Method Get -Uri $tokenAuthUri -Headers $headers
$accessToken = $response.access_token

🔐 관리 ID 흐름을 사용하면 스크립트에 비밀을 저장할 필요가 없습니다. Azure 환경 내에서 안전하고 원활한 인증을 제공합니다.

PowerShell + Graph API로 API 호출하기

PowerShell + Graph API로 API를 호출하면 Microsoft 365 서비스를 효과적으로 다룰 수 있습니다. API와 올바르게 통신하려면 HTTP 요청을 구성하는 방법을 이해하는 것이 필수적입니다.

HTTP 요청 구성

Microsoft Graph API와 상호 작용할 때는 HTTP 요청을 올바르게 구성해야 합니다. HTTP 요청의 주요 구성 요소는 다음과 같습니다.

• 액세스 토큰 가져오기: 획득한 토큰을 헤더에 사용합니다.
• 헤더 설정: Content-Type: application/json 및 Authorization: Bearer $accessToken을 포함하여 필요한 헤더를 설정합니다.
• GET/POST 요청: 원하는 Microsoft Graph API 엔드포인트에 명시적으로 요청을 보냅니다.

Invoke-RestMethod 사용하기

Invoke-RestMethod cmdlet을 사용하면 Microsoft Graph API와의 통신이 간단해집니다. HTTP 요청을 보내고 응답을 간편하게 받을 수 있습니다. 동작 방식과 제한 사항을 간략히 살펴보면 다음과 같습니다.

자주 사용하는 API 엔드포인트

Microsoft 365 관리 작업에 자주 사용되는 Microsoft Graph API 엔드포인트가 여러 개 있습니다. 가장 많이 사용되는 항목은 다음과 같습니다.

API 출력 관리하기

JSON 응답 이해하기

Microsoft Graph API와 상호 작용하면 데이터가 JSON 형식으로 반환됩니다. JSON(JavaScript Object Notation)은 가볍고 읽기 쉬운 형식입니다. 데이터를 효과적으로 다루려면 JSON 응답을 이해하는 것이 매우 중요합니다. 일반적인 JSON 응답은 다음과 같습니다.

{
  "id": "1",
  "displayName": "John Doe",
  "mail": "john.doe@example.com"
}

JSON을 PowerShell 객체로 변환하기

PowerShell에서 JSON 데이터를 다루려면 PowerShell 객체로 변환해야 합니다. 이렇게 변환하면 데이터를 손쉽게 조작할 수 있습니다. 이를 위해 ConvertFrom-Json cmdlet을 사용할 수 있습니다. 작동 방식은 다음과 같습니다.

$jsonData = '{"id": "1", "displayName": "John Doe", "mail": "john.doe@example.com"}'
$powerShellObject = $jsonData | ConvertFrom-Json

이제 $powerShellObject에는 $powerShellObject.displayName처럼 직접 접근할 수 있는 속성이 들어 있습니다.

데이터 필터링 및 서식 지정

PowerShell 객체에 데이터를 담았다면 요구 사항에 맞게 필터링하고 서식을 지정할 수 있습니다. PowerShell에는 출력 데이터를 세분화하는 다양한 기법이 있습니다. 예를 들어 API 호출 시 OData 쿼리 매개 변수를 사용하면 Microsoft Graph API에서 결과를 직접 필터링할 수 있습니다.

결과 내보내기

PowerShell 스크립트의 결과를 내보내는 것은 효과적인 데이터 관리에 필수적입니다. 출력은 CSV, JSON, XML 등 다양한 형식으로 저장할 수 있습니다. 예를 들어 다음과 같이 사용자 세부 정보를 내보낼 수 있습니다.

$users = Get-MgUser -All
$users | Select-Object DisplayName, Mail | Export-Csv -Path "Users.csv" -NoTypeInformation

모범 사례 및 문제 해결

오류 및 API 제한 처리

Microsoft Graph API를 사용할 때 오류는 종종 테넌트별 설정 또는 권한 문제에서 발생합니다. 많은 사용자가 인터넷에서 내려받은 스크립트를 환경에 맞게 수정하지 않고 실행하여 실패를 겪습니다. 또한 Microsoft Graph는 서비스를 보호하기 위해 속도 제한을 적용합니다. 스크립트가 너무 많은 요청을 너무 빠르게 보내면 API는 429 상태 코드를 반환합니다. 이때는 Retry-After 헤더를 확인하고, 제시된 시간만큼 기다린 후 다시 시도해야 합니다.

자격 증명 보호

Microsoft 365 작업을 자동화할 때 자격 증명을 보호하는 것은 매우 중요합니다. 애플리케이션의 보안 ID를 만들려면 앱 등록과 관리 ID를 사용하십시오. 가능하면 클라이언트 비밀을 스크립트 안에 일반 텍스트로 저장하지 마십시오.

스크립트 최적화

효율적인 스크립트는 시간을 절약하고 리소스 사용량을 줄입니다. $select 쿼리 매개 변수를 적용해 필요한 속성만 가져오고, 일괄 처리 메커니즘을 활용하며, 깔끔한 페이지 매김 처리기로 자동화 루프를 설계하십시오.

PowerShell과 Microsoft Graph API로 관리 ID 흐름을 익히면 클라우드 자동화에 접근하는 방식이 근본적으로 달라집니다. 정적 비밀을 없애고 클라우드 네이티브 ID를 採用하면 엔터프라이즈를 보호하는 탄력적이고 보안성이 높은 워크플로를 구축할 수 있습니다. 이러한 전략과 최신 클라우드 관리에 관한 실무 논의를 더 듣고 싶다면 관련 에피소드 Use Managed Identity with PowerShell for Microsoft Graph를 꼭 확인하십시오. 오늘 샌드박스 테넌트에서 이 예제들을 직접 실험해 보고 자동화 프레임워크를 한 단계 발전시켜 보십시오!

자주 묻는 질문

PowerShell이란 무엇인가요?

PowerShell은 명령줄 셸과 스크립팅 언어를 결합한 Microsoft의 작업 자동화 프레임워크로, 시스템 관리와 클라우드 운영을 간소화합니다.

Microsoft Graph API란 무엇인가요?

Microsoft Graph API는 사용자, 그룹, 메일, 디렉터리 구성 등 Microsoft 365 전반의 데이터와 서비스에 접근하기 위한 통합 RESTful 엔드포인트입니다.

Microsoft Graph PowerShell 모듈은 어떻게 설치하나요?

PowerShell 7 환경에서 Install-Module Microsoft.Graph -Scope CurrentUser를 실행하면 모듈을 설치할 수 있습니다.

위임된 권한과 애플리케이션 권한의 차이는 무엇인가요?

위임된 권한은 앱이 로그인한 사용자를 대신하여 작동하도록 허용하는 반면, 애플리케이션 권한은 활성 사용자 컨텍스트 없이 백그라운드 실행을 허용합니다.

API 속도 제한은 어떻게 처리하나요?

429 상태 코드를 받으면 항상 응답 헤더에서 Retry-After 값을 확인하고, 스크립트에 지수 백오프(exponential backoff) 재시도 로직을 구현하십시오.

OAuth 2.0이란 무엇입니까?

OAuth 2.0은 애플리케이션이 사용자의 자격 증명을 노출하지 않고도 보호된 API를 호출할 수 있도록 액세스 토큰을 안전하게 획득하게 해 주는 권한 부여(authorization) 프레임워크입니다.

Linux에서 PowerShell을 사용할 수 있습니까?

네! PowerShell은 완전한 크로스 플랫폼을 지원하며 Windows, macOS, Linux에서 네이티브로 실행됩니다.

PowerShell에서 데이터를 내보내려면 어떻게 합니까?

보고 형식 요구 사항에 따라 Export-Csv 또는 ConvertTo-Json 같은 cmdlet을 사용하면 구조화된 데이터를 손쉽게 내보낼 수 있습니다.