BYOK를 사용하는 Azure 관리 ID

이 가이드에서는 DefaultAzureCredential 라이브러리의 사용하여 Copilot SDK를 통해 Azure AI Foundry 모델로 인증하는 방법을 보여 줍니다.

작동 방식

Azure AI Foundry의 OpenAI 호환 엔드포인트는 정적 API 키 대신 Entra ID의 전달자 토큰을 허용합니다. 패턴은 다음과 같습니다.

DefaultAzureCredential 범위에 대한 토큰을 얻으려면 https://cognitiveservices.azure.com/.default를 사용합니다.
BYOK 공급자 구성에서 bearer_token로 토큰을 전달합니다.
토큰이 만료되기 전에 새로 고침(토큰은 일반적으로 ~1시간 동안 유효)

다이어그램: 설명된 프로세스를 보여 주는 시퀀스 다이어그램

Python 예제

사전 요구 사항

pip install github-copilot-sdk azure-identity

기본 사용법

import asyncio
import os

from azure.identity import DefaultAzureCredential
from copilot import CopilotClient
from copilot.session import PermissionHandler, ProviderConfig

COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"

async def main():
    # Get a token using Managed Identity, Azure CLI, or other credential chain
    credential = DefaultAzureCredential()
    token = credential.get_token(COGNITIVE_SERVICES_SCOPE).token

    foundry_url = os.environ["AZURE_AI_FOUNDRY_RESOURCE_URL"]

    client = CopilotClient()
    await client.start()

    session = await client.create_session(
        on_permission_request=PermissionHandler.approve_all,
        model="gpt-4.1",
        provider=ProviderConfig(
            type="openai",
            base_url=f"{foundry_url.rstrip('/')}/openai/v1/",
            bearer_token=token,  # Short-lived bearer token
            wire_api="responses",
        ),
    )

    response = await session.send_and_wait("Hello from Managed Identity!")
    print(response.data.content)

    await client.stop()

asyncio.run(main())

장기 실행 애플리케이션에 대한 토큰 새로 고침

전달자 토큰은 만료됩니다(일반적으로 ~1시간 후). 서버 또는 장기 실행 에이전트의 경우 각 세션을 만들기 전에 토큰을 새로 고칩니다.

from azure.identity import DefaultAzureCredential
from copilot import CopilotClient
from copilot.session import PermissionHandler, ProviderConfig

COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"

class ManagedIdentityCopilotAgent:
    """Copilot agent that refreshes Entra ID tokens for Azure AI Foundry."""

    def __init__(self, foundry_url: str, model: str = "gpt-4.1"):
        self.foundry_url = foundry_url.rstrip("/")
        self.model = model
        self.credential = DefaultAzureCredential()
        self.client = CopilotClient()

    def _get_provider_config(self) -> ProviderConfig:
        """Build a ProviderConfig with a fresh bearer token."""
        token = self.credential.get_token(COGNITIVE_SERVICES_SCOPE).token
        return ProviderConfig(
            type="openai",
            base_url=f"{self.foundry_url}/openai/v1/",
            bearer_token=token,
            wire_api="responses",
        )

    async def chat(self, prompt: str) -> str:
        """Send a prompt and return the response text."""
        # Fresh token for each session
        session = await self.client.create_session(
            on_permission_request=PermissionHandler.approve_all,
            model=self.model,
            provider=self._get_provider_config(),
        )

        response = await session.send_and_wait(prompt)
        await session.disconnect()

        return response.data.content if response else ""

Node.js/TypeScript 예제

import { DefaultAzureCredential } from "@azure/identity";
import { CopilotClient } from "@github/copilot-sdk";

const credential = new DefaultAzureCredential();
const tokenResponse = await credential.getToken(
  "https://cognitiveservices.azure.com/.default"
);

const client = new CopilotClient();

const session = await client.createSession({
  model: "gpt-4.1",
  provider: {
    type: "openai",
    baseUrl: `${process.env.AZURE_AI_FOUNDRY_RESOURCE_URL}/openai/v1/`,
    bearerToken: tokenResponse.token,
    wireApi: "responses",
  },
});

const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

.NET 예제

using Azure.Identity;
using GitHub.Copilot;

var credential = new DefaultAzureCredential();
var token = await credential.GetTokenAsync(
    new Azure.Core.TokenRequestContext(
        new[] { "https://cognitiveservices.azure.com/.default" }));

await using var client = new CopilotClient();
var foundryUrl = Environment.GetEnvironmentVariable("AZURE_AI_FOUNDRY_RESOURCE_URL");

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-4.1",
    Provider = new ProviderConfig
    {
        Type = "openai",
        BaseUrl = $"{foundryUrl!.TrimEnd('/')}/openai/v1/",
        BearerToken = token.Token,
        WireApi = "responses",
    },
});

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello from Managed Identity!" });
Console.WriteLine(response?.Data.Content);

환경 구성

변수	Description	Example
`AZURE_AI_FOUNDRY_RESOURCE_URL`	Azure AI Foundry 리소스 URL	`https://myresource.openai.azure.com`

API 키 환경 변수가 필요하지 않습니다. 인증은 자동으로 지원하는 다음을 DefaultAzureCredential통해 처리됩니다.

Azure 호스팅 앱의 경우 관리 ID(시스템 할당 또는 사용자 할당):
Azure CLI(az login): 로컬 개발용
환경 변수 (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET): 서비스 주체의 경우
워크로드 ID: Kubernetes의 경우

전체 자격 증명 체인 에 대한 DefaultAzureCredential 설명서를 참조하세요.

이 패턴을 사용하는 경우

Scenario	Recommendation
관리 ID를 사용하는 Azure 호스팅 앱
✅ 이 패턴 사용
기존 Azure AD 서비스 주체가 있는 앱
✅ 이 패턴 사용
`az login`를 사용한 로컬 개발
✅ 이 패턴 사용
정적 API 키를 사용하는 비 Azure 환경
BYOK(사용자 고유의 키 가져오기) 사용
GitHub Copilot 구독 사용 가능
GitHub OAuth 설정 사용