Kullanıcıların kimliğini doğrulama ve etkileşimli aracılar için belirteç alma

Etkileşimli aracılar, kullanıcılar adına eylemler gerçekleştirir. Bunu güvenli bir şekilde yapmak için aracının kullanıcının kimliğini doğrulaması, gerekli izinler için onay alması ve aşağı akış API'leri için erişim belirteçleri alması gerekir. Bu makalede, etkileşimli aracınız için uçtan uca akışı uygulama adımları gösterilir:

Aracı kimliği şemanız için yeniden yönlendirme URI'sini kaydedin.
Kullanıcı veya yönetici yetkilendirmesi (onay) yapılandırın.
Kullanıcının kimliğini doğrulama ve erişim belirteci alma.
Belirteci doğrulayın ve kullanıcı taleplerini ayıklayın.
On-Behalf-Of (OBO) akışını kullanarak aşağı yönlü API'ler için token alın.

Uyarı

Bu makale, OBO akışını kullanan oturum açmış kullanıcılar adına hareket eden etkileşimli aracıları kapsar. Aracınızın kendi kullanıcı benzeri kimliğine (dijital çalışan senaryosu) ihtiyacı varsa, bkz. Aracı'nın kullanıcı hesapları ve Aracının kullanıcı hesabı OAuth akışı.

Önkoşullar

Başlamadan önce aşağıdakilere sahip olduğunuzdan emin olun:

Aracı kimliği şeması. Aracı kimliği taslağı uygulama kimliğini (istemci kimliği) kaydedin.
Aracı kimliği.
Kullanıcı kimlik doğrulamasını işlemek için Microsoft Entra kayıtlı bir istemci uygulaması.
OAuth 2.0 yetkilendirme kodu akışı hakkında bilgi.

Yönetici yetkilendirmesi için şunları da yapmanız gerekir:

Uygulama izinleri için onay vermek amacıyla yönetici erişimi.

Yeniden yönlendirme URI'sini kaydetme

Temsilci izinlerini desteklemek için aracı kimliği şemanızın geçerli bir yeniden yönlendirme URI'siyle yapılandırılması gerekir. Bu URI, Microsoft Entra ID kullanıcıları aracınıza onay verdikten veya reddettikten sonra gönderdiği yerdir.

Microsoft Graph API'sı
Microsoft Graph PowerShell

Bu isteği göndermek için önce temsilci iznine AgentIdentityBlueprint.ReadWrite.Allsahip bir erişim belirteci almanız gerekir.

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "web": {
    "redirectUris": [
      "https://myagentapp.com/authorize"
    ]
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All" -TenantId <your-test-tenant>

$applicationId = "<agent-blueprint-id>"
$web = @{
    redirectUris= @(
        "https://myagentapp.com/authorize"
    )
}

$body = @{
    web   =  $web
}

Invoke-MgGraphRequest -Method PATCH `
        -Uri "https://graph.microsoft.com/beta/applications/$applicationId" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Kullanıcı yetkilendirmeyi yapılandırma

Bir kullanıcı adına aracının işlem yapabilmesi için önce kullanıcının gerekli izinleri onaylaması gerekir. Bu onay adımı jeton döndürmez. Bunun yerine, kullanıcının aracıya kendi adına işlem yapma izni verdiğini kaydeder. Belirteç alma işlemi sonraki bir adımda gerçekleşir.

Bir kullanıcıdan onay istemek için bir yetkilendirme URL'si oluşturup kullanıcıyı buna yönlendirin. Aracı, bu URL'yi farklı şekillerde( örneğin, bir sohbet iletisinde bağlantı olarak) sunabilir.

Önemli

Aracı kimliği şema kimliğini değil parametresinde client_id aracı kimliği istemci kimliğini kullanın.

https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
  client_id=<agent-identity-id>
  &response_type=none
  &redirect_uri=https%3A%2F%2Fmyagentapp.com%2Fauthorize
  &response_mode=query
  &scope=User.Read
  &state=xyz123

Kullanıcı bu URL'yi açtığında Microsoft Entra ID oturum açmasını ve scope parametresinde belirtilen izinlere onay vermelerini ister. Onay verildikten sonra kullanıcı belirtilen yeniden yönlendirme URI'sine yönlendirilir.

Onay URL'sindeki temel parametreler şunlardır:

client_id: Aracı kimliği istemci kimliği (aracı kimliği şema istemci kimliği değil).
response_type: Bu isteği yalnızca onayı kaydettiği için none olarak ayarlayın. Token alımı, ayrı bir istekte kullanılır.
redirect_uri: Önceki adımda yapılandırdığınızla tam olarak eşleşmelidir.
scope: İhtiyacınız olan temsilci izinlerini belirtin (örneğin, User.Read).
state: İstek ve geri çağırma arasında durumu korumak için isteğe bağlı parametre.

OAuth yetkilendirme kavramları hakkında daha fazla bilgi için: Microsoft kimlik platformunda İzinler ve kullanıcı onayı bölümüne bakın.

Yönetici yetkilendirmeyi yapılandırma

Aracılar, kiracılarındaki tüm kullanıcılar için aracıya yetkilendirme verebilen bir Microsoft Entra ID yöneticisinden de yetkilendirme isteyebilir. Tek tek kullanıcılar onay veremediği için uygulama izinleri yönetici yetkilendirmesi gerektirir.

Yönetici onayı vermek için, yöneticiye yönelik bir yetkilendirme URL'si oluşturun. Aşağıdaki istekte aracı kimliği kimliğini kullanın.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-id>
&scope=User.Read
&redirect_uri=https://entra.microsoft.com/TokenAuthorize
&state=xyz123

Yönetici onay verdikten sonra, izinler kiracı genelinde uygulanır ve bu kiracıdaki kullanıcıların bu izinleri tek tek onaylaması gerekmez.

Kullanıcının kimliğini doğrulama ve belirteç isteme

Yetkilendirme yapılandırıldıktan sonra istemci uygulaması (ön uç veya mobil uygulama gibi) hedef kitlenin aracı kimliği şeması olduğu bir belirteç almak için bir OAuth 2.0 yetkilendirme kodu isteği başlatır. Bu adımda, client_id ajan kimliği veya ajan kimliği taslak kimliği değil, istemci uygulamasının kendi kayıtlı uygulama kimliğine atıfta bulunur.

Kullanıcıyı aşağıdaki parametrelerle Microsoft Entra ID yetkilendirme uç noktasına yönlendirin:

GET https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/authorize?client_id=<client-app-id>
&response_type=code
&redirect_uri=<redirect_uri>
&response_mode=query
&scope=api://<agent-blueprint-id>/access_agent
&state=abc123

Kullanıcı oturum açtığında, uygulamanız yeniden yönlendirme URI'sinde bir yetkilendirme kodu alır. Erişim belirteci ile değiştir:
```
POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<client-app-id>
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&scope=api://<agent-blueprint-id>/access_agent
&client_secret=<client-secret>
```
Gizli bir istemci kullanıyorsanız client_secret parametresini yalnızca ekleyin.

JSON yanıtı, aracının API'sine erişmek için kullanılabilecek bir erişim belirteci içerir.

Erişim belirtecini doğrulama

Genellikle bir web API'si aracılığıyla erişime açılan aracın erişim belirtecini doğrulaması gerekir. Belirteç geçerleme gerçekleştirmek için her zaman onaylı bir kütüphane kullanın. Hiçbir zaman kendi belirteç doğrulama kodunuzu uygulamayın.

Microsoft.Identity.Web NuGet paketini yükleyin:
```
dotnet add package Microsoft.Identity.Web
```

ASP.NET Core web API'niz projesinde Microsoft Entra ID kimlik doğrulamasını uygulayın:

// Program.cs
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

appsettings.json dosyasında kimlik doğrulama bilgilerini yapılandırın.

Uyarı

Güvenlik risklerinden dolayı istemci sırları, ajan kimlik planları için üretim ortamlarında istemci kimlik bilgileri olarak kullanılmamalıdır. Bunun yerine, yönetilen kimliklerle veya istemci sertifikalarıyla federasyon kimlik bilgileri (FIC) gibi daha güvenli kimlik doğrulama yöntemleri kullanın. Bu yöntemler, hassas gizli dizileri doğrudan uygulama yapılandırmanızda depolama gereksinimini ortadan kaldırarak gelişmiş güvenlik sağlar.
```
"AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<my-test-tenant>",
    "ClientId": "<agent-blueprint-id>",
    "Audience": "<agent-blueprint-id>",
    "ClientCredentials": [
        {
            "SourceType": "ClientSecret",
            "ClientSecret": "your-client-secret"
        }
    ]
}
```

Microsoft.Identity.Web hakkında daha fazla bilgi için Microsoft.Identity.Web belgelerine bakın.

Kullanıcı taleplerini doğrulama

Erişim belirtecini doğruladıktan sonra aracı kullanıcıyı tanımlayabilir ve yetkilendirme denetimleri gerçekleştirebilir. Bu örnek API yolu, erişim belirtecinden kullanıcı taleplerini ayıklar ve bunları API yanıtında döndürür:

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

Alt API'ler için jeton alma

Etkileşimli bir aracı kullanıcının belirtecini doğruladıktan sonra, kullanıcı adına aşağı akış API'lerini çağırmak için erişim belirteçleri isteyebilir. On-Behalf-Of (OBO) akışı ajanının şunları yapmasına olanak tanır:

İstemciden erişim belirteci alma.
Yeni bir erişim belirteci almak için Microsoft Graph gibi bir alt-akış API'si karşılığında değiştirin.
Özgün kullanıcı adına korumalı kaynaklara erişmek için bu yeni belirteci kullanın.

Microsoft Identity Web
Microsoft Graph SDK'sı

Microsoft.Identity.Web kitaplığı, belirteç değişimini otomatik olarak işleyerek OBO uygulamasını basitleştirir, böylece protokolü izleyerek akışı el ile uygulamanız gerekmez.

Gerekli NuGet paketlerini yükleyin:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities

ASP.NET Core web API'niz projesinde Microsoft Entra ID kimlik doğrulama uygulamasını güncelleştirin:

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

Aracı API'sinde, gelen erişim belirtecini aracı kimliği için yeni bir erişim belirteciyle değiştirin. Microsoft.Identity.Web alınan erişim belirtecini doğrular ve adına belirteç değişimi işlemini yönetir.

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";
    IAuthorizationHeaderProvider authorizationHeaderProvider = httpContext.RequestServices.GetService<IAuthorizationHeaderProvider>()!;
    AuthorizationHeaderProviderOptions options = new AuthorizationHeaderProviderOptions().WithAgentIdentity(agentIdentity);

    string authorizationHeaderWithUserToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(["https://graph.microsoft.com/.default"], options);

    var response = new { header = authorizationHeaderWithUserToken };
    return Results.Json(response);
})
.RequireAuthorization();

Microsoft Graph SDK'sını kullanıyorsanız GraphServiceClient kullanarak Microsoft Graph kimlik doğrulaması yapabilirsiniz.

Gerekli NuGet paketlerini yükleyin:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities
dotnet add package Microsoft.Identity.Web.GraphServiceClient

ASP.NET Core web API'niz projesinde kimlik doğrulamasını yapılandırın ve Microsoft Graph için destek ekleyin:

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();
builder.Services.AddMicrosoftGraph();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

Hizmet sağlayıcısından bir GraphServiceClient alın ve aracı kimliğiyle Microsoft Graph API'lerini çağırın:

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";

    GraphServiceClient graphServiceClient = httpContext.RequestServices.GetService<GraphServiceClient>()!;
    var me = await graphServiceClient.Me.GetAsync(r => r.Options.WithAuthenticationOptions(
        o =>
        {
            o.WithAgentIdentity(agentIdentity);
        }));
    return me.UserPrincipalName;
})
.RequireAuthorization();

Arka planda, OBO akışı iki belirteç değişimi içerir: önce, aracı kimliğinin temel yapısı istemci kimlik bilgilerini kullanarak bir değişim belirteci alır; ardından, aracı kimliği, kullanıcının ardıl API belirteci için erişim belirteci ile birlikte bu belirteci değiştirir. HTTP isteği biçimleri ve belirteç doğrulama ayrıntıları da dahil olmak üzere tam protokol kılavuzu için bkz. Aracılarda adına akış.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-05-01