AgentID용 Microsoft Entra SDK: 개요

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

Kubernetes, Docker를 사용한 컨테이너화된 서비스 또는 Azure의 최신 마이크로 서비스를 사용하여 빌드하는 경우 에이전트ID용 Microsoft Entra SDK는 클라우드 네이티브 애플리케이션에서 인증 및 권한 부여를 처리하는 표준화된 방법을 제공합니다.

AgentID용 Microsoft Entra SDK란?

AgentID용 Microsoft Entra SDK는 인증 및 권한 부여를 위해 HTTP API를 통해 애플리케이션과 통신하여 기술 스택에 관계없이 일관된 통합 패턴을 제공합니다. 애플리케이션 코드에 ID 논리를 직접 포함하는 대신 AgentID용 Microsoft Entra SDK는 표준 HTTP 요청을 통해 토큰 관리, 유효성 검사 및 API 호출을 처리합니다.

이 방법을 사용하면 일관된 인증 패턴을 유지하면서 Python, Node.js, Go, Java 등으로 다양한 서비스를 작성할 수 있는 다각형 마이크로 서비스 아키텍처를 사용할 수 있습니다.

일반적인 아키텍처는 다음과 같습니다.

Client Application → Your Web API → Microsoft Entra SDK for AgentID → Microsoft Entra ID

최신 컨테이너 이미지 및 버전 태그는 시작하려면 컨테이너 이미지를 참조하세요.

Security

AgentID용 Microsoft Entra SDK 배포가 보안 작업에 대한 모범 사례를 따르는지 확인합니다. SDK는 권한이 없는 액세스를 방지하기 위해 네트워크 액세스가 제한된 컨테이너화된 환경에서 실행되어야 합니다. SDK API를 공개적으로 노출하면 무단 토큰 획득과 같은 보안 취약성이 발생할 수 있습니다.

네트워크, 자격 증명 및 런타임 보안 권장 사항에 대한 모범 사례를 확인하려면 보안 모범 사례를 참조하세요.

빠른 시작

AgentID용 Microsoft Entra SDK를 시작하려면 다음 단계를 수행하는 것이 좋습니다.

1. 배포 선택 - Kubernetes, Docker 또는 AKS 선택
2. 설정 구성 - 환경 변수 설정
3. 시나리오 선택 - 안내된 예제 따르기
4. 프로덕션에 배포 - 보안 모범 사례 검토

주요 이점

아키텍처는 비즈니스 논리와 ID 문제를 구분하여 다음과 같은 이점을 제공합니다.

AgentID 또는 Microsoft.Identity.Web용 Microsoft Entra SDK를 사용하는 경우

두 방법 중에서 선택하는 방법에 대한 자세한 지침은 Microsoft.Identity.Web과의 비교 를 참조하세요.

토큰 유효성 검사

AgentID용 Microsoft Entra SDK는 Microsoft Entra ID에서 발급한 액세스 토큰 및 ID 토큰의 유효성을 검사하고, Microsoft Entra ID의 공개 키에 대한 서명을 확인하고, 만료 시간을 확인하고, 토큰이 애플리케이션용인지 확인합니다. 유효성이 검사되면 사용자 클레임, 역할 및 범위를 추출하여 애플리케이션 논리 내에서 정보에 입각한 권한 부여 결정을 내릴 수 있습니다.

토큰 획득/권한 부여 헤더 만들기

• On-Behalf-Of OAuth 2.0 흐름 - 사용자 환경을 하위 API들에 위임
• 클라이언트 자격 증명 - 애플리케이션-애플리케이션 인증
• 관리 ID - 네이티브 Azure 서비스 인증
• 에이전트 ID - 자율 또는 위임된 에이전트 패턴

다운스트림 API 호출

• 자동으로 토큰 획득 및 연결
• 선택적 요청 재정의(범위, 메서드, 헤더)
• 서명된 HTTP 요청(PoP/SHR) 지원

시나리오 및 자습서

다음 가이드는 에이전트ID용 Microsoft Entra SDK를 애플리케이션에 통합하는 방법을 보여주는 실용적인 코드 예제를 포함하는 포괄적인 단계별 자습서입니다. 각 시나리오는 다양한 프로그래밍 언어 및 프레임워크에 맞게 조정된 완전한 요청/응답 예제, 코드 조각 및 구현 패턴을 제공합니다.

아키텍처 패턴

클라이언트가 Web API를 호출하는 일반적인 흐름인 API는 HTTP 엔드포인트를 통해 AgentID용 Microsoft Entra SDK에 ID 작업을 위임합니다. SDK는 /Validate 엔드포인트를 사용하여 인바운드 토큰의 유효성을 검사하고, /AuthorizationHeader 및 /AuthorizationHeaderUnauthenticated를 사용하여 토큰을 획득하며, /DownstreamApi 및 /DownstreamApiUnauthenticated를 사용하여 다운스트림 API를 직접 호출할 수 있습니다.

다음 코드 조각에 설명된 아키텍처와 함께 토큰 발급 및 Open ID Connect 메타데이터 검색을 위해 Microsoft Entra ID와 상호 작용합니다.

%%{init: {
  "theme": "base",
  "themeVariables": {
    "background": "#121212",
    "primaryColor": "#1E1E1E",
    "primaryBorderColor": "#FFFFFF",
    "primaryTextColor": "#FFFFFF",
    "textColor": "#FFFFFF",
    "lineColor": "#FFFFFF",
    "labelBackground": "#000000"
  }
}}%%
flowchart LR
    classDef dnode fill:#1E1E1E,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    linkStyle default stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

    client[Client Application]:::dnode -->| Bearer over HTTP | webapi[Web API]:::dnode
    subgraph Pod / Host
        webapi -->|"/Validate<br/>/AuthorizationHeader/{name}<br/>/DownstreamApi/{name}"| sidecar[Microsoft Entra SDK for AgentID]:::dnode
    end
    sidecar -->|Token validation & acquisition| entra[Microsoft Entra ID]:::dnode

지원 및 리소스

다음 리소스는 일반적인 질문에 대한 문제 및 답변을 해결하는 데 도움이 되는 포괄적인 지침과 도움말을 제공합니다.

추가 도움말:

• Microsoft-identity-web 리포지토리에서 문제 보고
• Microsoft Entra ID 문제 해결 가이드 확인

추가 리소스

• Microsoft Entra ID 설명서
• Microsoft Identity Platform 설명서
• Microsoft Identity Web 리포지토리
• Kubernetes 설명서
• Docker 설명서