AgentID용 Microsoft Entra SDK에 대한 질문과 대답

일반적인 질문

AgentID용 Microsoft Entra SDK란?

AgentID용 Microsoft Entra SDK는 토큰 획득, 유효성 검사 및 보안 다운스트림 API 호출을 처리하는 컨테이너화된 웹 서비스입니다. 애플리케이션과 함께 도우미 컨테이너로 실행되므로 ID 논리를 전용 서비스로 오프로드할 수 있습니다. SDK에서 ID 작업을 중앙 집중화하여 각 서비스에 복잡한 토큰 관리 논리를 포함할 필요가 없으므로 코드 중복 및 잠재적인 보안 취약성을 줄일 수 있습니다.

Microsoft.Identity.Web 대신 AgentID용 Microsoft Entra SDK를 사용하는 이유는 무엇인가요?

자세한 지침은 비교 가이드 를 참조하세요.

AgentID용 Microsoft Entra SDK를 프로덕션에 사용할 수 있나요?

예, SDK는 프로덕션 준비가 완료되었습니다. 최신 릴리스 상태 및 프로덕션 준비 지침은 GitHub 릴리스 를 참조하세요.

컨테이너 이미지를 사용할 수 있나요?

예 - 사용 가능한 이미지 및 버전 태그는 설치 가이드 를 참조하세요.

Kubernetes 외부에서 SDK를 실행할 수 있나요?

예 - Docker Compose 또는 기타 컨테이너 환경(Docker Compose, Azure Container Instances, AWS ECS/Fargate, 독립 실행형 Docker)에서 SDK를 실행하는 방법에 대한 지침은 설치 가이드 를 참조하세요.

SDK에서 사용하는 네트워크 포트는 무엇인가요?

기본 포트: 5000 (구성 가능)

SDK는 외부에 노출되지 않는 애플리케이션 컨테이너에서만 액세스할 수 있어야 합니다.

배치

배포 옵션, 리소스 요구 사항 및 Docker Compose 및 Kubernetes와 같은 컨테이너 플랫폼과의 통합에 대해 알아봅니다.

리소스 요구 사항은 무엇인가요?

예 - 리소스 요구 사항에 대한 설치 가이드 를 참조하세요.

Docker Compose에서 SDK를 사용할 수 있나요?

예 - Docker Compose에 대한 설치 가이드 예제를 참조하세요.

관리 ID를 사용하여 AKS에 배포하려면 어떻게 해야 하나요?

예 - 관리 ID 섹션을 사용하여 AKS(Azure Kubernetes Service)의 설치 가이드를 따릅니다.

구성 / 설정

자격 증명, 다운스트림 API 및 요청 재정의를 포함하여 배포 요구 사항에 맞게 SDK 설정을 구성합니다.

구성 참조를 사용할 수 있나요?

예 - 자세한 구성 옵션은 구성 참조를 참조 하세요.

클라이언트 비밀 또는 인증서를 사용해야 하나요?

클라이언트 비밀보다 인증서를 선호합니다.

• 더 안전한
• 회전하기 쉽습니다.
• Microsoft에서 권장

최적: Azure에서 관리 ID 사용(자격 증명 필요 없음)

지침 은 보안 모범 사례를 참조하세요.

여러 다운스트림 API를 구성할 수 있나요?

예. 고유한 섹션을 사용하여 각 섹션을 구성합니다.

DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
DownstreamApis__Graph__Scopes: "User.Read"

DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
DownstreamApis__MyApi__Scopes: "api://myapi/.default"

요청당 구성을 재정의하려면 어떻게 해야 하나요?

엔드포인트에서 쿼리 매개 변수 사용:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

모든 옵션은 구성 참조 를 참조하세요.

에이전트 ID

에이전트 ID를 사용하면 적절한 컨텍스트 격리 및 범위 지정을 통해 에이전트 애플리케이션이 사용자를 대신하여 자율적으로 또는 사용자를 대신하여 작동할 수 있는 시나리오를 사용할 수 있습니다.

에이전트 ID란?

에이전트 ID를 사용하면 에이전트 애플리케이션이 다음 중 하나의 역할을 하는 시나리오를 사용할 수 있습니다.

• 자율적 - 자체 애플리케이션 컨텍스트에서
• 대화형 - 호출한 사용자를 대신하여

포괄적인 설명서는 에이전트 ID 를 참조하세요.

자율 에이전트 모드는 언제 사용해야 하나요?

다음을 위해 자율 에이전트 모드를 사용합니다.

• 사용자 컨텍스트 없이 일괄 처리
• 백그라운드 작업
• 시스템 대 시스템 작업
• 예약된 작업

예제:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

대화형 에이전트 모드는 언제 사용해야 하나요?

다음을 위해 위임된 에이전트 모드를 사용합니다.

• 대화형 에이전트 애플리케이션
• 사용자를 대신하여 작동하는 AI 도우미
• 사용자 범위 자동화
• 개인 설정된 워크플로

예제:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

AgentIdentity 없이 AgentUsername을 사용할 수 없는 이유는 무엇인가요?

AgentUsername 는 에이전트가 대신 작동하는 사용자를 지정하는 한정자입니다. 사용할 에이전트 컨텍스트를 지정해야 AgentIdentity 합니다. 매개 변수가 없으면 AgentIdentity아무런 의미가 없습니다.

AgentUsername 및 AgentUserId가 상호 배타적인 이유는 무엇인가요?

동일한 사용자를 식별하는 두 가지 방법입니다.

• AgentUsername - UPN(사용자 계정 이름)
• AgentUserId - 개체 ID(OID)

둘 다 허용하면 모호성이 만들어집니다. 시나리오에 맞는 시나리오를 선택합니다.

• 사용자의 UPN이 있는 경우 사용 AgentUsername
• 사용자의 개체 ID가 있는 경우 사용 AgentUserId

API 사용량

SDK는 인증된 흐름과 인증되지 않은 흐름에 대한 지원을 통해 토큰 획득, 유효성 검사 및 다운스트림 API 호출에 대한 여러 HTTP 엔드포인트를 노출합니다.

SDK는 어떤 엔드포인트를 노출하나요?

• /Validate - 토큰 유효성 검사 및 클레임 반환
• /AuthorizationHeader/{serviceName} - 토큰을 사용하여 권한 부여 헤더 가져오기
• /AuthorizationHeaderUnauthenticated/{serviceName} - 인바운드 사용자 토큰 없이 토큰 가져오기
• /DownstreamApi/{serviceName} - 다운스트림 API 직접 호출
• /DownstreamApiUnauthenticated/{serviceName} - 인바운드 사용자 토큰 없이 다운스트림 API 호출
• /healthz - 상태 프로브

자세한 내용은 엔드포인트 참조 를 참조하세요.

인증된 엔드포인트와 인증되지 않은 엔드포인트의 차이점은 무엇인가요?

인증됨: 헤더에 Authorization 전달자 토큰 필요(OBO 흐름의 경우) 인증되지 않음: 인바운드 토큰의 유효성을 검사하지 않음(앱 전용 또는 에이전트 시나리오의 경우)

사용자 토큰의 유효성을 검사하려면 어떻게 해야 하나요?

GET /Validate
Authorization: Bearer <user-token>

응답에는 토큰의 모든 클레임이 포함됩니다.

다운스트림 API에 대한 액세스 토큰을 가져오려면 어떻게 해야 하나요?

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

응답에는 다운스트림 API와 함께 사용할 수 있는 권한 부여 헤더가 포함됩니다.

요청당 HTTP 메서드 또는 경로를 재정의할 수 있나요?

예, 쿼리 매개 변수 사용:

# Override method
GET /DownstreamApi/Graph?optionsOverride.HttpMethod=POST

# Override path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

토큰 캐싱

SDK는 성능을 최적화하고 중복 토큰 획득 요청을 줄이기 위해 메모리에 토큰을 자동으로 캐시합니다.

SDK는 토큰을 캐시하나요?

예 - SDK는 기본적으로 메모리의 토큰을 캐시합니다.

토큰은 얼마나 오래 캐시되는가?

토큰은 만료가 가까워질 때까지 캐시된 다음 자동으로 새로 고쳐집니다. 정확한 기간은 토큰 수명(일반적으로 Entra ID 토큰의 경우 1시간)에 따라 달라집니다.

캐싱을 사용하지 않도록 설정할 수 있나요?

토큰 캐싱은 자동으로 최적화됩니다. 현재 사용하지 않도록 설정하는 옵션은 없습니다.

토큰 캐시가 SDK 인스턴스 간에 공유되는가요?

아니요 - 각 SDK 인스턴스는 자체 메모리 내 캐시를 유지 관리합니다. 고가용성 배포에서 각 Pod에는 독립적인 캐싱이 있습니다.

Security

보안 SDK 배포는 관리 ID 사용, 네트워크 격리 및 적절한 자격 증명 처리를 비롯한 Microsoft Entra ID 및 데이터 보호 모범 사례를 따릅니다.

SDK를 실행해도 안전한가요?

예 - 보안 모범 사례에 대한 보안 모범 사례를 참조하세요.

SDK를 외부에 노출해야 하나요?

Never - SDK는 애플리케이션 컨테이너에서만 액세스할 수 있어야 합니다. 자세한 보안 모범 사례는 보안 모범 사례를 참조하세요.

SDK를 어떻게 보호해야 하나요?

포괄적인 지침 은 보안 모범 사례를 참조하세요.

어떤 자격 증명을 사용해야 하나요?

기본 설정 순서:

1. 관리 ID (Azure) - 가장 안전한 자격 증명 없음
2. 인증서 - 보안, 회전 가능
3. 클라이언트 비밀 - 덜 선호, 보안 자격 증명 모음에 유지

SDK 규정 준수 인증 여부

GitHub 리포지토리에서 현재 준수 정보를 확인합니다.

Performance

SDK 성능은 토큰 캐싱 효율성 및 네트워크 왕복 대기 시간에 따라 달라지며, 캐시된 토큰의 경우 일반적인 응답 시간은 10~50ms 사이입니다.

SDK 사용의 성능 영향은 무엇인가요?

일반적인 HTTP 왕복: 10-50ms

토큰 캐싱은 반복된 획득을 최소화합니다. 첫 번째 요청은 느리고(토큰 획득), 후속 요청은 캐시된 토큰을 사용합니다.

SDK 성능은 In-Process 라이브러리와 어떻게 비교됩니까?

In-Process 라이브러리는 더 빠르지만(네트워크 왕복 없음) SDK는 다음을 제공합니다.

• 언어에 구애받지 않은 액세스
• 중앙 집중식 구성
• 서비스 간 공유 토큰 캐시
• 간소화된 크기 조정

자세한 내용은 비교 가이드 를 참조하세요.

SDK의 크기를 수평으로 조정할 수 있나요?

예. Kubernetes 배포를 사용하여 여러 SDK 복제본을 배포합니다. 각 Pod는 독립적인 토큰 캐싱을 유지 관리합니다.

Migration

Microsoft.Identity.Web에서 SDK로 전환하면 다중 언어 지원, 중앙 집중식 구성 및 서비스 간 간소화의 이점이 있습니다.

Microsoft.Identity.Web에서 AgentID용 Microsoft Entra SDK로 마이그레이션할 수 있나요?

예 - 자세한 마이그레이션 단계는 비교 가이드 를 참조하세요.

Support

문제에 대한 도움말을 보고, 추가 설명서를 찾고, 공식 채널을 통해 커뮤니티 리소스에 액세스합니다.

버그를 보고하는 위치는 어디인가요?

Entra ID 템플릿을 사용하여 GitHub 리포지토리에 문제를 보고합니다.

Troubleshooting

SDK에 문제가 발생하면 문제 해결 가이드의 진단 단계, 일반적인 문제 및 솔루션에 대한 포괄적인 문제 해결 가이드를 참조하세요.

자세한 내용은 어디서 확인할 수 있나요?

또한 참조하십시오

• Microsoft Learn 설명서
• ID 플랫폼 문서
• 에이전트 ID 플랫폼