Gözlemlenebilirlik kimlik doğrulama kurulumu

Agent 365 dışa aktarıcısı, telemetri verilerini dışa aktarırken kimlik doğrulaması yapmak için bir belirteç çözümleyicisine ihtiyaç duyar. Bu kılavuz, .NET, Python ve Node.js genelinde hem Agent 365 özellikli aracılar hem de özel altyapı aracıları dahil olmak üzere Microsoft 365 Aracıları SDK'sı ile oluşturulan aracılar için kurulumu kapsamaktadır.

Dağıtım kurulumu, genel yapılandırma ve Agent SDK dışındaki senaryolar için Microsoft OpenTelemetry Distro bölümüne bakın.

Genel bakış

Aracı türünüze ve jetonları nasıl elde ettiğine bağlı olarak dört farklı kimlik doğrulama senaryosu bulunmaktadır. Belirteç edinme, Adına (OBO) akışı veya Hizmetten Hizmete (S2S) akışı kullanılarak gerçekleştirilebilir. Kurulumunuza uygun senaryoyu seçin:

Senaryo Açıklama
OBO kullanılarak Agent 365 etkinleştirildi Dağıtımın yerleşik AgenticTokenCache öğesi, belirteç edinimini otomatik olarak gerçekleştirir. Özel çözümleyiciye gerek yoktur. Bu, Agent 365 özelliğini kullanan aracılar için önerilen yaklaşımdır.
S2S kullanılarak Agent 365 etkinleştirildi Aracı, aracı kimlik zincirini (getAgenticApplicationToken + Microsoft Kimlik Doğrulama Kitaplıkları (MSAL)) kullanarak bir belirteç edinir. Özel bir TokenResolver gerektirir. OBO kullanılamadığında veya yalnızca uygulama için geçerli belirteçlere ihtiyacınız olduğunda bu yöntemi kullanın.
OBO kullanan özel altyapı Aracı, Azure Bot OAuth aracılığıyla gözlemlenebilirlik API'si kapsamına sahip bir kullanıcı belirteci alır. Özel bir TokenResolver ve bir Azure Bot OAuth bağlantısı gerektirir.
S2S kullanan özel motor Aracı, istemci kimlik bilgilerini kullanarak yalnızca uygulama için geçerli bir belirteç alır. Özel bir TokenResolver gerektirir. Uygulama kayıtları, Standart (aracı temelli olmayan) bir uygulama olmalıdır.

OBO kullanılarak Agent 365 etkinleştirildi

Agent 365 özellikli aracılar, Agent 365 platformundan aracı kimliği (agenticAppId, agenticUserId) ile istekler alır. OBO ile, dağıtımın yerleşik AgenticTokenCache öğesi belirteç alımını otomatik olarak yönetir: herhangi bir özel belirteç çözümleyicisine gerek yoktur.

Ön koşullar

  • Entra uygulama kaydı : İstemci Kimliği, İstemci Gizli Anahtarı ve Kiracı Kimliği içeren bir hizmet sorumlusu (uygulama kayıtları)
  • Temsil edilen API izinleri : Agent365.Observability.OtelWrite (Temsilci) ekleyin, yönetici onayı verin. Ayrıntılı adımlar için İzin verme bölümüne bakın.

Ayarlar

Her turda, aracınız tur bağlamı ile birlikte RegisterObservability işlevini çağırır. Yerleşik önbellek, bir OBO değişimi gerçekleştirmek ve Agent365.Observability.OtelWrite kapsamlı bir belirteç edinmek için AgenticUserAuthorization işleyicisinden gelen kullanıcının yetkili belirtecini kullanır.

Paketler, yapılandırma ve kod örnekleri de dahil olmak üzere tam kurulum yönergeleri için Agent Framework uygulamaları ile aracı temelli belirteç önbelleğe alma bölümüne bakın.

S2S kullanılarak Agent 365 etkinleştirildi

Agent 365 ile uyumlu aracılar, OBO yerine S2S (hizmetten hizmete) kimlik doğrulamasını da kullanabilir. Aracı, iki aşamalı bir aracı kimlik zinciri aracılığıyla kendi hizmet sorumlusu kimliğini kullanarak bir belirteç alır:

  1. getAgenticApplicationToken(tenantId, agentId) : istemci kimlik bilgileri + Birleştirilmiş Yönetilen Kimlik (FMI) yolu
  2. Uygulama belirteci olarak clientAssertion ve kapsam olarak api://9b975845-388f-4429-889e-eab1ef63949c/.default kullanan MSAL acquireTokenForClient

Not

Birleştirilmiş Yönetilen Kimlik (FMI), yönetilen bir kimliğin birleştirilmiş kimlik bilgileri aracılığıyla iş yükü kimlik federasyonuna katıldığı ve kimlikler arasındaki güven ilişkilerine dayalı olarak jeton alışverişini ve gizli anahtar gerektirmeyen kimlik doğrulamayı etkinleştiren bir mimaridir.

Özel bir TokenResolver sağlamalı ve UseS2SEndpoint = true ayarını yapmalısınız.

Ön koşullar

  • Entra uygulama kaydı : İstemci Kimliği, İstemci Gizli Anahtarı ve Kiracı Kimliği içeren bir hizmet sorumlusu (uygulama kayıtları)

  • Uygulama API izinleri : Agent365.Observability.OtelWrite (Uygulama) ekleme, yönetici onayı verme

  • Agent365.Observability.OtelWrite uygulama rolü : Aracının hizmet sorumlusuna, Agent365 Gözlemlenebilirlik kaynağı üzerinde OtelWrite rolünün atanmış olması gerekir. Agent 365 CLI'sini kullanın:

    a365 setup permissions bot --config-dir "<path-to-config-dir>"

    Not

    Rol yayma işleminin tamamlanması birkaç dakika sürebilir. Bu süre zarfında, dışa aktarma bitiş noktasından gelen ilk 401 veya 403 hataları beklenmektedir.

1. adım: Ortam yapılandırması

Aşağıdaki kod örnekleri, özel S2S belirteç akışını etkinleştirmeden önce gerekli bağlantı, kiracı, istemci kimlik bilgileri ve gözlemlenebilirlik aktarıcısı ortam ayarlarının nasıl yapılandırılacağını göstermektedir.

AgenticUserAuthorization işleyicisine gerek yok. S2S, gözlemlenebilirlik kaynağına yönelik bir belirteç almak için manuel aracı kimlik zincirini (get_agentic_application_token + MSAL acquire_token_for_client) kullanır.

CONNECTIONSMAP__0__SERVICEURL=*
CONNECTIONSMAP__0__CONNECTION=SERVICE_CONNECTION

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<your-client-id>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<your-client-secret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

ENABLE_A365_OBSERVABILITY=true
ENABLE_A365_OBSERVABILITY_EXPORTER=true

2. adım: Dağıtımı özel belirteç çözümleyicisiyle yapılandırma

Aşağıdaki örnekler, Agent 365 dışa aktarma özelliğinin nasıl etkinleştirileceğini ve dışa aktarıcının her aracı ve kiracı için S2S belirteçlerini alabilmesi amacıyla özel bir TokenResolver öğesinin nasıl kaydedileceğini göstermektedir.

from microsoft.opentelemetry import use_microsoft_opentelemetry

_token_cache: dict[str, str] = {}

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _token_cache.get(f"{agent_id}:{tenant_id}")

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    a365_use_s2s_endpoint=True,
    a365_enable_observability_exporter=True,
)

3. adım: S2S belirteçini al ve önbelleğe alma

Gelen her ileti için, aracı kimlik zinciri aracılığıyla S2S belirteçini alın ve çözümleyici için önbelleğe alın.

import asyncio
from msal import ConfidentialClientApplication
from microsoft.opentelemetry.a365.core import BaggageBuilder, InvokeAgentScope, InvokeAgentScopeDetails, Request

OBSERVABILITY_S2S_SCOPE = "api://9b975845-388f-4429-889e-eab1ef63949c/.default"

async def get_agentic_s2s_token(connection, tenant_id: str, agent_id: str) -> str:
    # Step 1: Get agentic application token (client_credentials + fmi_path)
    app_token = await connection.get_agentic_application_token(tenant_id, agent_id)
    if not app_token:
        raise ValueError(f"Failed to get agentic app token for agent {agent_id}")

    # Step 2: Exchange for observability-scoped token
    cca = ConfidentialClientApplication(
        client_id=agent_id,
        authority=f"https://login.microsoftonline.com/{tenant_id}",
        client_credential={"client_assertion": app_token},
    )
    result = await asyncio.to_thread(
        lambda: cca.acquire_token_for_client(scopes=[OBSERVABILITY_S2S_SCOPE])
    )
    if not result or "access_token" not in result:
        raise ValueError(f"Token acquisition failed: {result}")
    return result["access_token"]

# In your message handler : use SDK helpers to get agent/tenant from the activity:
@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    # get_agentic_instance_id reads from recipient (SDK convention)
    agent_id = context.activity.get_agentic_instance_id()
    tenant_id = context.activity.get_agentic_tenant_id()

    # Acquire S2S token and cache BEFORE creating spans
    connection = CONNECTION_MANAGER.get_connection("SERVICE_CONNECTION")
    token = await get_agentic_s2s_token(connection, tenant_id, agent_id)
    _token_cache[f"{agent_id}:{tenant_id}"] = token

    # Wrap spans in BaggageBuilder so the exporter can resolve the token
    request = Request(content=user_message, session_id=None)
    with BaggageBuilder().tenant_id(tenant_id).agent_id(agent_id).build():
        invoke_scope = InvokeAgentScope.start(request, InvokeAgentScopeDetails(), agent_details)
        with invoke_scope:
            invoke_scope.record_input_messages([user_message])
            invoke_scope.record_output_messages([response])

Önemli

S2S için manuel iki adımlı akış (get_agentic_application_token + MSAL acquire_token_for_client) gereklidir. AgenticUserAuthorization.get_token(), gözlemlenebilirlik kaynağı api://9b975845-.../.default yerine 5a807f24-.../.default (Bot Framework) kapsamındaki bir belirteci döndürür: S2S uç noktası bunu 401 InvalidAudience ile reddeder.

  • Etkinlikten aracı ve kiracıyı okumak için context.activity.get_agentic_instance_id() ve get_agentic_tenant_id() kullanın (SDK kuralı gereği recipient öğesinden okur).
  • Span oluşturmadan önce S2S belirtecini edinin ve önbelleğe alın. Dışa aktarıcının BatchSpanProcessor öğesi, işleyici tamamlanmadan önce temizleme işlemi gerçekleştirebilir: Belirteç henüz önbelleğe alınmamışsa dışa aktarma işlemi başarısız olur.
  • Dışa aktarıcının belirteçleri hangi aracı ve kiracı için çözümleyeceğini bilmesi adına tüm A365 kapsamlarını BaggageBuilder içine alın. Herhangi bir sorun olmadığında, "Kiracı/aracı kimlikine sahip aralık bulamadık" mesajıyla aralıklar sessizce kaldırılır.

OBO kullanan özel altyapı

Özel motor aracıları, aracı kimlik zinciri yerine Azure Bot OAuth bağlantıları ile standart uygulama kayıtlarını kullanır. OBO'yu kullanarak, aracı, Bot Framework Belirteç Hizmeti tarafından A365 gözlemlenebilirlik API'si için önceden kapsamı belirlenmiş bir kullanıcı belirtecini Azure Bot OAuth aracılığıyla alır. Tek bir getToken veya GetTurnTokenAsync çağrısı, doğru şekilde kapsamlandırılmış belirteci döndürür; bu nedenle exchangeToken kullanmanıza gerek kalmaz.

Ön koşullar

Entra uygulama kaydı, Temsilci API izinleri ile. Agent365.Observability.OtelWrite (Temsilci) ekleme ve yönetici onayı verme

Önemli

Belirteç önbelleğindeki agentId, uygulama kaydının İstemci Kimliği ile eşleşmelidir; özel motor aracıları için mevcut olmayan etkinliğin agenticAppId değeriyle değil. Dışarı aktarma URL'si agentId öğesini içerir ve bir uyumsuzluk HTTP 403 hatasına neden olur.

1. adım: Ortam ve uygulama yapılandırması

Aşağıdaki örnekler, hizmet bağlantı değerleri, kiracı ve istemci ayarları ile gerekli yetkilendirme eşlemeleri dahil olmak üzere, uygulamanızı ve çalışma zamanı ortamınızı nasıl yapılandıracağınızı göstermektedir.

# .env
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<your-client-id>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<your-client-secret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

CONNECTIONSMAP__0__CONNECTION=SERVICE_CONNECTION
CONNECTIONSMAP__0__SERVICEURL=*

# Auth handler config : TYPE is required, name is uppercased by load_configuration_from_env
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__OBOCONNECTIONPROFILE__TYPE=UserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__OBOCONNECTIONPROFILE__SETTINGS__AZUREBOTOAUTHCONNECTIONNAME=oboConnectionProfile
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__OBOCONNECTIONPROFILE__SETTINGS__SCOPES=api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite

ENABLE_A365_OBSERVABILITY=true
ENABLE_A365_OBSERVABILITY_EXPORTER=true

Önemli

load_configuration_from_env tüm ortam değişkeni anahtarlarını büyük harfe dönüştürür. İşleyici adı OBOCONNECTIONPROFILE olur ve bu adı auth_handlers ve get_token() çağrılarında tam olarak aynı büyük/küçük harf düzeniyle referans göstermeniz gerekir. TYPE eksikliği çalışma zamanında Auth handler ... not recognized or not configured hatasına neden olur.

2. adım: OBO için dağıtımı yapılandırma

Aşağıdaki örnekler, Agent 365 dışa aktarma işlemini nasıl etkinleştireceğinizi, dışa aktarıcıyı OBO uç noktasında nasıl tutacağınızı ve dışa aktarma sırasında yetkilendirilmiş belirteçler döndüren özel bir TokenResolver öğesini nasıl kaydedeceğinizi göstermektedir.

from microsoft.opentelemetry import use_microsoft_opentelemetry

_token_cache: dict[str, str] = {}

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _token_cache.get(f"{agent_id}:{tenant_id}")

environ["ENABLE_A365_OBSERVABILITY_EXPORTER"] = "true"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    a365_use_s2s_endpoint=False,  # OBO uses /observability endpoint
    a365_enable_observability_exporter=True,
)

Not

OBO modu, aiohttpApplication üzerinde jwt_authorization_middleware gerektirir (Bot Framework'ten gelen JWT'yi (JSON Web Belirteci) doğrular). S2S/öykünücü yolu bu ara yazılımı içermemelidir.

from microsoft_agents.hosting.aiohttp import jwt_authorization_middleware
app = Application(middlewares=[jwt_authorization_middleware])

3. adım: OBO belirtecini edinme

Aşağıdaki örnekler, yapılandırılmış Azure Bot OAuth bağlantısından yetki devri yoluyla alınmış bir OBO belirtecini nasıl talep edileceğini ve ardından bu belirtecin dışa aktarıcı için uygulama istemcisi ve kiracı bazında önbelleğe nasıl alınacağını göstermektedir.

from microsoft_agents.hosting.core import (
    AgentApplication, Authorization, MemoryStorage, TurnContext, TurnState,
)
from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter

# Auth handlers are loaded from .env via load_configuration_from_env (see Environment config above)
agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config,
)

CLIENT_ID = environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID", "")
TENANT_ID = environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID", "")

# Message handler : get_token returns a token already scoped to the observability API.
# The Azure Bot Token Service performs the OBO exchange internally based on the
# OAuth connection's configured scope. No manual MSAL exchange_token call is needed.
@AGENT_APP.activity("message", auth_handlers=["OBOCONNECTIONPROFILE"])
async def on_message(context: TurnContext, _state: TurnState):
    token_response = await AGENT_APP.auth.get_token(context, "OBOCONNECTIONPROFILE")
    # token_response.token has aud=<a365-observability-app-id>,
    # scp=Agent365.Observability.OtelWrite
    _token_cache[f"{CLIENT_ID}:{TENANT_ID}"] = token_response.token

Önemli

Azure portal ön koşulu:oboConnectionProfile adlı Azure Bot OAuth bağlantısının Scopes değerinin api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite olarak ayarlanması gerekir. Bu ayar olmadan, belirtecin kapsamı botun kendi hedef kitlesiyle (api://botid-...) sınırlandırılır ve dışarı aktarma HTTP 401 InvalidAudience hatasıyla başarısız olur.

Not

AGENT_APP.auth.get_token() doğru kapsamdaki belirteci doğrudan döndürür; exchange_token() çağrısı yapılmasına gerek yoktur. OAuth bağlantı kapsamı A365 gözlemlenebilirlik kaynağını hedeflediğinde, Bot Framework Belirteç Hizmeti OBO değişimini yönetir.

S2S kullanan özel motor

Özel motor aracıları, hizmet bağlantısı kimlik bilgilerini kullanarak S2S (istemci kimlik bilgileri) yoluyla yalnızca uygulama için geçerli bir belirteç alabilir. Bu yöntem, standart MSAL istemci kimlik bilgilerini kullanır; aracı kimlik zinciri gerekmez.

Ön koşullar

  • Azure AD uygulama kaydı : Özel altyapı (standart) uygulaması olmalıdır. Agent 365 etkinleştirilmiş uygulama kayıtları, gözlemlenebilirlik kaynağı (AADSTS82001) için düz client_credentials kullanamaz.
  • Uygulama izinleri : Agent365.Observability.OtelWrite (Uygulama, Temsili değil) ekleyin ve yönetici onayı verin.

Önemli

önbelleği için kullanılan agentId, ServiceConnection'a ait ClientId olmalıdır. Dışarı aktarma URL'si /observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces şeklindedir: uyuşmazlık HTTP 403 hatasına neden olur.

1. adım: Ortam ve uygulama yapılandırması

Aşağıdaki örnekler, hizmet bağlantı değerleri, kiracı ve istemci ayarları ile gerekli yetkilendirme eşlemeleri dahil olmak üzere, uygulamanızı ve çalışma zamanı ortamınızı nasıl yapılandıracağınızı göstermektedir.

# .env
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<your-client-id>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<your-client-secret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

CONNECTIONSMAP__0__CONNECTION=SERVICE_CONNECTION
CONNECTIONSMAP__0__SERVICEURL=*

ENABLE_A365_OBSERVABILITY=true
ENABLE_A365_OBSERVABILITY_EXPORTER=true

2. adım: Dağıtımı S2S için yapılandırma

Aşağıdaki örnekler, Agent 365 dışa aktarma özelliğinin nasıl etkinleştirileceğini, dışa aktarıcının S2S uç noktasına nasıl ayarlanacağını ve dışa aktarma sırasında belirteç araması için özel bir TokenResolver öğesinin nasıl kaydedileceğini göstermektedir.

from microsoft.opentelemetry import use_microsoft_opentelemetry

_token_cache: dict[str, str] = {}

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _token_cache.get(f"{agent_id}:{tenant_id}")

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    a365_use_s2s_endpoint=True,  # S2S uses /observabilityService endpoint
    a365_enable_observability_exporter=True,
)

3. adım: S2S belirtecini edinme

Aşağıdaki örnekler, hizmet bağlantısı kimlik bilgilerini kullanarak gözlemlenebilirlik kaynağı için yalnızca uygulama erişim belirtecinin nasıl talep edileceğini ve ardından bu belirtecin dışa aktarıcı için aracı ve kiracı bazında önbelleğe nasıl alınacağını göstermektedir.

# Force agentId to ServiceConnection ClientId (custom engine agents have no agenticAppId)
agent_id = os.environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID")
tenant_id = os.environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID")

connection = CONNECTION_MANAGER.get_connection("SERVICE_CONNECTION")
token = await connection.get_access_token(
    resource_url="https://login.microsoftonline.com",
    scopes=["api://9b975845-388f-4429-889e-eab1ef63949c/.default"],
)
_token_cache[f"{agent_id}:{tenant_id}"] = token

4. adım: Span dışa aktarmak için bagaj ayarları

Agent365 dışa aktarıcısı, span bağlamında bagaj (kiracı kimliği ve aracı kimliği) bilgilerinin ayarlanmasını gerektirir. Bu olmadan dışa aktarıcı, No spans with tenant/agent identity found. iletisiyle aralıkları sessizce bırakır.

from microsoft.opentelemetry.a365.core import BaggageBuilder, InvokeAgentScope

# Baggage must wrap the span as a context manager
with BaggageBuilder().tenant_id(tenant_id).agent_id(agent_id).build():
    invoke_scope = InvokeAgentScope.start(request, InvokeAgentScopeDetails(), agent_details)
    with invoke_scope:
        invoke_scope.record_input_messages([user_message])
        invoke_scope.record_output_messages([response])
  • Last updated on