Azure Active Directory reporting API에 액세스하기 위한 필수 구성 요소

  • 아티클

Azure AD(Azure Active Directory) Reporting API는 일련의 REST API를 통해 데이터에 프로그래밍 방식으로 액세스합니다. 여러 프로그래밍 언어 및 도구에서 이러한 API를 호출할 수 있습니다. Reporting API는 OAuth 를 사용하여 Web API에 대한 액세스 권한을 부여합니다. Microsoft Graph API는 많은 양의 활동 데이터를 끌어오기 위한 목적으로 설계되지 않았습니다. API를 사용하여 많은 양의 활동 데이터를 끌어오면 페이지 매김 및 성능 문제가 발생할 수 있습니다.

이 문서에서는 Microsoft Graph가 Azure Portal 및 PowerShell을 통해 Azure AD 보고 API에 액세스할 수 있도록 하는 방법을 설명합니다.

역할 및 라이선스 요구 사항

API를 통해 보고 데이터에 액세스하려면 다음 역할 중 하나가 있어야 합니다.

  • 보안 Reader
  • 보안 관리자
  • 전역 관리자

테넌트에 대한 로그인 보고서에 액세스하려면 Azure AD 테넌트에 연결된 Azure AD Premium P1 또는 P2 라이선스가 있어야 합니다. 디렉터리 유형이 Azure AD B2C인 경우 기타 라이선스 요구 사항 없이 API를 통해 로그인 보고서에 액세스할 수 있습니다.

스크립트를 사용하여 보고 API에 액세스하는 경우에도 등록이 필요합니다. 등록하면 인증 호출에 필요한 애플리케이션 ID가 제공되고, 이를 통해 코드에서 토큰을 받을 수 있습니다. Azure AD 보고 API에 액세스하도록 디렉터리를 구성하려면 필요한 역할 중 하나에서 Azure Portal에 로그인해야 합니다.

중요

이 같은 관리자 권한이 있는 자격 증명 하에서 실행 중인 애플리케이션은 매우 강력할 수 있으므로, 애플리케이션의 ID 및 비밀 자격 증명을 안전하게 보관해야 합니다.

Azure Portal을 통해 Microsoft Graph API를 사용하도록 설정

애플리케이션이 사용자 개입 없이 Microsoft Graph에 액세스할 수 있도록 하려면 Azure AD에 애플리케이션을 등록한 다음, Microsoft Graph API에 권한을 부여해야 합니다. 이 문서에서는 Azure Portal에서 따라야 하는 단계를 설명합니다.

Azure AD 애플리케이션 등록

팁

이 문서의 단계는 시작 지점이 되는 포털에 따라 약간 다를 수 있습니다.

  1. Microsoft Entra 관리 센터에 보안 읽기 권한자 이상의 권한으로 로그인합니다.

  2. ID>애플리케이션>앱 등록으로 이동합니다.

  3. 새 등록을 선택합니다.

    새 등록 단추가 강조 표시된 앱 등록 페이지의 스크린샷

  4. 애플리케이션 등록 페이지에서 다음을 수행합니다.

    1. 애플리케이션에 Reporting API application과 같은 이름을 지정합니다.
    2. 지원되는 계정 유형의 경우 이 조직 디렉터리 계정의 계정만을 선택합니다.
    3. 리디렉션 URI 섹션의 목록에서 웹을 선택하고 https://localhost를 입력합니다.
    4. 등록을 선택합니다.

    이 단계에서 값을 입력하는 애플리케이션 등록 페이지를 보여주는 스크린샷입니다.

권한 부여

Azure AD 보고 API에 액세스하려면 앱 디렉터리 데이터 읽기 및 Microsoft Graph API 대한 모든 감사 로그 데이터 읽기 권한을 부여해야 합니다.

  1. ID>애플리케이션>앱 등록으로 이동합니다.

  2. 사용 권한 추가를 선택합니다.

    API 권한 메뉴 옵션 및 권한 추가 단추 스크린샷

  3. Microsoft Graph>애플리케이션 권한을 선택합니다.

  4. Directory.Read.All, AuditLog.Read.All, Policy.Read.ConditionalAccess를 추가한 다음 권한 추가 단추를 선택합니다.

    • 필요한 쿼리를 실행하기 위해 더 많은 권한이 필요한 경우 지금 쿼리를 추가하거나 Microsoft Graph에서 필요에 따라 권한을 수정할 수 있습니다.
    • 자세한 내용은 Graph 탐색기에서 작업을 참조하세요.

    애플리케이션 권한을 선택할 수 있는 요청 API 권한 페이지를 보여 주는 스크린샷

  5. 보고 API 애플리케이션 - API 권한 페이지에서 기본 디렉터리에 대한 관리자 동의 부여를 선택합니다.

    관리자 동의 부여를 선택할 수 있는 보고 API 애플리케이션 API 권한 페이지를 보여 주는 스크린샷

Microsoft Graph Explorer를 사용하여 보고서에 액세스

앱 등록이 구성되면 Microsoft Graph에서 활동 로그 쿼리를 실행할 수 있습니다.

  1. 보안 읽기 권한자 역할을 사용하여 https://graph.microsoft.com에 로그인합니다.

    • 적절한 역할에 로그인했는지 확인해야 할 수 있습니다.
    • Microsoft Graph의 오른쪽 위 모서리에서 프로필 아이콘을 선택합니다.

  2. 다음 쿼리 중 하나를 사용하여 활동 로그에 액세스하기 위해 Microsoft Graph 사용을 시작합니다.

    • GET https://graph.microsoft.com/v1.0/auditLogs/directoryAudits
    • GET https://graph.microsoft.com/v1.0/auditLogs/signIns
    • Microsoft Graph 활동 로그 쿼리에 대한 자세한 내용은 활동 보고서 API 개요를 참조하세요.

    Microsoft Graph의 활동 로그 GET 쿼리 스크린샷

Microsoft Graph PowerShell을 사용하여 보고서 액세스

PowerShell을 사용하여 Azure AD 보고 API에 액세스하려면 몇 가지 구성 설정을 수집해야 합니다. 이러한 설정은 앱 등록 프로세스의 일부로 만들어졌습니다.

  • 테넌트 ID
  • 클라이언트 앱 ID
  • 클라이언트 암호 또는 인증서

Reporting API에 대한 호출을 구성하는 경우 이 값이 필요합니다. 인증서는 더 안전하므로 사용하는 것이 좋습니다.

  1. ID>애플리케이션>앱 등록으로 이동합니다.
  2. 만든 애플리케이션을 엽니다.
  3. 디렉터리(테넌트) ID를 복사합니다.
  4. 애플리케이션(클라이언트) ID를 복사합니다.
  5. 인증서 및 비밀>인증서>인증서 업로드로 이동하여 인증서의 공개 키 파일을 업로드합니다.

다음으로 방금 수집한 구성 설정을 사용하여 인증해야 합니다. PowerShell을 열고 다음 명령을 실행하여 자리 표시자를 사용자의 정보로 바꿉니다.

Connect-MgGraph -ClientID YOUR_APP_ID -TenantId YOUR_TENANT_ID -CertificateName YOUR_CERT_SUBJECT ## Or -CertificateThumbprint instead of -CertificateName

Microsoft Graph PowerShell cmdlet:

프로그래밍 방식 액세스 API:

Azure Active Directory Reporting API에서 오류 해결

Microsoft Graph 베타 엔드포인트에 액세스하는 동안 500 HTTP 내부 서버 오류 - 현재 Microsoft Graph 베타 엔드포인트를 지원하지 않습니다. Microsoft Graph v1.0 엔드포인트를 사용하여 활동 로그에 액세스해야 합니다.

  • GET https://graph.microsoft.com/v1.0/auditLogs/directoryAudits
  • GET https://graph.microsoft.com/v1.0/auditLogs/signIns

오류: 테넌트가 B2C가 아니거나 테넌트에 Premium 라이선스가 없음: 로그인 보고서에 액세스하려면 Azure Active Directory P1(Premium 1) 라이선스가 필요합니다. 로그인에 액세스하는 동안 이 오류 메시지가 표시되면 Azure AD P1 라이선스를 사용하여 테넌트에게 사용이 허가되었는지 확인합니다.

오류: 사용자가 허용된 역할에 없음: API를 사용하여 감사 로그 또는 로그인에 액세스하는 동안 이 오류 메시지가 표시되면 Azure Active Directory 테넌트의 보안 읽기 권한자 또는 보고서 구독자 역할이 계정에 포함되어 있는지 확인합니다.

오류: Azure AD ‘디렉터리 데이터 읽기’ 또는 ‘모든 감사 로그 데이터 읽기’ 권한이 누락된 애플리케이션: 이 문서의 권한 부여 섹션을 다시 검토하여 사용 권한이 제대로 설정되었는지 확인합니다.

다음 단계