Erstellen eines Agentidentitäts-Blueprints

Ein Agentidentitäts-Blueprint wird verwendet, um Agentidentitäten zu erstellen und Token mithilfe dieser Agentidentitäten anzufordern. Dieser Leitfaden führt Sie durch das Erstellen eines Agentidentitäts-Blueprints mit der Microsoft Graph-REST-API und Microsoft Graph PowerShell.

Voraussetzungen

Stellen Sie vor dem Erstellen Ihrer Agentenidentitäts-Plan sicher, dass Sie Folgendes haben:

Verstehen von Blueprints der Agentenidentität
Zum Erteilen von Berechtigungen ist ein privilegierter Rollenadministrator erforderlich.
Eine der folgenden Rollen, die zum Erstellen eines Blueprints erforderlich sind: Agent-ID-Entwickler oder Agent-ID-Administrator. Bevorzugen Sie die Rolle "Agent-ID-Administrator".

Autorisierung eines Clients zur Erstellung von Agentenidentitätsvorlagen

In diesem Artikel verwenden Sie Microsoft Graph PowerShell oder einen anderen Client, um Ihren Agent-Identitäts-Blueprint zu erstellen. Sie müssen diesen Client autorisieren, um einen Agentidentitäts-Blueprint zu erstellen. Der Client erfordert eine der folgenden Microsoft Graph-Berechtigungen:

AgentIdentityBlueprint.Create (delegierte Berechtigung)
AgentIdentityBlueprint.Create (Anwendungsberechtigung)

Nur ein globaler Administrator oder ein Privilegierter Rollenadministrator kann dem Client diese Berechtigungen erteilen. Um diese Berechtigungen zu erteilen, kann ein Administrator:

Verwenden Sie den Befehl Connect-MgGraph.
Führen Sie ein Skript aus, um ein oAuth2PermissionGrant oder appRoleAssignment im Mandanten zu erzeugen.

Erstellen eines Agentidentitäts-Blueprints

Das Erstellen eines Identitätsentwurfs für Funktionsagenten in Ihrem Mandanten erfordert zwei Schritte.

Erstellen Sie einen AgentIdentityBlueprint im Mandanten.
Erstellen Sie einen AgentIdentityBlueprintPrincipal im Mandanten.

Die in diesem Fall erstellte Hauptentität unterscheidet sich von der vom Agenten verwendeten Agentidentität.

Microsoft Graph-API
Microsoft Graph PowerShell

Rufen Sie zuerst ein Zugriffstoken mit der Berechtigung AgentIdentityBlueprint.Create ab. Sobald Sie über ein Zugriffstoken verfügen, führen Sie die folgende Anforderung aus.

Tipp

Fügen Sie bei Verwendung von @odata.type immer die OData-Version in die Kopfzeile ein.

POST https://graph.microsoft.com/beta/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>"
	]
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create","User.Read" -TenantId <your-tenant>

# Get the current user's ID
$currentUser = Get-MgContext | Select-Object -ExpandProperty Account
$user = Get-MgUser -UserId $currentUser

Write-Host "Current user: $($user.DisplayName) ($($user.Id))"

# Construct the body for the POST request
$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = "My Agent Identity Blueprint"
    "sponsors@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$($user.Id)")
    "owners@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$($user.Id)")
} | ConvertTo-Json -Depth 5

# Make the POST request to create the agent identity blueprint application
$response = Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/beta/applications/graph.agentIdentityBlueprint" `
    -Body $body `
    -ContentType "application/json"

# Output the response
$response

Nachdem Sie einen Agent-Identitäts-Blueprint erstellt haben, notieren Sie dessen appId für die nächsten Schritte im Handbuch. Erstellen Sie als Nächstes einen Dienstprinzipal für Ihren Agent-Identitäts-Blueprint:

Microsoft Graph-API
Microsoft Graph PowerShell

Um den Dienstprinzipal zu erstellen, müssen Sie zuerst ein Zugriffstoken mit der Berechtigung AgentIdentityBlueprint.Create erhalten. Sobald Sie über ein Zugriffstoken verfügen, führen Sie die folgende Anforderung aus:

Tipp

Fügen Sie bei Verwendung von @odata.type immer die OData-Version in die Kopfzeile ein.

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

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

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId <your-test-tenant>
$body = @{
    appId   = "<agent-blueprint-client-id>"
}
Invoke-MgGraphRequest -Method POST `
        -Uri "https://graph.microsoft.com/beta/serviceprincipals/graph.agentIdentityBlueprintPrincipal" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Konfigurieren von Anmeldeinformationen für den Agentidentitäts-Blueprint

Um Zugriffstoken mithilfe des Agentidentitäts-Blueprints anzufordern, müssen Sie eine Clientanmeldeinformation hinzufügen. Es wird empfohlen, eine verwaltete Identität als Verbundidentität-Anmeldeinformationen für Bereitstellungen in der Produktion zu verwenden. Verwenden Sie für lokale Entwicklung und Tests einen geheimen Clientschlüssel.

Fügen Sie eine verwaltete Identität als Berechtigungsnachweis mithilfe der folgenden Anforderung hinzu:

Microsoft Graph-API
Microsoft Graph PowerShell

Um diese Anforderung zu senden, müssen Sie zuerst ein Zugriffstoken mit der Berechtigung AgentIdentityBlueprint.AddRemoveCreds.Allabrufen.

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

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

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

$applicationId = "<agent-blueprint-object-id>"

$federatedCredential = @{
  Name             = "my-msi"
  Issuer           = "https://login.microsoftonline.com/<my-test-tenant-id>/v2.0"
  Subject          = "<msi-principal-id>"
  Audiences         = @("api://AzureADTokenExchange")
}

New-MgApplicationFederatedIdentityCredential `
  -ApplicationId $applicationId `
  -BodyParameter $federatedCredential

In einigen Mandanten werden auch andere Arten von App-Anmeldeinformationen, einschließlich keyCredentials, passwordCredentials und trustedSubjectNameAndIssuers, unterstützt. Diese Arten von Anmeldeinformationen werden für die Produktion nicht empfohlen, können aber für die lokale Entwicklung und Tests geeignet sein. Um ein Passwort-Zertifikat hinzuzufügen:

Microsoft Graph-API
Microsoft Graph PowerShell

Um diese Anforderung zu senden, müssen Sie zuerst ein Zugriffstoken mit der delegierten Berechtigung abrufen. AgentIdentityBlueprint.AddRemoveCreds.All

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

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

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

$applicationId = "<agent-blueprint-object-id>"

# Define the secret properties
$displayName = "My Secret"
$endDate = (Get-Date).AddYears(1).ToString("o")  # 1 year from now, in ISO 8601 format

# Construct the password credential
$passwordCredential = @{
    displayName = $displayName
    endDateTime = $endDate
}

# Add the password (client secret)
$response = Add-MgApplicationPassword -ApplicationId $applicationId -PasswordCredential $passwordCredential

# Output the generated secret (only returned once!)
Write-Host "Secret Text: $($response.secretText)"

Achten Sie darauf, den passwordCredential generierten Wert sicher zu speichern. Sie kann nach der ersten Erstellung nicht angezeigt werden. Sie können Clientzertifikate auch als Anmeldeinformationen verwenden; siehe Hinzufügen von Zertifikatanmeldeinformationen.

Konfigurieren des Bezeichner-URI und -Bereichs

Um eingehende Anforderungen von Benutzern und anderen Agents empfangen zu können, müssen Sie eine Identifikator-URI und einen OAuth-Bereich für Ihren Agenten-Identitätsentwurf definieren.

Microsoft Graph-API
Microsoft Graph PowerShell

Um diese Anforderung zu senden, müssen Sie zuerst ein Zugriffstoken mit der Berechtigung AgentIdentityBlueprint.ReadWrite.Allabrufen.

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-object-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"
        }
      ]
  }
}

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

$AppId = "<agent-blueprint-object-id>"
$IdentifierUri = "api://<agent-blueprint-id>"
$ScopeId = [guid]::NewGuid()

# Construct the OAuth2 permission scope
$scope = @{
    adminConsentDescription = "Allow the application to access the agent on behalf of the signed-in user."
    adminConsentDisplayName = "Access agent"
    id = $ScopeId
    isEnabled = $true
    type = "User"
    value = "access_agent"
}

Update-MgApplication -ApplicationId $AppId `
    -IdentifierUris @($IdentifierUri) `
    -Api @{ oauth2PermissionScopes = @($scope) }

Erstellen und Löschen von Agentidentitäten

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-19

Freigeben über

Erstellen eines Agentidentitäts-Blueprints

Voraussetzungen

Autorisierung eines Clients zur Erstellung von Agentenidentitätsvorlagen

Erstellen eines Agentidentitäts-Blueprints

Konfigurieren von Anmeldeinformationen für den Agentidentitäts-Blueprint

Konfigurieren des Bezeichner-URI und -Bereichs

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen