Microsoft Entra 에이전트 ID 위한 AI 기반 설정

Microsoft Entra 에이전트 ID 온보딩에는 여러 단계가 포함됩니다. 에이전트 ID 블루프린트 만들기, 자격 증명 구성, 식별자 URI 및 범위 설정, 블루프린트 보안 주체 만들기, 그리고 에이전트 ID 프로비저닝이 여기에 포함됩니다. 각 단계에는 고유한 필수 구성 요소, 유효성 검사 및 의사 결정 지점이 있습니다.

이 AI 기반 설정은 AI 코딩 에이전트(예: VS Code의 GitHub Copilot)를 사용하여 사용자를 대신하여 단계를 실행하여 이 전체 워크플로를 자동화합니다. 여러 설명서 페이지 간을 탐색하고 명령을 수동으로 실행하는 대신 AI 에이전트에 단일 명령 파일을 제공하고 대화형으로 프로세스를 안내합니다. 이 명령 파일은 기술로 사용할 수 있으며 두 가지 이상의 방법으로 액세스할 수 있습니다.

혜택

AI 기반 설정은 수동 워크플로에 비해 다음과 같은 몇 가지 이점을 제공합니다.

• 단일 진입점: 하나의 명령 파일은 여러 설명서 페이지 간에 이동해야 하는 필요성을 대체합니다. AI 에이전트는 순서대로 단계를 수행하고 전환을 자동으로 처리합니다.
• 인증된 필수 구성 요소 유효성 검사: AI 에이전트는 올바른 Microsoft Entra 역할이 있는지, 필요한 도구 및 그래프 모듈이 설치되었는지, API를 호출하기 전에 필요한 권한이 관리자 동의로 구성되어 있는지 확인합니다.
• 스마트 기본값 및 자동 검색: AI 에이전트는 테넌트에 기존 사용자 정보 및 리소스 세부 정보를 쿼리한 다음 구성 입력을 수집할 때 이러한 값을 제안으로 사용합니다.
• 파생 명명 규칙: 에이전트에 대한 단일 표시 이름을 제공하고 AI 에이전트는 일관된 패턴을 사용하여 모든 관련 리소스 이름(청사진, 청사진 보안 주체, 에이전트 ID, 식별자 URI)을 파생합니다.
• 인라인 오류 처리: 명령이 실패하면 AI 에이전트가 오류를 분석하고 수정을 제안하며 문제 해결 설명서를 통해 검색하도록 요구하는 대신 다시 시도합니다. 이 오류 처리는 권한 전파 지연 및 OData 헤더 요구 사항과 같은 에이전트 ID 관련 문제에서 특히 유용합니다.
• Idempotent 작업: AI 에이전트는 리소스를 만들기 전에 리소스가 이미 있는지 확인하므로 이전 시도가 중단된 경우 설치 프로그램을 다시 실행할 수 있습니다.

사전 요구 사항

시작하기 전에 다음 필수 구성 요소가 있는지 확인합니다.

필요한 도구

AI 기반 설정에는 터미널 액세스 권한이 있는 AI 코딩 에이전트가 필요합니다.

• Visual Studio CodeGitHub Copilot 및 GitHub Copilot Chat 확장이 설치되어 있습니다.
• VS Code에서 직접 Microsoft Entra 에이전트 ID 기능을 제공하는 GitHub Copilot for Azure 확장.

이 기술은 두 개의 프로비저닝 경로를 지원합니다. 기본 설정에 따라 하나 또는 둘 다를 설치합니다.

• PowerShell 경로: PowerShell 7 이상 및 Microsoft Graph PowerShell SDK. Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force을 사용하여 설치합니다.
• Python path: Python 3.8 이상과 azure-identity 및 requests. pip install azure-identity requests을 사용하여 설치합니다.

필요한 계정 및 권한

• 다음 역할 중 하나를 가진 경우, Microsoft Entra 테넌트에 대한 액세스 권한:
  • 에이전트 아이디 개발자는 에이전트 아이디 청사진과 에이전트 아이디를 생성합니다. 에이전트 ID 청사진의 소유자는 에이전트 ID 역할 없이 해당 청사진에 대한 에이전트 ID를 만들 수 있습니다.
  • 에이전트 ID 리소스에 대한 전체 관리 액세스를 위한 에이전트 ID 관리자입니다.

• 권한 부여에 대한 추가 역할:
  • 특권 역할 관리자는 Microsoft Graph 애플리케이션 권한을 부여합니다.
  • Cloud 애플리케이션 관리자 또는 애플리케이션 관리자는 Microsoft Graph의 위임된 권한을 부여할 수 있습니다.

필요한 Microsoft Graph 권한

사용하는 클라이언트(PowerShell 또는 사용자 지정 앱 등록)는 다음 위임된 권한으로 권한을 부여해야 합니다.

필수 에이전트 코드(선택 사항)

에이전트 ID가 필요한 작업 에이전트 프로젝트(Python, Node.js또는 .NET)가 이미 있는 경우 프로젝트 디렉터리를 사용할 수 있습니다. 아직 청사진이 없다면, 독립적으로 설정을 완료할 수 있습니다.

Get started

AI 단계별 설정은 모든 단계 및 유효성 검사를 포함하는 단일 명령 파일인 기술을 사용합니다. 다음 두 가지 방법 중 하나로 기술에 액세스할 수 있습니다.

• Azure용 GitHub Copilot 확장을 통해(권장): GitHub Copilot for Azure VS Code 확장을 설치합니다. Microsoft Entra 에이전트 ID 기술은 Copilot Chat 에이전트 ID 설정에 대해 묻는 경우 자동으로 활성화됩니다.
• GitHub에서 직접: Copilot Chat 프롬프트에서 이를 참조하여 독립 실행형 Microsoft Entra 에이전트 ID 스킬을 사용합니다.

1단계: VS Code에서 프로젝트 열기

Visual Studio Code 에이전트 프로젝트 디렉터리(또는 작업 디렉터리)를 엽니다.

2단계: 에이전트 모드에서 GitHub Copilot Chat 열기

GitHub Copilot Chat 패널을 열고 Agent 모드로 전환합니다. 에이전트 모드는 GitHub Copilot 터미널 명령을 실행하고, 파일을 읽고, AI 기반 설정에 필요한 환경과 상호 작용하는 기능을 제공합니다.

3단계: 단계별 설정 시작

Azure 확장에 대한 GitHub Copilot 설치되어 있는 경우 Copilot 에이전트 ID를 설정하도록 요청합니다. 다음은 그 예입니다.

@azure Use the Agent ID Skill to set up an agent identity blueprint and create agent identities for my project using Microsoft Entra Agent ID.

확장이 없는 경우 GitHub 직접 기술을 참조합니다.

Follow the steps in https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/skills/entra-agent-id/SKILL.md

AI 에이전트는 기술을 읽고 안내된 설정을 시작합니다. 이 작업은 단계를 순차적으로 수행합니다.

1. 필수 구성 요소 유효성 검사: Microsoft Entra 역할을 확인하고 필요한 도구(Microsoft Graph 모듈이 있는 PowerShell 또는 azure-identity 사용 Python)가 설치되어 있는지 확인합니다.
2. Authenticate: 필요한 범위를 사용하여 Microsoft Graph 연결합니다. PowerShell의 경우, 이 기능은 명시적 위임 범위와 함께 Connect-MgGraph를 사용합니다. Python 경우 클라이언트 자격 증명으로 전용 앱 등록을 사용합니다.
3. 에이전트 ID 청사진 만들기: 표시 이름을 수집하고, 스폰서(사용자)를 식별하고, 입력한 엔드포인트(/applications/microsoft.graph.agentIdentityBlueprint)를 사용해 청사진을 만들고, appId를 기록합니다.
4. 자격 증명 구성: 관리 ID(프로덕션용) 또는 클라이언트 암호(로컬 개발/테스트용)를 사용하여 페더레이션 ID 자격 증명을 청사진에 추가합니다.
5. 식별자 URI 및 범위 구성: 에이전트 간 통신 및 사용자 간 통신에 대한 OAuth2 권한 범위를 설정하고 identifierUrisapi://{appId} 만듭니다.
6. 청사진 보안 주체 만들기: 형식화된 엔드포인트를 사용하여 청사진에 대한 서비스 주체를 만듭니다(보안 주체는 자동으로 생성 되지 않으며 명시적으로 수행해야 합니다).
7. 에이전트 ID 만들기: 청사진 아래에 하나 이상의 에이전트 ID 서비스 주체를 만듭니다.

에이전트가 기술을 읽을 때 확장 또는 기타 도구를 설치하라는 메시지가 표시될 수 있습니다. 프롬프트에 따라 환경이 준비되었는지 확인합니다.

4단계: 프롬프트에 응답

AI 에이전트는 특정 지점에서 일시 중지하여 사용자로부터 입력을 수집합니다.

• 표시 이름: 에이전트 ID 청사진의 표시 이름입니다(예: "Contoso 예산 에이전트").
• 스폰서: 에이전트에 대한 책임이 있는 사용자 또는 그룹입니다. 기본값으로 현재 로그인한 사용자가 설정됩니다.
• 소유자: 청사진을 기술적으로 변경할 수 있는 사용자 또는 서비스 주체입니다. 선택 사항이지만 권장됩니다.
• 자격 증명 유형: 관리 ID(프로덕션에 권장) 또는 인증서 또는 클라이언트 비밀(로컬 개발용)을 사용할지 여부입니다.
• 에이전트 ID 수: 이 청사진에서 만들 에이전트 ID 수입니다.
• 파생 값 확인: 리소스를 만들기 전에 자동 생성된 이름 및 URI를 검토합니다.

5단계: Microsoft Entra 관리 센터 확인

설치가 완료되면 AI 에이전트는 리소스를 확인하는 방법에 대한 지침을 제공합니다.

1. Microsoft Entra 관리 센터에 적어도 Agent ID 개발자로 로그인합니다.
2. Entra ID>Agents>Agent ID로 이동하여 새 에이전트 ID 청사진과 그 아래에 생성된 에이전트 ID를 확인합니다.
3. 청사진에 올바른 자격 증명, 식별자 URI 및 범위가 구성되어 있는지 확인합니다.

AI 기반 설정에서 다루는 내용

AI 기반 설정은 에이전트 ID 통합의 다음 단계를 자동화합니다.

AI 지원 설정이 처리하는 일반적인 함정

에이전트 ID API에는 AI 기반 설정이 자동으로 감지하고 해결하는 몇 가지 요구 사항이 있지만 명백한 요구 사항은 아닙니다. 문제를 디버그하거나 설정을 확장해야 하는 경우 이러한 문제를 이해하는 것이 도움이 될 수 있습니다.

OData-Version 헤더가 필요합니다.

모든 에이전트 ID API 호출에는 헤더가 OData-Version: 4.0 필요합니다. 이 헤더를 생략하면 API가 에이전트 ID 청사진 대신 표준 애플리케이션을 자동으로 만들 수 있습니다. AI 기반 설정에는 항상 이 헤더가 포함됩니다. 또한 이 기술은 속성이 있는 원시 /applications/microsoft.graph.agentIdentityBlueprint/applications 엔드포인트 대신 형식화된 엔드포인트(예: @odata.type)를 사용하여 이 문제의 위험을 줄입니다.

청사진 주체가 자동으로 생성되지 않음

에이전트 ID 청사진(POST /applications)을 만든다고 해서 청사진의 주체(서비스 주체)가 자동으로 생성되는 것은 아닙니다. 청사진 원칙이 없으면 모든 후속 에이전트 ID 생성이 실패합니다.

400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

AI 기반 설정은 항상 청사진 바로 후에 청사진 주요 요소를 만듭니다. 또한 idempotent 케이스를 처리합니다. 이전 실행에서 청사진을 만들었지만 주체를 만들기 전에 충돌한 경우, 설치가 이 이벤트를 감지하여 누락된 주체를 만듭니다.

스폰서가 필요합니다.

스폰서는 필수이며 사용자, 동적 멤버 자격을 가진 그룹 또는 통합 그룹이 될 수 있습니다. 청사진과 에이전트 ID 생성 모두에 필드가 sponsors@odata.bind 필요합니다. 이 항목이 없으면 다음을 받게 됩니다.

400: No sponsor specified. Please provide at least one sponsor.

AI 기반 설정은 스폰서 할당에는 사용자 개체만 허용하며 /users/{objectId} 형식의 URL만 사용합니다. /directoryObjects/ 또는 /servicePrincipals/는 사용하지 않습니다. 설정은 현재 사용자의 개체 ID를 확인하고 기본 스폰서로 사용합니다. 지원되는 그룹 청사진의 후원자로 할당하려면 Microsoft Graph API 직접 사용합니다.

권한 전파에는 30~120초가 소요됩니다.

에이전트 ID 권한에 대한 관리자 동의를 부여한 후에는 새로 부여된 권한이 토큰에 즉시 표시되지 않습니다. 토큰 엔드포인트는 캐시된 클레임을 제공하며 전파에는 30-120초 이상이 걸릴 수 있습니다.

AI 기반 설정은 403이 수신될 때 지수 백오프를 사용하여 작업을 다시 시도하여 최근 권한 변경을 처리합니다. 이 작업을 수동으로 스크립팅하는 경우 재시도 논리를 구현합니다.

# Example: Retry with backoff after admin consent
$maxRetries = 5
for ($i = 0; $i -lt $maxRetries; $i++) {
    try {
        # Attempt the operation
        $result = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 403 -and $i -lt $maxRetries - 1) {
            $wait = 20 * ($i + 1)
            Write-Host "Permission not yet propagated. Retrying in $wait seconds..."
            Start-Sleep -Seconds $wait
            # Disconnect and reconnect to force a fresh token
            Disconnect-MgGraph
            Connect-MgGraph -Scopes $scopes
        } else {
            throw
        }
    }
}

에이전트 ID에 암호 자격 증명을 가질 수 없습니다.

에이전트 ID는 애플리케이션 개체를 백업하지 않는 서비스 주체입니다. 에이전트 ID에 passwordCredential 직접 추가하려고 시도하면 다음이 발생합니다.

PropertyNotCompatibleWithAgentIdentity

자격 증명은 개별 에이전트 ID가 아니라 청사진에서 구성해야 합니다. 관리 ID 페더레이션(권장)을 사용하거나 청사진에 비밀 및 인증서를 추가하고, 에이전트 ID는 가장 방식을 통해 자격 증명을 상속합니다.

식별자 URI를 명시적으로 설정해야 합니다.

청사진의 identifierUris 필드는 기본적으로 설정되지 않습니다. 이 범위가 없으면 OAuth2 범위 api://{appId}/.default 가 확인되지 않으며 에이전트에 대한 토큰 획득이 실패합니다. AI 기반 설정은 항상 범위 설정 단계의 일부로 이 값을 구성합니다.

청사진을 위한 연합 신원 자격 증명 경로

관리 ID 페더레이션에 대한 페더레이션된 ID 자격 증명(FIC)을 추가할 때 에이전트별 API 경로를 사용해야 합니다.

POST /applications/{blueprint-obj-id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials

/applications/{id}/federatedIdentityCredentials 경로를 사용하는 것은 에이전트 ID 청사진에 대해 작동할 수 있지만 지원되지 않으며 권장되지 않습니다.

토큰 발급자 엔드포인트 버전에 따라 다름

에이전트 백 엔드에서 토큰의 유효성을 검사하는 경우 다음과 같은 변형에 유의하세요.

• v1.0 토큰은 발급자를 사용합니다. https://sts.windows.net/{tenant-id}/
• v2.0 토큰은 발급자를 사용합니다. https://login.microsoftonline.com/{tenant-id}/v2.0

토큰 유효성 검사 논리에서 두 형식을 모두 적용합니다.

Troubleshooting

AI 에이전트가 터미널 명령을 실행하지 않음

AI 에이전트가 명령을 설명하지만 실행하지 않는 경우 GitHub Copilot Chat Agent 모드를 사용하고 있는지 확인합니다. 요청 및 편집 모드에는 터미널 액세스 권한이 없습니다.

AI 에이전트가 유효성 검사 단계를 건너뜁니다.

명령 파일은 엄격한 단계 순서를 적용합니다. AI 에이전트가 단계를 건너뛰는 것처럼 보이면 처음부터 지침을 따르도록 미리 알려 줍니다. 다음은 그 예입니다.

Please start from Step 1 in the setup instructions and work through each step in order.

403-금지됨으로 그래프 명령 실패

403 오류의 가장 일반적인 원인은 다음과 같습니다.

• Azure CLI 또는 DefaultAzureCredential 토큰 사용: Azure CLI 토큰에는 에이전트 ID API가 완전히 거부하는 Directory.AccessAsUser.All 포함됩니다. 명시적 위임 범위와 함께 Connect-MgGraph를 사용하거나 client_credentials가 포함된 전용 앱 등록을 사용하세요. 필수 구성 요소에서 인증 경고를 참조하세요.
• 권한 전파 지연: 관리자 동의 후 1~2분 후에 기다렸다가 다시 시도합니다. AI 기반 설정은 재시도 논리를 사용하여 이를 자동으로 처리합니다.
• 관리자 동의 누락: Microsoft Entra 관리 센터의 앱 등록>에서 클라이언트 앱 >API 권한에 필요한 권한이 관리자 동의를 받았는지 확인하십시오.

청사진 만들기는 성공하지만 표준 애플리케이션을 반환합니다.

이 결과는 헤더가 OData-Version: 4.0 누락될 때 발생합니다. 이 문제를 방지하려면 원시 /applications/microsoft.graph.agentIdentityBlueprint/applications 엔드포인트 대신 형식화된 엔드포인트(@odata.type)를 사용합니다.

"‘Blueprint Principal이 존재하지 않음’ 오류로 인해 에이전트 아이덴티티 생성 실패"

청사진의 주요 항목은 청사진 후 별도의 단계로 생성해야 합니다. Run:

POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

{
  "appId": "<your-blueprint-app-id>"
}

자격 증명 수명 정책 오류

테넌트에는 클라이언트 비밀의 최대 수명을 제한하는 자격 증명 수명 주기 정책이 있을 수 있습니다. 암호를 추가할 때 자격 증명 수명에 관한 오류가 발생할 경우, 조직의 정책에 맞게 endDateTime 값을 줄이십시오.

구성 값을 변경해야 합니다.

설치 후 구성 값을 변경해야 하는 경우 다음을 수행할 수 있습니다.

• 업데이트된 값을 사용하여 AI 기반 설정을 다시 실행합니다. 멱등적 검사는 이미 올바르게 존재하는 리소스를 생략합니다.
• Microsoft Graph PowerShell을 사용하여 PATCH 요청으로 특정 속성을 업데이트합니다.

다음 단계

• 에이전트 ID 만들기 및 삭제
• 에이전트 ID의 관리 관계(소유자, 스폰서 및 관리자)
• 에이전트 ID, 서비스 주체 및 애플리케이션
• 에이전트 신원 청사진 개념