Tworzenie strategii tożsamości agenta

Strategia tożsamości agenta służy do tworzenia tożsamości agenta i żądań tokenów przy użyciu tych tożsamości agenta. Podczas tworzenia strategii tożsamości agenta należy ustawić właściciela i sponsora tej strategii, aby ustanowić relacje odpowiedzialności i administracyjne. Można również skonfigurować identyfikator URI i zdefiniować zakres dla agentów utworzonych na podstawie tego szablonu, jeśli agent jest przeznaczony do odbierania żądań przychodzących od innych agentów i użytkowników.

Strategię tożsamości agenta można utworzyć na dwa sposoby:

• centrum administracyjne Microsoft Entra — użyj kreatora do szybkiej konfiguracji, która tworzy szablon i jego główny składnik zabezpieczeń.
• Microsoft interfejs Graph API lub PowerShell — utwórz i w pełni skonfiguruj plan programowo, w tym poświadczenia, identyfikatory URI, zakresy i główną jednostkę planu w jednym przepływie pracy.

Wymagania wstępne

Aby utworzyć strategię tożsamości agenta, potrzebne są następujące elementy:

• rola Administrator ról jest najmniej uprzywilejowaną rolą wymaganą do udzielenia uprawnień aplikacji Microsoft Graph.
• Administrator aplikacji Cloud lub Administrator aplikacji musi udzielić delegowanych uprawnień Microsoft Graph.
• Zarówno role dewelopera identyfikatora agenta, jak i administratora identyfikatora agenta mogą tworzyć szablony tożsamości agenta i główne elementy szablonów tożsamości agenta.
  • Deweloper identyfikatora agenta może skonfigurować poświadczenia tożsamości federacyjnej w szablonie tożsamości agenta.
  • Administrator identyfikatora agenta może skonfigurować poświadczenia tożsamości federacyjnej na wzorcu tożsamości agenta i jest zobowiązany do dodania poświadczenia tajnego lub poświadczenia certyfikatu.
• W przypadku korzystania z programu PowerShell wymagana jest wersja 7.

Przygotowywanie środowiska

Aby usprawnić proces, pośmiń kilka chwil, aby skonfigurować środowisko pod kątem odpowiednich uprawnień.

Autoryzowanie klienta do tworzenia strategii tożsamości agenta

W tym artykule użyjesz programu Microsoft Graph PowerShell lub innego klienta do utworzenia strategii tożsamości agenta. Musisz autoryzować tego klienta, aby utworzyć i skonfigurować szablon tożsamości agenta oraz utworzyć główną jednostkę szablonu tożsamości agenta. Klient wymaga następujących uprawnień Microsoft Graph:

• AgentIdentityBlueprint.Create delegowane uprawnienie
• AgentIdentityBlueprint.AddRemoveCreds.All delegowane uprawnienie
• AgentIdentityBlueprint.UpdateAuthProperties.All delegowane uprawnienia
• AgentIdentityBlueprintPrincipal.Create delegowane uprawnienie

Kroki opisane w tym przewodniku korzystają ze wszystkich delegowanych uprawnień, ale w tych scenariuszach, które ich wymagają, można użyć uprawnień aplikacji.

Aby nawiązać połączenie ze wszystkimi wymaganymi zakresami dla programu Microsoft Graph PowerShell, uruchom następujące polecenie:

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

Tworzenie strategii tożsamości agenta

Szablony tożsamości agenta muszą mieć sponsora, którym jest użytkownik lub obsługiwana grupa, która jest odpowiedzialna za agenta. Zalecany jest właściciel, czyli użytkownik lub jednostka usługi, która może wprowadzać zmiany w strategii tożsamości agenta. Aby uzyskać informacje, zobacz Relacje administracyjne w Identyfikator agenta Microsoft Entra.

Korzystanie z centrum administracyjne Microsoft Entra

Strategię tożsamości agenta można utworzyć bezpośrednio w centrum administracyjne Microsoft Entra. Kreator administracyjnego centrum automatycznie tworzy szablon tożsamości agenta i jego główny element szablonu.

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra.

2. Przejdź do Entra ID>Agents>Szablony agentów.

3. Wybierz pozycję Nowa strategia agenta (wersja zapoznawcza).

4. Na karcie Podstawy wprowadź nazwę w polu Nazwa szablonu agenta i wybierz Dalej.

   

5. Na karcie Właściciele i sponsorzy opcjonalnie zmień lub dodaj właścicieli i sponsorów dla strategii:

   • Wybierz ikonę ołówka obok pola Właściciele , aby zmienić lub dodać użytkowników, którzy mogą zarządzać strategią.
   • Wybierz ikonę ołówka obok pola Sponsorzy , aby zmienić lub dodać użytkowników, którzy mogą sponsorować strategię.

   Uwaga / Notatka

   Sponsorzy mogą być użytkownikami, dynamicznymi grupami członkostwa lub grupami Microsoft 365. Grupy zabezpieczeń i grupy z możliwością przypisywania ról nie są obsługiwane jako sponsorzy.

6. Wybierz Dalej.

7. Przejrzyj ustawienia, a następnie wybierz pozycję Utwórz.

8. Wybierz Gotowe, aby zamknąć kreatora lub przejdź do szablonu agenta, aby wyświetlić stronę szczegółów szablonu lub skonfigurować dodatkowe ustawienia.

Aby uzyskać więcej informacji na temat zarządzania strategiami tożsamości agenta, zobacz Zarządzanie strategiami tożsamości agenta.

Tworzenie programistyczne

Aby utworzyć strategię tożsamości agenta przy użyciu kodu, użyj programu Microsoft interfejs Graph API lub programu PowerShell.

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>"
  ]
}

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

$currentUser = Get-MgContext | Select-Object -ExpandProperty Account
$user = Get-MgUser -UserId $currentUser

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


$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

$response = Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint" `
    -Headers @{ "OData-Version" = "4.0" } `
    -Body $body `
    -ContentType "application/json"

$response

Konfigurowanie poświadczeń dla szablonu tożsamości agenta

Aby zażądać tokenów dostępu przy użyciu szablonu tożsamości agenta, należy dodać poświadczenie client. Zalecamy używanie tożsamości zarządzanej jako poświadczenia tożsamości federacyjnej (FIC) na potrzeby wdrożeń produkcyjnych. Tożsamości zarządzane umożliwiają uzyskiwanie tokenów Microsoft Entra bez konieczności zarządzania poświadczeniami. Aby uzyskać więcej informacji, zobacz Tożsamości zarządzane dla zasobów Azure.

Inne rodzaje poświadczeń aplikacji, w tym keyCredentials i passwordCredentials są obsługiwane, ale nie są zalecane w środowisku produkcyjnym. Mogą one być wygodne w przypadku lokalnego programowania i testowania lub gdy tożsamości zarządzane nie będą działać, ale te opcje nie są zgodne z najlepszymi rozwiązaniami w zakresie zabezpieczeń. Aby uzyskać więcej informacji, zobacz Najlepsze rozwiązania dotyczące zabezpieczeń dotyczące właściwości aplikacji.

Należy pamiętać, że aby używać tożsamości zarządzanej, musisz uruchomić kod w usłudze Azure, takiej jak maszyna wirtualna lub Azure App Service. W przypadku lokalnego programowania i testowania należy użyć klucza tajnego klienta lub certyfikatu.

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"
    ]
}

Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

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

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

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

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

Inne poświadczenia aplikacji

W przypadku scenariuszy, w których tożsamości zarządzane nie będą działać lub jeśli tworzysz strategię lokalnie na potrzeby testowania, wykonaj następujące kroki, aby dodać poświadczenia.

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"
  }
}

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

$applicationId = "<agent-blueprint-application-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)"

Pamiętaj, aby bezpiecznie przechowywać wygenerowane passwordCredential wartości. Nie można go wyświetlić po początkowym utworzeniu. Certyfikaty klienta można również używać jako poświadczenia; zobacz Dodaj poświadczenie certyfikatu.

Jeśli agenci utworzeni za pomocą szablonu będą obsługiwać agentów interaktywnych, w których agent działa w imieniu użytkownika, szablon musi uwidocznić zakres, aby przedni interfejs agenta mógł przekazać token dostępu do zaplecza agenta. Ten token może być następnie używany przez zaplecze agenta w celu uzyskania tokenu dostępu do działania w imieniu użytkownika.

Konfiguracja identyfikatora URI i zakresu

Aby odbierać żądania przychodzące od użytkowników i innych agentów, podobnie jak w przypadku dowolnego internetowego interfejsu API, należy zdefiniować identyfikator URI i zakres OAuth dla strategii tożsamości agenta:

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"
        }
      ]
  }
}

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

$AppId = "<agent-blueprint-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) }

Tworzenie podmiotu głównego szablonu agenta

W tym kroku utworzysz obiekt zasadniczy dla szablonu tożsamości agenta. Aby uzyskać więcej informacji, zobacz Tożsamości agenta, zasady usługi i aplikacje.

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>"
}

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

Strategia agenta jest teraz gotowa i widoczna w centrum administracyjne Microsoft Entra. W następnym kroku użyjesz tej strategii, aby utworzyć tożsamości agentów.

Rejestrowanie agentów w rejestrze agenta 365

Po utworzeniu strategii tożsamości agenta zarejestruj ją w rejestrze Agent 365 aby administratorzy mogli odnajdywać i zarządzać agentem z Centrum administracyjne platformy Microsoft 365 oraz zarządzać nim. Ta sekcja zawiera również instrukcje dotyczące dodawania istniejących planów tożsamości agenta, które mogą obecnie nie być wyświetlane w rejestrze Agent 365.

Użyj Zestaw SDK agentów usługi Microsoft 365 (zalecane)

Zestaw SDK agentów usługi Microsoft 365 jest teraz ogólnie dostępny i jest zalecanym sposobem kompilowania i aprowizacji agentów. Zestaw SDK obsługuje tworzenie i rejestrację tożsamości agenta w rejestrze Agent 365, dzięki czemu tożsamości agentów będą wyświetlane automatycznie bez dodatkowego kodu. Jeśli uruchamiasz nowy projekt agenta lub masz elastyczność migracji istniejącego kodu, użyj zestawu SDK. Jest to najprostsza, najbardziej trwała ścieżka i pozwala uniknąć konieczności koordynowania wielu wywołań interfejsu API samodzielnie.

Użyj Agent 365 CLI

Interfejs Agent CLI 365 to kolejna opcja, która zajmuje się konfiguracją, w tym rejestracją agenta. Postępuj zgodnie z instrukcjami konfiguracji, korzystając z zalecanej kolejności wykonywania. Użyj następującego polecenia:

a365 setup all

Jeśli rejestracja nie powiedzie się, możesz ponownie uruchomić tylko krok rejestracji bez konieczności przechodzenia przez cały proces. Użyj następującego polecenia:

a365 setup all --agent-registration-only

Wywołaj bezpośrednio interfejs API rejestru agentów

Jeśli musisz programowo utworzyć szablony tożsamości agenta za pomocą interfejs Graph API firmy Microsoft, na przykład dlatego, że masz istniejące procesy wystawiania tożsamości, których nie można zmienić natychmiast, możesz dodać jawne wywołanie Agent Registry API po utworzeniu szablonu tożsamości agenta w celu opublikowania odpowiedniej karty agenta. Ten krok rejestruje kartę agenta w rejestrze agenta 365, aby była wyświetlana dla administratorów.

1. Utwórz strategię tożsamości agenta przy użyciu interfejs Graph API Microsoft (jak pokazano w poprzednich sekcjach).
2. Natychmiast wykonaj wywołanie interfejsu API Rejestru Agentów, aby opublikować odpowiednią kartę agenta, w tym metadane niezbędne do zarządzania nią przez administratorów.
3. Obsłuż wzorzec dwóch wywołań w bezpieczny sposób, aby awaria przejściowa w obu wywołaniach pozostawiła środowisko w stanie umożliwiającym odzyskanie.

Aby zapoznać się ze schematami żądań i odpowiedzi, wymaganymi uprawnieniami i przykładami kodu, zobacz dokumentację interfejsu API rejestru agentów.

Istniejące plany tożsamości agenta, które nie są w rejestrze Agent 365

W przypadku szablonów tożsamości agenta, które zostały wcześniej utworzone przy użyciu Identyfikator agenta Microsoft Entra interfejs Graph API, ale nie są obecnie widoczne w rejestrze Agenta 365, można je zarejestrować przy użyciu interfejsu API rejestru Agentów. Ten krok zapewnia pojawienie się ich w rejestrze agent 365.

Usuń schemat tożsamości agenta

Po zlikwidowaniu agenta usuń skojarzony plan tożsamości agenta. Usunięcie strategii powoduje automatyczne czyszczenie wszystkich tożsamości agentów podrzędnych i kont użytkowników agentów. Aby uzyskać instrukcje krok po kroku dotyczące usuwania i przywracania, zobacz Usuwanie i przywracanie obiektów tożsamości agenta.

Następne kroki