Aracı kimlik platformunda aracı kimlikleri oluşturma

Bir aracı kimliği şeması oluşturduktan sonra, sonraki adım kiracınızdaki yapay zeka aracılarını temsil eden bir veya daha fazla aracı kimliği oluşturmaktır. Aracı kimliği oluşturma işlemi genellikle yeni bir yapay zeka aracısı sağlanırken gerçekleştirilir.

Aracı kimliklerini iki şekilde oluşturabilirsiniz:

• Microsoft Entra yönetim merkezi — Hızlı ve tek tek kimlik oluşturmak için yönetim merkezi sihirbazını kullanın.
• Microsoft Graph API — Aracı kimliklerini program aracılığıyla oluşturan ve büyük ölçekte otomatik sağlama için yararlı olan bir web hizmeti oluşturun.

Test amacıyla aracı kimliklerini hızla oluşturmak istiyorsanız, aracı kimliklerini oluşturmak ve kullanmak için bu Microsoft Entra PowerShell modülünü kullanarak aracı kimlikleri kullanmayı göz önünde bulundurun.

Önkoşullar

Aracı kimlikleri oluşturmak için şunları yapmanız gerekir:

• Aracı kimliği şeması. Oluşturma işleminden aracı kimliği şablon uygulama kimliğini kaydedin.
• Aracı kimliği oluşturma mantığını barındıran, yerel olarak çalıştırılan veya Azure'a dağıtılan bir web hizmeti veya uygulama. Bu önkoşul yalnızca aracı kimliklerini program aracılığıyla oluşturuyorsanız geçerlidir.

Microsoft Entra yönetim merkezi kullanma

Microsoft Entra yönetim merkezinde mevcut bir taslağı seçip sahipler ve sponsorlar atayarak doğrudan bir aracı kimliği oluşturabilirsiniz.

1. Microsoft Entra yönetici merkezine oturum açın.

2. Entra ID>Agents>Agent identities adresine gidin.

3. Yeni aracı kimliği (Önizleme) öğesini seçin.

4. Temel Bilgiler sekmesinde:

   • Aracı şeması altında, aracı kimliğinizin oluşturulacağı şemayı seçin.

   • Aracı kimliği adı alanına bir ad girin ve İleri'yi seçin.

     

5. Sahipler ve Sponsorlar sekmesinde, isteğe bağlı olarak kimlik için sahipler ve sponsorlar ekleyin:

   • Bu aracı kimliğini yönetebilecek kullanıcıları değiştirmek veya eklemek için Sahipler alanının yanındaki kalem simgesini seçin.
   • Bu aracı kimliğine sponsor olabilecek kullanıcıları değiştirmek veya eklemek için Sponsorlar alanının yanındaki kalem simgesini seçin.

   Uyarı

   Sponsorlar kullanıcılar, dinamik üyelik grupları veya Microsoft 365 grupları olabilir. Güvenlik grupları ve rol atanabilir gruplar sponsor olarak desteklenmez.

6. Sonraki'yi seçin.

7. Ayarlarınızı gözden geçirin ve oluştur'u seçin.

8. Sihirbazdan çıkmak için Bitti'yi seçin veya kimliğin ayrıntı sayfasını görüntülemek ya da daha fazla ayar yapılandırmak için Agent kimliğine git seçin.

Aşağıdaki adımlarda, Microsoft Graph API ve Microsoft.Identity.Web ile programatik olarak aracı kimlikleri oluşturmayı öğreneceksiniz. Önce bir erişim belirteci alın, ardından oluşturma API'sini çağırın.

Microsoft Graph API'sı

Aracı kimliği taslağını kullanarak erişim belirteci alma

Her bir ajan kimliğini oluşturmak için ajan kimliği taslağını kullanırsınız. Aracı kimliği şemanızı kullanarak Microsoft Entra erişim belirteci isteyin:

Kimlik bilgisi olarak yönetilen kimlik kullanırken, önce yönetilen kimliğinizi kullanarak bir erişim belirteci edinmeniz gerekir. Yönetilen kimlik belirteçleri, işlem ortamında yerel olarak kullanıma sunulan bir IP adresinden istenebilir. Ayrıntılar için yönetilen kimlik belgelerine bakın.

GET http://169.254.169.254/metadata/identity/oauth2/token?api-version=2019-08-01&resource=api://AzureADTokenExchange/.default
Metadata: True

Yönetilen kimlik için bir belirteç aldıktan sonra aracı kimliği şeması için bir belirteç isteyin:

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

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

Yerel geliştirmede bir istemci gizli dizisi kullanılırken client_secret ve client_assertion yerine bir client_assertion_type parametresi de kullanılabilir.

Microsoft. Identity.Web

Microsoft.Identity.Web'i yüklemek için:

dotnet add package Microsoft.Identity.Web

Microsoft. Identity.Web otomatik olarak erişim belirteci isteyen ve giden HTTP isteklerine ekleyen bir arabirim içerir. Microsoft.Identity.Web kullanırken sonraki adıma geçebilirsiniz.

Ajan Kimliği Oluştur

Önceki adımda alınan erişim belirtecini kullanarak artık kiracınızda aracı kimlikleri oluşturabilirsiniz. Aracı kimliği oluşturma işlemi, kullanıcının yeni aracı oluşturmak için düğme seçmesi gibi birçok farklı olaya veya tetikleyiciye yanıt olarak gerçekleşebilir. Her bir aracı için bir temsilci kimliği oluşturmanızı öneririz, ancak gereksinimlerinize göre farklı bir yaklaşım seçebilirsiniz.

Microsoft Graph API'sı

tr-TR: `@odata.type` kullanırken her zaman OData-Version üst bilgisini ekleyin.

POST https://graph.microsoft.com/beta/serviceprincipals/Microsoft.Graph.AgentIdentity
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
{
	"displayName": "My Agent Identity",
	"agentIdentityBlueprintId": "<my-agent-blueprint-id>",
	"sponsors@odata.bind": [
		"https://graph.microsoft.com/v1.0/users/<id>",
		"https://graph.microsoft.com/v1.0/groups/<group-id>"
	],
}

Uyarı

Bir grubu sponsor olarak atarken yalnızca desteklenen grup türleri kabul edilir. Gruplar sahip olarak desteklenmez.

Microsoft. Identity.Web

Microsoft.Identity.Web kullanarak bir ajan kimliği oluşturmak için Microsoft Graph API isteğini yürütmek üzere aşağıdaki MISE yapılandırma dosyasını ekleyin:

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": "<my-agent-blueprint-id>",
	"Scopes": "access_agent",
	"ClientCredentials": [
		{
			"SourceType": "ClientSecret",
			"ClientSecret": "your-client-secret"
		}
	]
  },

  "DownstreamApis": {
	"agent-identity": {
	  "BaseUrl": "https://graph.microsoft.com",
	  "RelativePath": "/beta/serviceprincipals/Microsoft.Graph.AgentIdentity",
	  "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
	  "RequestAppToken": true
	}
  }
}

ASP.NET Core uygulamasının kodu (Program.cs) aşağıdaki örnektir:

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

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
	.EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddInMemoryTokenCaches();
var app = builder.Build();

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

public class AgentIdentity
{
	[JsonPropertyName("@odata.type")]
	public string @odata_type { get; set; } = "#Microsoft.Graph.AgentIdentity";

	[JsonPropertyName("displayName")]
	public string? displayName { get; set; }

	[JsonPropertyName("agentIdentityBlueprintId")]
	public string? agentIdentityBlueprintId { get; set; }

	[JsonPropertyName("id")]
	public string? id { get; set; }

  [JsonPropertyName("sponsors@odata.bind")]
	public string[]? sponsorsOdataBind { get; set; }

  [JsonPropertyName("owners@odata.bind")]
	public string[]? ownersOdataBind { get; set; }
}

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

		// Call the downstream API with a POST request to create an Agent Identity
		var jsonResult = await downstreamApi.PostForAppAsync<AgentIdentity, AgentIdentity>(
			"agent-identity",
			new AgentIdentity {
				displayName = "My agent identity",
				agentIdentityBlueprintId = "<my-agent-blueprint-id>",
		  sponsorsOdataBind = new [] { "https://graph.microsoft.com/v1.0/users/<id>" }
			}
		  );
		return jsonResult?.id;
	}
	catch (Exception ex)
	{
		return ex.Message;
	}

})

app.Run();

Aracı kimliğini sil

Bir aracı serbest bırakıldığında veya yok edildiğinde, hizmetiniz ilişkili aracı kimliğini de silmelidir:

Microsoft Graph API'sı

DELETE https://graph.microsoft.com/beta/serviceprincipals/<agent-identity-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

Microsoft. Identity.Web

// Delete an Agent identity
app.MapGet("/delete-agent-identity", async (HttpContext httpContext, string id) =>
{
	// Get the service to call the downstream API (preconfigured in the appsettings.json file)
	IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();

	// Call the downstream API with a DELETE request to remove an Agent Identity
	var jsonResult = await downstreamApi.DeleteForAppAsync<string, string>(
		"agent-identity",
		null!,
		options =>
		{
			options.RelativePath += $"/{id}"; // Specify the ID of the agent identity to delete
		});
	return jsonResult;
})

İlgili içerik

• Şemalar için devralınabilir izinleri yapılandırma
• Otonom aracılar için kimlik doğrulaması ve belirteç alma
• Kullanıcıların kimliğini doğrulama ve etkileşimli aracılar için belirteç alma
• Sahipleri ve sponsorları yönetme
• Aracı kimliği şemaları