Aracı kimliği şeması oluşturma

Aracı kimliği şeması, aracı kimlikleri oluşturmak ve bu aracı kimliklerini kullanarak belirteç istemek için kullanılır. Aracı kimliği şeması oluşturma işlemi sırasında, sorumluluk ve yönetim ilişkileri kurmak için bu şemanın sahibini ve sponsorunu ayarlarsınız. Ayrıca bir tanımlayıcı URI'sini yapılandırıp aracı diğer aracılardan ve kullanıcılardan gelen istekleri almak üzere tasarlandıysa bu şemadan oluşturulan aracılar için bir kapsam tanımlarsınız.

Ajan kimlik taslağını iki yolla oluşturabilirsiniz:

  • Microsoft Entra yönetim merkezi — Taslağı ve asıl bileşenini oluşturan hızlı bir kurulum için sihirbazı kullanın.
  • Microsoft Graph API veya PowerShell — Tek bir iş akışında kimlik bilgileri, tanımlayıcı URI'leri, kapsamlar ve şema sorumlusu dahil olmak üzere şemayı program aracılığıyla oluşturun ve tam olarak yapılandırın.

Önkoşullar

Aracı kimliği şeması oluşturmak için şunları yapmanız gerekir:

Uyarı

Bir aracı kimliği şemasının veya aracı kimliği şema sorumlusunun sahipleri, Microsoft Entra Aracı Kimliği rolü olmadan bu şema için aracı kimlikleri oluşturabilir. Aracı kimliği şema oluşturucuları otomatik olarak hem şemanın hem de ilişkili aracı kimliği şema sorumlusunun sahipleri olarak ayarlanır.

Ortamınızı hazırlama

İşlemi kolaylaştırmak için ortamınızın doğru izinler için ayarlanmasını sağlamak birkaç dakikanızı alır.

İstemciye aracı kimliği şemaları oluşturma yetkisi verme

Bu makalede, aracınızın kimlik taslağını oluşturmak için Microsoft Graph PowerShell veya başka bir istemci kullanırsınız. Bu istemciyi bir aracı kimliği şeması oluşturma ve yapılandırma ve aracı kimliği şema sorumlusu oluşturma yetkisi vermelisiniz. İstemci aşağıdaki Microsoft Graph izinlerini gerektirir:

Bu kılavuzdaki adımlar tüm temsilci izinlerini kullanır, ancak bunları gerektiren senaryolar için uygulama izinlerini kullanabilirsiniz.

Microsoft Graph PowerShell için gerekli tüm kapsamlara bağlanmak için aşağıdaki komutu çalıştırın:

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.AddRemoveCreds.All", "AgentIdentityBlueprint.UpdateAuthProperties.All", "AgentIdentityBlueprintPrincipal.Create", "User.Read" -TenantId <your-tenant-id>

Aracı kimliği şeması oluşturma

Aracı kimliği şemalarının, aracıdan sorumlu olan kullanıcı veya desteklenen grup olan bir sponsoru olmalıdır. Ajan kimliği taslağında değişiklik yapabilen kullanıcı veya hizmet ilkesi olan bir sahibin olması önerilir. Daha fazla bilgi için bkz. Microsoft Entra Aracı Kimliği Yönetimsel ilişkiler.

Microsoft Entra yönetim merkezi kullanma

Microsoft Entra yönetici merkezinde doğrudan bir aracı kimliği taslağı oluşturabilirsiniz. Yönetim merkezi sihirbazı hem ajan kimliği planını hem de ana planını otomatik olarak oluşturur.

Uyarı

Yönetim merkezi sihirbazı taslak adını ayarlar ve sahiplerle sponsorları atar. Kimlik bilgilerini, tanımlayıcı URI'leri, kapsamları veya izinleri yapılandırmak için Microsoft Graph API veya PowerShell'i kullanın ya da oluşturma işleminden sonra bunları yönetim merkezindeki şemanın ayrıntı sayfaları aracılığıyla yapılandırın.

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

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

  3. Yeni aracı şeması (Önizleme) seçeneğini belirleyin.

  4. Temel Bilgiler sekmesinde, Aracı şema adı alanına bir ad girin ve İleri'yi seçin.

    Aracı şema adı alanını içeren Temel bilgiler sekmesini gösteren aracı şeması oluşturma sihirbazının ekran görüntüsü.

  5. Sahipler ve Sponsorlar sekmesinde, isteğe bağlı olarak şemanın sahiplerini ve sponsorlarını değiştirin veya ekleyin:

    • Şemayı yönetebilecek kullanıcıları değiştirmek veya eklemek için Sahipler alanının yanındaki kalem simgesini seçin.
    • Şemaya 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 veya şemanın ayrıntı sayfasını görüntülemek veya daha fazla ayar yapılandırmak için Aracı şemasına git'i seçin.

Aracı kimliği şemalarını yönetme hakkında daha fazla bilgi için bkz. Aracı kimliği şemalarını yönetme.

Program aracılığıyla oluşturma

Kod kullanarak bir aracı kimliği şeması oluşturmak için Microsoft Graph API veya PowerShell kullanın.

Bu adım aracı kimliği şemasını oluşturur, bir sahip ve sponsor atar ve aşağıdaki ayrıntıları gerektirir:

  • İzin AgentIdentityBlueprint.Create .
  • OData-Version üst bilgisi 4.0 olarak ayarlanmalıdır.
  • Sahip ve sponsor alanları için örnek istek gövdesinde bir kullanıcı kimliği. Sponsor gereklidir, ancak sahip zorunlu değildir.
POST https://graph.microsoft.com/v1.0/applications/
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
  "displayName": "My Agent Identity Blueprint",
  "sponsors@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>",
  ],
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>"
  ],
}

Ajan kimliği şablonunu oluşturduktan sonra, bir sonraki adımda appId değerini kaydedin.

Aracı kimliği taslağı için kimlik bilgilerini yapılandırma

Aracı kimliği şemasını kullanarak erişim belirteçleri istemek için bir istemci kimlik bilgisi eklemeniz gerekir. Üretim dağıtımları için federasyon kimlik bilgisi (FIC) olarak managed identity kullanmanızı öneririz. Yönetilen kimlikler, kimlik bilgilerini yönetmek zorunda kalmadan Microsoft Entra belirteçleri almanıza olanak sağlar. Daha fazla bilgi için bkz. Azure kaynakları için kimlikleri yönetme.

keyCredentials ve passwordCredentials dahil olmak üzere diğer uygulama kimlik bilgisi türleri desteklenir, ancak üretim için önerilmez. Yerel geliştirme ve test için veya yönetilen kimliklerin çalışmadığı yerlerde kullanışlı olabilir, ancak bu seçenekler en iyi güvenlik yöntemleriyle uyumlu değildir. Daha fazla bilgi için bkz . Uygulama özellikleri için en iyi güvenlik yöntemleri.

Yönetilen kimlik kullanmak için kodunuzu sanal makine veya Azure App Service gibi bir Azure hizmetinde çalıştırmanız gerektiğini unutmayın. Yerel geliştirme ve test için bir istemci gizli anahtarı veya sertifika kullanın.

Bu isteği göndermek için:

  • AgentIdentityBlueprint.AddRemoveCreds.All izinlerine ihtiyacınız var.
  • Yer tutucuyu <agent-blueprint-id> aracı kimliği şemasıyla appId değiştirin.
  • Yönetilen kimliğinizin kimliğiyle <managed-identity-principal-id> yer tutucu öğesini değiştirin.

Aşağıdaki isteği kullanarak kimlik bilgisi olarak yönetilen kimlik ekleyin:

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

{
    "name": "my-managed-identity",
    "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
    "subject": "<managed-identity-principal-id>",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Diğer uygulama kimlik bilgileri

Yönetilen kimliklerin çalışmadığı senaryolar veya test için yerel olarak bir taslak oluşturuyorsanız, kimlik bilgilerini eklemeniz için aşağıdaki adımları kullanın.

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

POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>

{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z"
  }
}

Uyarı

Kiracınızın, istemci sırları için maksimum yaşam süresi sınırını kısıtlayan kimlik bilgisi yaşam döngüsü ilkeleri olabilir. Kimlik bilgileri yaşam süresiyle ilgili bir hata alırsanız, değeri kuruluşunuzun endDateTime ilkesiyle uyumlu olacak şekilde azaltın.

Oluşturulan değerleri güvenli bir şekilde depolamayı passwordCredential unutmayın. İlk oluşturma işleminden sonra görüntülenemez. Kimlik bilgileri olarak istemci sertifikalarını da kullanabilirsiniz; Bkz. Sertifika kimlik bilgisi ekleme.

Şablonla oluşturulan aracılar, aracının bir kullanıcı adına çalıştığı etkileşimli aracıları destekleyecekse, aracı ön ucunun aracı arka ucuna bir erişim belirteci geçirebilmesi için şablonunuzun bir kapsamı açık hale getirmesi gerekir. Bu belirteç daha sonra aracı arka ucu tarafından kullanıcı adına işlem yapmak üzere bir erişim belirteci almak için kullanılabilir.

Tanımlayıcı URI'si ve kapsamı yapılandırma

Herhangi bir web API'sinde olduğu gibi kullanıcılardan ve diğer aracılardan gelen istekleri almak için, aracı kimliği şemanız için bir tanımlayıcı URI'sini ve OAuth kapsamını tanımlamanız gerekir:

Bu isteği göndermek için:

  • iznine AgentIdentityBlueprint.UpdateAuthProperties.Allihtiyacınız vardır.
  • Yer tutucuyu <agent-blueprint-id> aracı kimliği şemasıyla appId değiştirin.
  • Genel Benzersiz Tanımlayıcı (GUID) gerekir. PowerShell'de [guid]::NewGuid() çalıştırın veya bir çevrimiçi GUID oluşturucu kullanın. Oluşturulan GUID'yi kopyalayın ve yer tutucuyu <generate-a-guid> değiştirmek için kullanın.
PATCH https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "identifierUris": ["api://<agent-blueprint-id>"],
    "api": {
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access agent",
          "id": "<generate-a-guid>",
          "isEnabled": true,
          "type": "User",
          "value": "access_agent"
        }
      ]
  }
}

Başarılı bir çağrı, HTTP 204 yanıtı oluşturur.

Temsilci şeması temel oluşturma

Bu adımda, aracı kimliği şeması için bir sorumlu oluşturursunuz. Daha fazla bilgi için bkz. Aracı kimlikleri, hizmet sorumluları ve uygulamalar.

Önceki adımın sonuçlarından kopyaladığınız <agent-blueprint-app-id> yer tutucusuyla appId yer tutucusunu değiştirin.

POST https://graph.microsoft.com/v1.0/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "appId": "<agent-blueprint-app-id>"
}

Aracı şemanız artık hazır ve Microsoft Entra yönetim merkezinde görünür durumda. Sonraki adımda aracı kimlikleri oluşturmak için bu şemayı kullanacaksınız.

Aracı kimliği şablonunu sil

Bir aracı kullanımdan kaldırıldığında, ilişkili aracı kimliği şemasını silin. Kılavuzun silinmesi, tüm alt aracı kimliklerinin ve ajanların kullanıcı hesaplarının otomatik olarak temizlenmesini tetikler. Adım adım silme ve geri yükleme yönergeleri için bkz. Aracı kimliği nesnelerini silme ve geri yükleme.

Sonraki adım

Aracı kimliklerini oluşturma ve silme

  • Last updated on