엔드포인트 참조: 에이전트 ID HTTP API용 SDK Microsoft Entra

이 문서에서는 AgentID용 Microsoft Entra SDK에서 노출하는 HTTP 엔드포인트에 대한 전체 참조를 제공합니다.

API 사양

OpenAPI 사양: /openapi/v1.json(개발 환경) 및 리포지토리에서 사용할 수 있습니다. https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

이를 사용하여 다음을 수행합니다.

• 클라이언트 코드 생성
• 요청 유효성 검사
• 사용 가능한 엔드포인트 검색

엔드포인트 개요

Authentication

모든 토큰 획득 및 유효성 검사 엔드포인트는 명시적으로 인증되지 않은 것으로 표시되지 않는 한 헤더에 Authorization 전달자 토큰이 필요합니다.

GET /AuthorizationHeader/Graph
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

토큰은 구성된 Microsoft Entra ID 설정(테넌트, 대상 그룹, 발급자, 사용하도록 설정된 경우 범위)에 대해 유효성을 검사합니다.

/Validate

인바운드 전달자 토큰의 유효성을 검사하고 해당 클레임을 반환합니다.

요청

GET /Validate HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

성공적인 응답(200)

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "claims": {
    "aud": "api://your-api-id",
    "iss": "https://sts.windows.net/tenant-id/",
    "iat": 1234567890,
    "nbf": 1234567890,
    "exp": 1234571490,
    "acr": "1",
    "appid": "client-id",
    "appidacr": "1",
    "idp": "https://sts.windows.net/tenant-id/",
    "oid": "user-object-id",
    "tid": "tenant-id",
    "scp": "access_as_user",
    "sub": "subject",
    "ver": "1.0"
  }
}

오류 예제

// 400 Bad Request - No token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "No token found"
}

// 401 Unauthorized - Invalid token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Unauthorized",
  "status": 401
}

/AuthorizationHeader/{serviceName}

구성된 다운스트림 API에 대한 액세스 토큰을 획득하고 권한 부여 헤더 값으로 반환합니다. 사용자 전달자 토큰이 인바운드로 제공되면 OBO(위임됨)가 사용됩니다. 그렇지 않으면 앱 컨텍스트 패턴이 적용됩니다(사용하도록 설정된 경우).

Path 매개 변수

• serviceName – 구성의 다운스트림 API 이름

쿼리 매개 변수

표준 재정의

에이전트 ID

규칙:

• AgentUsername 또는 AgentUserId 필요 AgentIdentity (사용자 에이전트).
• AgentUsername 는 AgentUserId 상호 배타적입니다.
• AgentIdentity alone = 자율 에이전트입니다.
• AgentIdentity + 사용자 인바운드 토큰 = 위임된 에이전트입니다.

예시

기본 요청:

GET /AuthorizationHeader/Graph HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

응답

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

PoP/SHR 응답:

{
  "authorizationHeader": "PoP eyJ0eXAiOiJhdCtqd3QiLCJhbGc..."
}

/AuthorizationHeaderUnauthenticated/{serviceName}

인바운드 사용자 토큰과 동일한 /AuthorizationHeader/{serviceName} 동작 및 매개 변수가 필요하지 않습니다. 사용자 컨텍스트 없이 앱 전용 또는 자율/에이전트 ID 획득에 사용됩니다. 사용자 토큰의 유효성을 검사하는 오버헤드를 방지합니다.

요청

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

응답

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

/DownstreamApi/{serviceName}

액세스 토큰을 획득하고 다운스트림 API에 대한 HTTP 요청을 수행합니다. 다운스트림 응답에서 상태 코드, 헤더 및 본문을 반환합니다. 사용자 OBO, 앱 전용 또는 에이전트 ID 패턴을 지원합니다.

Path 매개 변수

• serviceName – 구성된 다운스트림 API 이름입니다.

추가 쿼리 매개 변수(매개 변수 추가 /AuthorizationHeader )

요청 본문 전달

본문은 변경되지 않은 상태로 전달됩니다.

POST /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

{ 
  "subject": "Hello", 
   "body": { "contentType": "Text", "content": "Hello world" } 
}

응답

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "content": "{\"@odata.context\":\"...\",\"displayName\":\"...\"}"
}

오류 미러 /AuthorizationHeader 및 다운스트림 API 오류 상태 코드

/DownstreamApiUnauthenticated/{serviceName}

인바운드 사용자 토큰과 동일 /DownstreamApi/{serviceName} 하지만 유효성은 검사되지 않습니다. 앱 전용 또는 자율 에이전트 작업에 사용합니다.

/healthz

기본 상태 프로브 엔드포인트입니다.

응답

정상(200):

HTTP/1.1 200 OK

비정상(503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

OpenAPI 3.0 사양을 반환합니다(개발 환경에만 해당). 다음을 수행합니다.

• 클라이언트 코드 생성
• 요청 유효성 검사
• 엔드포인트 검색

일반적인 오류 패턴

잘못된 요청(400)

누락된 서비스 이름:

// 400 Bad Request - Missing service name
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "Service name is required" }

// 400 Bad Request - Invalid agent combination
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "AgentUsername and AgentUserId are mutually exclusive" }

// 401 Unauthorized - Invalid token
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Unauthorized", "status": 401 }

// 403 Forbidden - Missing scope
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden", "status": 403, "detail": "The scope 'access_as_user' is required" }

// 404 Not Found - Service not configured
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "Downstream API 'UnknownService' not configured" }

// 500 Internal Server Error - Token acquisition failure
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "Failed to acquire token for downstream API" }

MSAL 오류 예제

{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "MSAL.NetCore.invalid_grant: AADSTS50076: Due to a configuration change ...", "extensions": { "errorCode": "invalid_grant", "correlationId": "..." } }

전체 재정의 참조

optionsOverride.Scopes=<scope>     # Repeatable
optionsOverride.RequestAppToken=<true|false>
optionsOverride.BaseUrl=<url>
optionsOverride.RelativePath=<path>
optionsOverride.HttpMethod=<method>
optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>
optionsOverride.AcquireTokenOptions.AuthenticationScheme=<scheme>
optionsOverride.AcquireTokenOptions.CorrelationId=<guid>
optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>
optionsOverride.AcquireTokenOptions.PopClaims=<json>
optionsOverride.CustomHeader.<Name>=<value>

AgentIdentity=<agent-client-id>
AgentUsername=<user-upn>            # Requires AgentIdentity
AgentUserId=<user-object-id>        # Requires AgentIdentity

재정의의 예

범위 재정의:

GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

속도 제한

에이전트 ID에 대한 Microsoft Entra SDK 자체는 속도 제한을 적용하지 않습니다. 유효 한도는 다음과 같습니다.

1. Microsoft Entra ID 토큰 서비스 제한(SDK 캐시 토큰으로 발생하지 않아야 합니다).
2. 다운스트림 API 제한
3. 토큰 캐시 효율성(취득 볼륨 감소)

모범 사례

1. 임시 재정의보다 구성을 선호합니다.
2. 서비스 이름을 정적이고 선언적으로 유지합니다.
3. 일시적인 오류에 대한 재시도 정책 구현(HTTP 500/503).
4. 호출하기 전에 에이전트 매개 변수의 유효성을 검사합니다.
5. 서비스 간 추적을 위한 상관 관계 ID를 기록합니다.
6. 토큰 획득 대기 시간 및 오류 비율을 모니터링합니다.
7. 오케스트레이션 플랫폼에서 상태 프로브를 사용합니다.

관련 콘텐츠

• 구성 참조
• 에이전트 ID
• 권한 부여 헤더 유효성 검사
• 다운스트림 API 호출