Uç nokta başvurusu: Aracı Kimliği HTTP API'si için Microsoft Entra SDK

Bu belge, AgentID için Microsoft Entra SDK'sı tarafından kullanıma sunulan HTTP uç noktaları için tam başvuru sağlar.

API belirtimi

OpenAPI belirtimi: /openapi/v1.json (geliştirme ortamı) ve depoda kullanılabilir: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

Bunu şunlar için kullanın:

İstemci kodu oluşturma
İstekleri doğrulama
Kullanılabilir uç noktaları bulma

Uç noktaya genel bakış

Bitiş noktası	Yöntemler	Amaç	Kimlik Doğrulaması Gerekli
`/Validate`	GET	Gelen taşıyıcı belirtecini doğrulama ve talepleri döndürme	Yes
`/AuthorizationHeader/{serviceName}`	GET	Gelen belirteci doğrulama (varsa) ve aşağı akış API'si için yetkilendirme üst bilgisi alma	Yes
`/AuthorizationHeaderUnauthenticated/{serviceName}`	GET	Gelen kullanıcı belirteci olmadan yetkilendirme üst bilgisi (uygulama veya aracı kimliği) alma	Yes
`/DownstreamApi/{serviceName}`	GET, POST, PUT, PATCH, DELETE	Otomatik belirteç alma ile gelen belirteci doğrulama (varsa) ve aşağı akış API'lerini çağırma	Yes
`/DownstreamApiUnauthenticated/{serviceName}`	GET, POST, PUT, PATCH, DELETE	Aşağı akış API'sini çağırma (yalnızca uygulama veya aracı kimliği)	Yes
`/healthz`	GET	Sistem durumu yoklaması (canlılık/hazır olma)	Hayı
`/openapi/v1.json`	GET	OpenAPI 3.0 belgesi	Hayır (yalnızca Geliştirme)

Authentication

Kimliği doğrulanmamış olarak açıkça işaretlenmediği sürece tüm belirteç alma ve doğrulama uç noktaları üst bilgide Authorization taşıyıcı belirteci gerektirir:

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

Belirteçler yapılandırılmış Microsoft Entra ID ayarlarına (kiracı, hedef kitle, veren, etkinleştirildiyse kapsamlar) karşı doğrulanır.

`/Validate`

Gelen taşıyıcı belirtecini doğrular ve taleplerini döndürür.

İstek

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

Başarılı yanıt (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"
  }
}

Hata örnekleri

// 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}`

Yapılandırılan aşağı akış API'si için bir erişim belirteci alır ve bunu yetkilendirme üst bilgisi değeri olarak döndürür. Gelen bir kullanıcı taşıyıcı belirteci sağlanırsa, OBO (temsilci) kullanılır; aksi takdirde uygulama bağlam düzenleri uygulanır (etkinse).

Path parametresi

serviceName – Yapılandırmadaki aşağı akış API'sinin adı

Sorgu parametreleri

Standart geçersiz kılmalar

Parametre	Türü	Description	Example
`optionsOverride.Scopes`	string[]	Yapılandırılmış kapsamları geçersiz kılma (yinelenebilir)	`?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read`
`optionsOverride.RequestAppToken`	Boolean	Yalnızca uygulama belirtecini zorlama (OBO atla)	`?optionsOverride.RequestAppToken=true`
`optionsOverride.AcquireTokenOptions.Tenant`	String	Kiracı kimliğini geçersiz kıl	`?optionsOverride.AcquireTokenOptions.Tenant=tenant-guid`
`optionsOverride.AcquireTokenOptions.PopPublicKey`	String	PoP/SHR'yi etkinleştirme (base64 ortak anahtarı)	`?optionsOverride.AcquireTokenOptions.PopPublicKey=base64key`
`optionsOverride.AcquireTokenOptions.PopClaims`	String	Ek PoP talepleri (JSON)	`?optionsOverride.AcquireTokenOptions.PopClaims={"nonce":"abc"}`

Aracı Kimliği

Parametre	Türü	Description	Example
`AgentIdentity`	String	Aracı uygulaması (istemci) kimliği	`?AgentIdentity=11111111-2222-3333-4444-555555555555`
`AgentUsername`	String	Kullanıcı asıl adı (temsilci aracı)	`?AgentIdentity=<id>&AgentUsername=user@contoso.com`
`AgentUserId`	String	Kullanıcı nesne kimliği (temsilci aracı)	`?AgentIdentity=<id>&AgentUserId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`

Kurallar:

AgentUsername veya AgentUserId (kullanıcı aracısı) gerektirir AgentIdentity .
AgentUsername ve AgentUserId birbirini dışlar.
AgentIdentity alone = otonom aracı.
AgentIdentity + kullanıcı gelen belirteci = temsilci aracı.

Örnekler

Temel istek:

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

Yanıt

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

PoP/SHR yanıtı:

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

`/AuthorizationHeaderUnauthenticated/{serviceName}`

Gelen kullanıcı belirteciyle aynı davranış ve parametreler /AuthorizationHeader/{serviceName} beklenmiyor. Kullanıcı bağlamı olmadan yalnızca uygulama veya otonom/aracı kimliği alımı için kullanılır. Kullanıcı belirtecini doğrulama yükünden kaçınır.

İstek

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Yanıt

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

`/DownstreamApi/{serviceName}`

Bir erişim belirteci alır ve aşağı akış API'sine bir HTTP isteği gerçekleştirir. Aşağı akış yanıtından durum kodunu, üst bilgileri ve gövdeyi döndürür. Kullanıcı OBO,yalnızca uygulama veya aracı kimliği desenlerini destekler.

Path parametresi

serviceName – Aşağı akış API'si adı yapılandırıldı.

Ek sorgu parametreleri (parametrelere `/AuthorizationHeader` ek olarak)

Parametre	Türü	Description	Example
`optionsOverride.HttpMethod`	String	HTTP yöntemini geçersiz kılma	`?optionsOverride.HttpMethod=POST`
`optionsOverride.RelativePath`	String	Yapılandırılmış BaseUrl'e göreli yol ekleme	`?optionsOverride.RelativePath=me/messages`
`optionsOverride.CustomHeader.<Name>`	String	Özel üst bilgiler ekleme	`?optionsOverride.CustomHeader.X-Custom=value`

İstek gövdesi iletme

Gövde değiştirilmeden geçirilir:

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" } 
}

Yanıt

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

Hatalar yansıtma /AuthorizationHeader artı aşağı akış API'si hata durum kodları.

`/DownstreamApiUnauthenticated/{serviceName}`

/DownstreamApi/{serviceName} Aynı ancak gelen kullanıcı belirteci doğrulanmaz. Yalnızca uygulama veya otonom aracı işlemleri için kullanın.

/healthz

Temel sistem durumu yoklaması uç noktası.

Yanıt

Sağlıklı (200):

HTTP/1.1 200 OK

İyi durumda değil (503):

HTTP/1.1 503 Service Unavailable

`/openapi/v1.json`

OpenAPI 3.0 belirtimini döndürür (yalnızca geliştirme ortamı). Şu şekilde kullanın:

İstemci kodu oluşturma
İstekleri doğrulama
Uç noktaları bulma

Yaygın hata desenleri

Hatalı istek (400)

Eksik hizmet adı:

// 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 hata örneği

{ "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": "..." } }

Tam geçersiz kılma başvurusu

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

Geçersiz kılma örnekleri

Kapsamları geçersiz kıl:

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

Hız sınırlaması

Aracı Kimliği için Microsoft Entra SDK'sı hız sınırları getirmez. Geçerli sınırlar şunlardan gelir:

Microsoft Entra ID belirteç hizmeti azaltma (SDK belirteci önbelleğe alırken gerçekleşmemelidir)
Aşağı akış API'leri sınırları
Belirteç önbelleği verimliliği (alma hacmini azaltır)

En iyi uygulamalar

Geçici geçersiz kılmalar yerine yapılandırmayı tercih edin.
Hizmet adlarını statik ve bildirim temelli tutun.
Geçici hatalar için yeniden deneme ilkeleri uygulayın (HTTP 500/503).
Çağırmadan önce aracı parametrelerini doğrulayın.
Hizmetler arasında izleme için günlük bağıntı kimlikleri.
Belirteç alma gecikme süresini ve hata oranlarını izleyin.
Düzenleme platformlarında sistem durumu yoklamalarını kullanın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-19

Uç nokta başvurusu: Aracı Kimliği HTTP API'si için Microsoft Entra SDK

API belirtimi

Uç noktaya genel bakış

Authentication

/Validate

İstek

Başarılı yanıt (200)

Hata örnekleri

/AuthorizationHeader/{serviceName}

Path parametresi

Sorgu parametreleri

Standart geçersiz kılmalar

Aracı Kimliği

Örnekler

Yanıt

/AuthorizationHeaderUnauthenticated/{serviceName}

İstek

Yanıt

/DownstreamApi/{serviceName}

Path parametresi

Ek sorgu parametreleri (parametrelere /AuthorizationHeader ek olarak)

İstek gövdesi iletme

Yanıt

/DownstreamApiUnauthenticated/{serviceName}

/healthz

Yanıt

/openapi/v1.json

Yaygın hata desenleri

Hatalı istek (400)

MSAL hata örneği

Tam geçersiz kılma başvurusu

Geçersiz kılma örnekleri

Hız sınırlaması

En iyi uygulamalar

İlgili içerik

Geri Bildirim

Ek kaynaklar

`/Validate`

`/AuthorizationHeader/{serviceName}`

`/AuthorizationHeaderUnauthenticated/{serviceName}`

`/DownstreamApi/{serviceName}`

Ek sorgu parametreleri (parametrelere `/AuthorizationHeader` ek olarak)

`/DownstreamApiUnauthenticated/{serviceName}`

`/openapi/v1.json`