엔드포인트 참조: AgentID HTTP API용 Microsoft Entra SDK

이 문서에서는 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.AgentID.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(위임됨)가 사용됩니다. 그렇지 않으면 앱 컨텍스트 패턴이 적용됩니다(사용하도록 설정된 경우).

경로 매개 변수

• 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 패턴을 지원합니다.

경로 매개 변수

• 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...

속도 제한

AgentID용 Microsoft Entra SDK 자체는 속도 제한을 적용하지 않습니다. 유효 한도는 다음과 같습니다.

1. Microsoft Entra ID 토큰 서비스 제한(SDK가 토큰을 캐시하면 안 됨)
2. 다운스트림 API 제한
3. 토큰 캐시 효율성(취득 볼륨 감소)

모범 사례

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

또한 참조하십시오

• 구성 참조
• 에이전트 ID
• 시나리오: 권한 부여 헤더 유효성 검사
• 시나리오: 권한 부여 헤더 가져오기
• 시나리오: 다운스트림 API 호출