Otonom etkenler için kimlik doğrulama ve belirteç edinme

Otonom aracılar, bir kullanıcının temsilcisi olarak hareket etmek yerine kendi kimliklerini kullanarak işlemler gerçekleştirir. Otonom bir aracı güvenli bir şekilde çalışmak için Microsoft Entra ID ile kimlik doğrulaması yapmalı, erişim belirteçleri almalı ve uygun izinlere sahip olmalıdır. Bu makalede uçtan uca akışta size yol gösterilir:

İstemci kimlik bilgilerini yapılandırın.
Aracı kimliği şeması için bir belirteç isteyin.
Aracı kimlik belirteci talep edin.
Uygulama izinleri verme (yönetici onayı).
(İsteğe bağlı) Kullanıcı kimliği gerektiren kaynaklar için bir aracının kullanıcı hesabını oluşturun ve kimlik doğrulaması yapın.

Uyarı

Bu makale, kendi kimlikleriyle çalışan otonom aracıları kapsar. Aracınızın oturum açmış bir kullanıcı adına işlem yapması gerekiyorsa bkz. Kullanıcıların kimliğini doğrulama ve etkileşimli aracılar için belirteç alma.

Önkoşullar

Aracı belirteci kimlik doğrulamasını uygulamadan önce aşağıdakilere sahip olduğunuzdan emin olun:

Aracı kimliği şeması.
Ajanın kimliği. Aracı kimliği istemci kimliğine ihtiyacınız var.
Microsoft Entra Aracı Kimliği içindeki OAuth protokollerinin anlaşılması.

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

Microsoft Entra ID kiracınızdaki yönetici yetkileri.
Temsilciniz için gereken belirli izinlerin anlaşılması.

Ajanın kullanıcı hesabı kimlik doğrulaması için de şunları yapmanız gerekir:

Microsoft Entra Aracı Kimliği'deki ajanlar kullanıcı hesaplarını anlama.

İstemci kimlik bilgilerinizi yapılandırma

İstemci kimlik bilgilerinizi alın. Bu, istemci gizli bilginiz, sertifikanız veya federe kimlik bilgisi olarak kullandığınız yönetimli kimlik olabilir.

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.

Microsoft Graph API'sı
Microsoft. Identity.Web

Aracı kimliği şemanızda yapılandırdığınız kimlik bilgilerini toplayın. Aşağıdakilerden birine ihtiyacınız vardır:

Yönetilen kimlik (önerilir): Yönetilen kimlik istemci kimliği ve Azure Örnek Meta Veri Hizmeti'nden (IMDS) bir belirteç.
Sertifika: Sertifika parmak izi veya PFX dosyası.
İstemci sırrı (yalnızca geliştirme): Sır değeri.

Üretim için yönetilen kimliği federasyon kimliği kimlik bilgileri olarak kullanın:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<managed-identity-client-id>"
      }
    ]
  }
}

"Yerel geliştirme ve test için yalnızca, bunun yerine bir istemci gizli anahtarı kullanabilirsiniz:"

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Temsilci kimliği taslağı için token talebi

Aracı kimliği taslağı için belirteç talep ederken, aracı kimliğinin istemci kimliğini fmi_path (Federasyon Yönetilen Kimlik Yolu) parametresinde sağlayın. Bu parametre, Microsoft Entra ID'ye taslağın hangi temsilci kimliği adına hareket ettiğini bildirir.

Yerel geliştirme sırasında bir istemci gizli dizisi kullanırken client_secret parametresini sağlayın. Sertifikalar ve yönetilen kimlikler için client_assertion ve client_assertion_type'i kullanın.

Microsoft Graph API'sı
Microsoft. Identity.Web

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-blueprint-client-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_secret=<client-secret>
&fmi_path=<agent-identity-client-id>

Microsoft.Identity.Web ile, aracı kimlik planı için açıkça bir jeton istemeniz gerekmez. Microsoft. Identity.Web sizin için yapar.

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

Aracı kimliği şablon belirtecini (T1) aldıktan sonra, aracı kimliği belirtecini istemek için bunu kullanın.

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-client-id>
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token-T1>

Microsoft. Identity.Web, uygulamanın başlatılması sırasında hizmet koleksiyonunuzda yeni services.AddAgentIdentities() kullanmanız koşuluyla belirteç alma protokolünün ayrıntılarını sizin yerinize işler.

Uygulamayı başlatın:

// 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);
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

Erişim belirteçleri istemek için deseni .WithAgentIdentity() kullanın:

// In an API endpoint or service method where HttpContext is available
app.MapGet("/call-api", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    AuthorizationHeaderProviderOptions options =
        new AuthorizationHeaderProviderOptions().WithAgentIdentity("<agent-identity-client-id>");

    // Request agent identity tokens
    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForAppAsync("https://graph.microsoft.com/.default", options);

    // The authHeader contains "Bearer " + the access token
    return Results.Ok(authorizationHeader);
});

Uygulama izinleri verme

Aracıların genellikle Microsoft Graph ve Microsoft Entra ID uygulama izni gerektiren diğer web hizmetlerinde (uygulama rolleri olarak temsil edilir) eylem gerçekleştirmesi gerekir. Otonom aracıların bu izinleri bir Microsoft Entra ID yöneticisinden istemesi gerekir.

Otonom bir aracıya uygulama izinleri vermenin iki yolu vardır:

Yönetici, Microsoft Graph API'lerini veya PowerShell'i kullanarak appRoleAssignment oluşturabilir.
Aracı, yönetici onayı URL'sini kullanarak yöneticiyi bir onay sayfasına yönlendirebilir.

API'ler aracılığıyla uygulama rolü ataması oluşturma

Uygulama rolü ataması almak için aşağıdaki adımları kullanın.

Uygulama izinleriyleApplication.Read.All ve AppRoleAssignment.ReadWrite.All bir erişim belirteci alın.
Erişmeye çalıştığınız kaynak hizmeti sorumlusunun nesne kimliğini alın. Örneğin, Microsoft Graph hizmet sorumlusu nesne kimliğini bulmak için:
1. Microsoft Entra yönetim merkezi gidin.
2. Entra ID -->Kurumsal Uygulamalar adresine gidin
3. Uygulama türüne göre filtrele == Microsoft Uygulamaları
4. Microsoft Graph için arama yapın.
Atamak istediğiniz uygulama rolünün benzersiz kimliğini alın.

Uygulama rolü atamasını oluşturun:

Microsoft Graph API'sı
Microsoft Graph PowerShell

POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
Authorization: Bearer <token>
Content-Type: application/json

{
  "principalId": "<agent-identity-id>",
  "resourceId": "<microsoft-graph-sp-object-id>",
  "appRoleId": "<app-role-id>"
}

Connect-MgGraph -Scopes "Application.Read.All AppRoleAssignment.ReadWrite.All" -TenantId <your-test-tenant>

# Get the service principal for Microsoft Graph (well-known app ID)
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get your application's service principal (replace with your app's client ID)
$agentId = "<agent-identity-id>"

# Find the App Role ID for "User.ReadBasic.All"
$userReadBasicRole = $graphSp.AppRoles | Where-Object {
    $_.Value -eq "User.ReadBasic.All" -and $_.AllowedMemberTypes -contains "Application"
}

# Assign the app role
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $agentId `
    -PrincipalId $agentId `
    -ResourceId $graphSp.Id `
    -AppRoleId $userReadBasicRole.Id

Kiracı yöneticisinden yetkilendirme isteme

Temsilci izinleri vermek için yöneticiye istemde bulunmak için kullanılan yetkilendirme URL'sini oluşturun. rol parametresi, istenen uygulama izinlerini belirtmek için kullanılır.

Aşağıdaki istekte acente kimliği istemci ID'sini kullandığınızdan emin olun.

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

Aracı uygulamaları, yöneticiyi sohbet penceresinde yöneticiye gönderilen bir iletiye dahil etmek gibi çeşitli yollarla bu URL'ye yönlendirebilir. Yönetici bu URL'ye yeniden yönlendirildiğinde oturum açması ve kapsam parametresinde belirtilen izinlere onay vermesi istenir. Şu anda, yöneticiyi onay verdikten sonra boş bir sayfaya yönlendiren, listelenen yeniden yönlendirme URI'sini kullanmanız gerekir.

Uygulamanıza gerekli izinleri verdikten sonra, izinlerin etkili olması için yeni bir aracı erişim belirteci isteyin.

Bir ajanın kullanıcı hesabı olarak kimlik doğrulayın.

Yalnızca uygulama belirteçleriyle çalışmanın yanı sıra, otonom aracılar bir aracının kullanıcı hesabı olarak kimlik doğrulaması yapabilir. Aracıların kullanıcı hesapları, aracılar tarafından kullanılmak üzere oluşturulmuş Microsoft Entra özel bir kullanıcı hesabı türüdür. Bunlar en yaygın olarak, bir aracının bir kullanıcı hesabının (örneğin, posta kutusu, Teams kanalı veya kullanıcıya özgü diğer kaynaklar) var olmasını gerektiren sistemlere bağlanması gerektiğinde kullanılır.

Her aracı kimliği yalnızca tek bir ilişkili aracı kullanıcı hesabına sahip olabilir ve her aracının kullanıcı hesabı yalnızca tek bir aracı kimliğiyle ilişkilendirilebilir.

Aracıların kullanıcı hesaplarını oluşturmak için yetkilendirme alma

Aracıların kullanıcı hesaplarını oluşturmak için, aracı kimliği şemanıza kiracıda uygulama izni AgentIdUser.ReadWrite.IdentityParentedBy verilmelidir. Yetkilendirmeyi iki yoldan biriyle alabilirsiniz:

Aracı yetkilendirme isteğinde bulun. Aracı kimliği yerine aracı kimliği şemanızı client_id olarak kullandığınızdan emin olun.
Kiracıda manüel olarak bir appRoleAssignment oluşturun. Değer olarak, uygulama (istemci) kimliği yerine aracı kimliği planının principalId hizmet ilkesi nesne kimliğini kullanın.

Aracıların kullanıcı hesaplarını oluşturmak için aracı kimliği şemasını değil farklı bir istemci kullanmak istiyorsanız, bu istemcinin AgentIdUser.ReadWrite.All bunun yerine temsilci veya uygulama izni alması gerekir.

Temsilci kullanıcı hesabı oluşturma

Aracı kimliği şemanızı veya onaylanmış başka bir istemciyi kullanarak bir aracı kullanıcı hesabı oluşturun. Temsilcinin kullanıcı hesabını oluşturmanın önerilen yolu, temsilci kimliği taslağınızı kullanmaktır. Aracının kullanıcı hesabını oluşturmak için erişim anahtarına ihtiyacınız vardır.

REST
Microsoft. Identity.Web

Gerekli izne sahip bir erişim belirtecini aldıktan sonra aşağıdaki isteği gönderin:

POST https://graph.microsoft.com/beta/users
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "microsoft.graph.agentUser",
  "displayName": "New Agent User",
  "userPrincipalName": "agentuserupn@tenant.onmicrosoft.com",
  "identityParentId": "{agent-identity-id}",
  "mailNickname": "agentuserupn",
  "accountEnabled": true
}

Temsilcinin kullanıcı hesabını oluşturmak için Microsoft.Identity.Web kullanarak şu adımları izleyin:

Yapılandırma dosyanıza aşağıdakileri ekleyin:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<my-test-tenant>",
    "ClientId": "<my-agent-blueprint-id>",
    "Scopes": "access_agent",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
      }
    ]
  },

  "DownstreamApis": {
    "agent-identity": {
      "BaseUrl": "https://graph.microsoft.com",
      "RelativePath": "/v1.0/users",
      "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
      "RequestAppToken": true
    }
  }
}

Gerekli paketleri ekleme

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

Hizmetleri yapılandırın.

using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.Resource;
using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

Temsilcinin kullanıcı hesabı oluşturma uç noktasını oluşturun.

app.MapPost("/create-agent-id-user", async (HttpContext httpContext) =>
{
    try
    {
        // Get the service to call the downstream API (preconfigured in the appsettings.json file)
        IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();

        var requestBody = new AgentIdUser
        {
            displayName = "my-agent-name",
            mailNickname = "my-agent-alias",
            userPrincipalName = "my-agent-email-address",
            accountEnabled = true,
            identityParentId = "<associated-agent-identity-id>"
        };

        // Call the downstream API (Graph) with a POST request to create an agent's user account
        var jsonResult = await downstreamApi.PostForAppAsync<AgentIdUser, AgentIdUser>(
            "agent-identity",
            requestBody
        );

        return Results.Json(jsonResult);
    }
    catch (Exception ex)
    {
        return ex.Message;
    }
})

Ajanınızın kullanıcı hesabını oluşturduktan sonra başka bir şey yapılandırmanıza gerek yok. Bu hesapların kimlik bilgileri yoktur ve kimlik doğrulaması yalnızca sonraki bölümlerde açıklanan protokol kullanılarak gerçekleştirilebilir.

Aracıların kullanıcı hesapları diğer tüm kullanıcı hesapları gibi davranır. Bir aracının kullanıcı hesabını kullanarak belirteç isteğinde bulunabilmeniz için önce temsilci kimliğini onun adına hareket etmesi için yetkilendirmeniz gerekir. admin authorization kullanarak aracı kimliğini yetkilendirilebilir veya Microsoft Graph veya Microsoft Graph PowerShell kullanarak el ile oAuth2PermissionGrant oluşturabilirsiniz.

Microsoft Graph için isteğiniz aşağıdaki kod parçacığında gösterildiği gibi olur:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientId": "{agent-identity-id}",
  "consentType": "Principal",
  "principalId": "{agent-id-user-object-id}",
  "resourceId": "{ms-graph-service-principal-object-id}",
  "scope": "Mail.Read"
}

Microsoft Graph PowerShell için aşağıdaki betiği kullanın:

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

# Get the service principal for Microsoft Graph
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get the service principal for your client app
$clientSp = Get-MgServicePrincipal -Filter "appId eq '{agent-identity-id}'"

# Create the delegated permission grant
New-MgOauth2PermissionGrant -BodyParameter @{
    clientId    = $clientSp.Id
    consentType = "Principal"
    principalId = "{agent-id-user-object-id}"
    resourceId  = $graphSp.Id
    scope       = "Mail.Read"
}

Temsilcinin kullanıcı hesabı belirtecini iste

Bir aracının kullanıcı hesabının kimliğini doğrulamak için üç adımlı bir işlemi izlemeniz gerekir:

Ajan kimlik taslağı olarak bir belirteç alın.
Aracı kimliği olarak başka bir belirteç elde etmek için bu belirteci kullanın.
Temsilcinin kullanıcı hesabı olarak başka bir belirteç almak için önceki iki belirteci de kullanın.

REST
Microsoft. Identity.Web

İlk olarak, Aracı kimliği şeması için belirteç isteme başlığında açıklandığı gibi aracı kimliği şeması olarak bir belirteç isteyin. Aracı uygulama belirtecinizi aldıktan sonra, aracı kimliğiniz için Federasyon Kimlik Bilgilerini (FIC) talep etmek için bu belirteci kullanın.

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>

Bu, aracı kimliği için bir değişim jetonu (T2) döndürür. Ajanın kullanıcı hesabı için bir devredilmiş belirteç almak amacıyla sonraki istekte bu belirteci kullanın.

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=https://graph.microsoft.com/.default
&grant_type=user_fic
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>
&user_id=<agent-user-object-id>
&user_federated_identity_credential=<agent-identity-token>

Bu, temsilcinizin kullanıcı hesabı **için** Microsoft Graph çağırmak amacıyla kullanabileceğiniz bir temsilci erişim belirteci sağlar. Kullanıcı tanımlayıcısı user_id=<user-object-id> için yerine kullanabilirsinizusername=<UPN>.

Microsoft.Identity.Web sizin için jeton alımını işler. Erişim belirteçleri istemek için deseni .WithAgentUserIdentity() kullanın.

// In an API endpoint or service method where HttpContext is available
app.MapGet("/agent-user-token", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    // Configure options for the agent's user account identity
    string agentIdentity = "agent-identity-id";
    string userId = "<user-object-id>";
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity(agentIdentity, userId);

    // Create a ClaimsPrincipal to enable token caching
    ClaimsPrincipal user = new ClaimsPrincipal();

    // Acquire a user token
    string authHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForUserAsync(
            scopes: ["https://graph.microsoft.com/.default"],
            options: options,
            user: user);

    return Results.Ok(authHeader);
});

Nesne kimliği yerine aracının kullanıcı hesabı asıl adını da kullanabilirsiniz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-09