Registrering av anpassade klientappar för Agent 365 CLI

Agent 365 CLI kräver en anpassad klientapplikationsregistrering i din Microsoft Entra ID-hyresgäst för att autentisera och hantera agentidentitetsmallar.

Den här artikeln delar upp processen i fyra huvudsteg:

1. Registrera app
2. Ange omdirigerings-URI
3. Kopiera App-ID (klient)
4. Konfigurera API-behörigheterKräver administratörsbehörigheter
5. Lägg till wids-rollclaimen

Om du har problem, se avsnittet Felsökning.

Krav

Innan du börjar, se till att du har tillgång till Microsoft Entra administrationscenter och, om det behövs, en av de nödvändiga administratörsrollerna för att bevilja samtycke.

För att registrera appen

Som standard kan vilken användare som helst i klientorganisationen registrera applikationer i Microsoft Entra administrationscenter. Dock kan klientorganisationsadministratörer begränsa denna möjlighet. Om du inte kan registrera din app, kontakta din administratör.

Lägg till behörigheter och bevilja samtycke

Du behöver en av dessa administrativa roller för 4. Konfigurera API-behörigheter.

• Applikationsadministratör: Rekommenderas – kan hantera appregistreringar och ge samtycke
• Cloud-applikationsadministratör: Kan hantera appregistreringar och ge samtycke
• Global administratör: Har alla behörigheter, men krävs inte

1. Registrera app

Dessa instruktioner sammanfattar de fullständiga instruktionerna för att skapa en appregistrering.

1. Gå till Microsoft Entra administrationscenter

2. Välj App-registreringar

3. Välj Ny registrering

4. Skriv in:

   • Namn: Ange ett meningsfullt namn för din app, till exempel my-agent-app. Appanvändare ser detta namn, och du kan ändra det när som helst. Du kan ha flera appregistreringar med samma namn.

     Dricks

     Om du vill använda det konfigurationsfria a365 setup all --agent-name flödet, namnge appen exakt Agent 365 CLI. CLI:n söker automatiskt upp klientappen via detta välkända visningsnamn, så du behöver inte kopiera klient-ID:t till en konfigurationsfil.

   • Kontotyper som stöds:Endast konton i den här organisationskatalogen (enskild klientorganisation)

   • Omdirigera URI: Välj Publik klient/inbyggt (mobil & dator) och ange http://localhost:8400/

5. Välj Registrera

CLI kräver totalt tre omdirigerings-URI:er. CLI lägger automatiskt till de som saknas när du kör:a365 setup requirements

Se Vad CLI automatiskt konfigurerar för mer information.

2. Ange omdirigerings-URI

1. Gå till Översikt och kopiera värdet App-ID (klient).
2. Gå till Autentisering (förhandsversion) och välj sedan Lägg till omdirigerings-URI.
3. Välj mobil- och skrivbordsapplikationer och sätt värdet till ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, där {client-id} är applikationsvärdet (klient-ID) du kopierade.
4. Välj Konfigurera för att lägga till värdet.

3. Kopiera App-ID (klient)

Från appens Översikt-sida, kopiera Application (client) ID i GUID-format. Du använder detta värde när du kör a365 setup all eller när du manuellt skapar a365.config.json.

4. Konfigurera API-behörigheter

Välj lämplig anslutningsmetod:

• Alternativ A: Använd Microsoft Entra administrationscenter för alla behörigheter (om betabehörigheter är synliga)
• Alternativ B: Använd Microsoft Graph API för att lägga till alla behörigheter (rekommenderas om betabehörigheter inte syns)

Alternativ A: Microsoft Entra administrationscenter (standardmetoden)

Använd denna metod om du kan se betabehörigheter i din organisation.

1. I din App-registrering går du till API-behörigheter.

2. Välj Lägg till behörighet>Microsoft Graph>Delegerade behörigheter.

   Viktigt

   Du måste använda delegerade behörigheter (inte applikationsbehörigheter). CLI autentiserar interaktivt – du loggar in och den agerar åt dig. För att lära dig mer, se Fel behörighetstyp.

3. Lägg till dessa sju behörigheter en efter en:

   Behörighet	Syfte
   AgentIdentityBlueprint.ReadWrite.All	Blueprint-skapande, klienthemlighetshantering, ärftliga behörigheter, federerade identitetsuppgifter och radering (beta-API)
   AgentIdentityBlueprintPrincipal.Create	Skapa Agent Blueprint service principal (beta-API)
   AgentIdentity.Read.All	Idempotenskontroll och sökning efter tjänsteenhet för agentidentitet (beta-API)
   AgentIdentity.DeleteRestore.All	Ta bort agentidentitetstjänsteprinciper under rensning (beta-API)
   AgentRegistration.ReadWrite.All	Läs och skriv alla agentregistreringar
   Application.Read.All	Sökning av tjänstehuvudkonto via app-ID (mer begränsat alternativ till Directory.Read.All)
   User.Read	Läs inloggad användarprofil för att tilldela blueprint-ägare och sponsor

   Kommentar

   AgentRegistration.ReadWrite.All krävs för agentuppsättning. CLI-validatorn kontrollerar uttryckligen denna behörighet. Det måste finnas i din appregistrering och ha administratörens godkännande.

   För varje behörighet:

   • I sökrutan, skriv in behörighetsnamnet (till exempel AgentIdentityBlueprint.ReadWrite.All).
   • Markera kryssrutan bredvid behörigheten.
   • Välj Lägg till behörigheter.
   • Upprepa för alla sju behörigheter.

4. Välj Bevilja administratörsmedgivande för [din klientorganisation].

   • Varför behövs detta? agentidentitetsmallar är hyresgästövergripande resurser som flera användare och applikationer kan referera till. Utan samtycke på hyresgästnivå misslyckas CLI:n under autentiseringen.
   • Vad händer om det misslyckas? Du måste ha rollen Applikationsadministratör, Molnapplikationsadministratör eller Global administratör. Be administratören för klientorganisationen om hjälp.

5. Kontrollera att alla behörigheter visar gröna bockar under Status.

Om betabehörigheterna (AgentIdentityBlueprint.*) inte syns, gå vidare till Alternativ B.

Alternativ B: Microsoft Graph API (för betabehörigheter)

Använd denna metod om Microsoft Entra administrationscenter inte visar AgentIdentityBlueprint.* behörigheter.

1. Öppna Grafutforskare

2. Logga in med ditt administratörskonto (Application Administrator eller Cloud Application Administrator).

3. Ge administratörsgodkännande genom att använda Graph API. För att slutföra det här steget behöver du:

   • ID för tjänstens huvudkonto. Du måste ha variabelt värde för SP_OBJECT_ID.
   • Microsoft Graph-resurs-ID. Du måste ha variabelt värde för GRAPH_RESOURCE_ID.
   • Skapa (eller uppdatera) delegerade behörigheter genom att använda resurstypen oAuth2PermissionGrant med värdena för variablerna SP_OBJECT_ID och GRAPH_RESOURCE_ID.

Använd informationen i följande avsnitt för att slutföra dessa steg.

Hämta ditt service principal-ID

En service principal är din apps identitet i din tenant. Du behöver det innan du kan ge behörigheter via API:et.

1. Ställ in Graph Explorer-metoden till GET och använd denna URL. Ersätt <YOUR_CLIENT_APP_ID> med ditt faktiska applikations-ID från Steg 3: Kopiera applikations-ID:

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
   

2. Välj Kör fråga.

   • Om frågan lyckas är värdet ditt SP_OBJECT_ID.

   • Om frågan misslyckas på grund av behörighetsfel, välj fliken Ändra behörigheter, samtyck till de nödvändiga behörigheterna och välj sedan Kör fråga igen. Värdet som returneras är ditt SP_OBJECT_ID.

   • Om frågan returnerar tomma resultat ("value": []), skapa tjänsteprincipen genom att följa dessa steg:

     1. Ange metod till POST och använd denna URL:

        https://graph.microsoft.com/v1.0/servicePrincipals
        

        Begärandetext (ersätt YOUR_CLIENT_APP_ID med ditt verkliga applikationsklient-ID):

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. Välj Kör fråga. Du får ett 201 Created-svar. Värdet som id returnerar är ditt SP_OBJECT_ID.

Hämta ditt Graph-resurs-ID

1. Ställ in Graph Explorer-metoden på GET och använd denna URL:

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
   

2. Välj Kör fråga.

   • Om sökfrågan lyckas, kopiera id värdet. Detta värde är din GRAPH_RESOURCE_ID.
   • Om frågan misslyckas på grund av behörighetsfel, välj fliken Ändra behörigheter, samtyck till de nödvändiga behörigheterna och välj sedan Kör fråga igen. Kopiera värdet id . Detta värde är din GRAPH_RESOURCE_ID.

Välj delegerade behörigheter

Detta API-anrop ger hyresövergripande administratörssamtycke för alla sju behörigheter, inklusive betabehörigheter som inte är synliga i Microsoft Entra administrationscenter.

1. Sätt Graph Explorer-metoden till POST och använd denna URL och förfrågningskropp:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants
   

   Begärandetext

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
   }
   

2. Välj Kör fråga.

   • Om du får 201 Created svar: Lyckat! Fältet scope i svaret visar alla sju behörighetsnamn. Klart!
   • Om sökningen misslyckas med ett behörighetsfel, välj fliken Ändra behörigheter, samtyck till de nödvändiga behörigheterna och välj Kör fråga igen.
   • Om du får fel Request_MultipleObjectsWithSameKeyValue: Ett godkännande finns redan. Kanske har någon lagt till behörigheter tidigare. Se följande: Uppdatera delegerade behörigheter.

Uppdatera delegerade behörigheter

När du får ett Request_MultipleObjectsWithSameKeyValue-fel när du använder stegen för att skapa delegerade behörigheter, använd dessa steg för att uppdatera de delegerade behörigheterna.

1. Ställ in Graph Explorer-metoden på GET och använd denna URL:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
   

2. Välj Kör fråga. Kopiera id-värdet från svaret. Detta värde är YOUR_GRANT_ID.

3. Ställ in Graph Explorer-metoden på PATCH och använd denna URL med YOUR_GRANT_ID.

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>
   

   Begärandetext

   {
      "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
   }
   

4. Välj Kör fråga. Du bör få ett 200 OK svar med alla sju behörigheter i fältet scope.

5. Lägg till wids-rollanspråket

Agent 365 CLI läser dina Entra-katalogrolltilldelningar direkt från åtkomsttoken för att avgöra om du har administratörsrättigheter. Detta kräver att du lägger till anspråket wids till åtkomsttokens som utfärdas för din appregistrering.

Utan detta påstående kan CLI inte upptäcka din roll och återgår till att visa PowerShell-instruktioner för varje steg som kräver administratörsrättigheter – även när du är administratör. Slutför detta steg för att få rätt beteende.

1. I din appregistrering, gå till Tokenkonfiguration.

2. Välj Lägg till ytterligare anspråk.

3. För tokentyp, välj Åtkomst.

4. I listan över skadeanmälningar, kryssa i rutan bredvid WIDS.

5. Välj Lägg till.

   Om du ombeds att slå på Microsoft Graph-behörigheten profile för att möjliggöra anspråket, välj Ja, lägg till.

Metodtips för säkerhet

Se över dessa riktlinjer för att säkerställa att din appregistrering är säker och följer gällande krav.

Rätt:

• Använd enkelhyresgästregistrering.
• Bevilja endast de delegerade behörigheter som krävs.
• Granska behörigheter regelbundet.
• Ta bort appen när den inte längre behövs.

Fel:

• Bevilja appbehörigheter. Använd endast delegerade.
• Dela klient-ID:t offentligt.
• Ge andra behörigheter som inte behövs.
• Använd appen till andra ändamål.

Vad CLI automatiskt konfigurerar

När du kör a365 setup requirements, validerar CLI:n din appregistrering och kan behöva göra ändringar. Innan några ändringar görs visar CLI en sammanfattning och ber om bekräftelse:

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

För att hoppa över bekräftelseprompten (till exempel i en CI-miljö), använd flaggan --yes:

a365 setup requirements --yes

Följande tabell beskriver varje ändring som CLI:n kan göra:

Om du avböjer uppmaningen ändrar CLI inte din appregistrering. Om ändringar krävs för att CLI:n ska fungera kan du konfigurera dem manuellt i Microsoft Entra administrationscenter eller köra igen med --yes.

Nästa steg

När du har registrerat din anpassade klientapp, använd den tillsammans med Agent 365 CLI för att slutföra din Agent 365-konfiguration:

Felsökning

I detta avsnitt beskrivs hur du felsöker problem med registrering av anpassade klientappar.

CLI-validering misslyckas vid konfiguration

Symptom: Om du kör a365 setup eller a365 setup requirements misslyckas det på grund av valideringsfel om din anpassade klientapp.

Lösning: Använd denna checklista för att verifiera att din appregistrering är korrekt:

# Run requirements validation to see validation messages
a365 setup requirements

Förväntat resultat: CLI visar Custom client app validation successful.

Om du inte får det förväntade resultatet, verifiera var och en av följande kontroller:

Obligatoriska delegerade behörigheter:

• AgentIdentityBlueprint.ReadWrite.All [Beta]
• AgentIdentityBlueprintPrincipal.Create [Beta]
• AgentIdentity.Read.All [Beta]
• AgentIdentity.DeleteRestore.All [Beta]
• AgentRegistration.ReadWrite.All
• Application.Read.All
• User.Read

Se Administratörsgodkännande felaktigt beviljat

Symptom: Validering misslyckas även om du lagt till behörigheter

Grundorsak: Du gav inte administratörens samtycke, eller så gav du det felaktigt.

Lösning: I din appregistrering i Microsoft Entra administrationscenter, gå till API-behörigheter och välj Bevilja administratörsgodkännande för [Din hyresgäst]. Kontrollera att alla behörigheter visar gröna bockar under Status.

Blueprint-skapande misslyckas med "Administratörssamtycke har inte beviljats"

Symptom: a365 setup allskriver ut "Successfully ensured delegated application consent" men misslyckas sedan omedelbart vid blueprint-skapande med:

Admin consent has not been granted for this application.
Share this URL with an Application Administrator or Global Administrator to grant consent:
  https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Grundorsak: Din klientorganisation har redan en oauth2PermissionGrant post för din anpassade klientapp (från en tidigare delvis installation eller från en tidigare "Bevilja administratörsgodkännande"-åtgärd i Microsoft Entra administrationscenter för andra omfång), men den posten saknar det nödvändiga omfånget (AgentIdentityBlueprint.ReadWrite.All). CLI:n upptäcker det saknade omfånget och visar en samtyckes-URL för en administratör att slutföra beviljandet.

Lösning:

Dela samtyckeslänken som skrivs ut i felmeddelandet med en applikationsadministratör eller global administratör. URL:en ser ut så här:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Efter att administratören gett sitt samtycke, kör a365 setup all --agent-name <name> igen.

Om du har administratörsbehörighet kan du öppna URL:en direkt i en webbläsare för att ge samtycke utan att vänta.

Fel behörighetstyp

Symptom: CLI misslyckas med autentiseringsfel eller att behörighet nekas.

Grundorsak: Du har lagt till applikationsbehörigheter i stället för delegerade behörigheter.

Denna tabell beskriver de olika typerna av behörigheter.

Varför delegerad?

• Du loggar in interaktivt (webbläsarautentisering)
• CLI utför åtgärder som du (revisionsspår visar din identitet)
• Mer säker – begränsad till dina faktiska behörigheter
• Säkerställer ansvarstagande och efterlevnad

Lösning:

1. Gå till Microsoft Entra administrationscenter>App-registreringar> Din app >API-behörigheter
2. Ta bort alla applikationsbehörigheter. Dessa behörigheter visas som Applikation i kolumnen Typ.
3. Lägg till samma behörigheter som delegerade behörigheter.
4. Bevilja administratörsmedgivande igen.

Beta-behörigheter försvinner efter administratörsgodkännande i Microsoft Entra administrationscenter

Symptom: Du använde Alternativ B: Microsoft Graph API (för beta-behörigheter) för att lägga till beta-behörigheter, men de försvinner efter att du valt Bevilja administratörsgodkännande i Microsoft Entra administrationscenter.

Grundorsak: Microsoft Entra administrationscenter visar inte betabehörigheter i användargränssnittet. När du väljer Grant admin consent, ger portalen endast samtycke för de synliga behörigheterna och ersätter det samtycke som beviljats via API:et.

Varför detta händer:

1. Du använder Microsoft Graph API (Alternativ B) för att lägga till alla sju behörigheter, inklusive betabehörigheter.
2. API-anropet consentType: "AllPrincipals"beviljar redan administratörssamtycke på tenant-nivå.
3. Du går till Microsoft Entra administrationscenter och ser bara en delmängd av behörigheter eftersom beta-behörigheter är osynliga i portalen.
4. Du väljer Ge administratörssamtycke eftersom du tror att du behöver det.
5. Microsoft Entra administrationscenter skriver över ditt API-givna samtycke med endast de synliga behörigheterna.
6. Dina betabehörigheter är nu raderade.

Lösning:

• Använd inte administratörssamtycke i Microsoft Entra administrationscenter efter API-metoden: API-metoden ger redan administratörssamtycke.
• Om du av misstag tar bort beta-behörigheter, upprepa Alternativ B Steg 3 (Ge administratörstillstånd med hjälp av Microsoft Graph API) för att återställa dem. Om du får ett Request_MultipleObjectsWithSameKeyValue fel, följ stegen för att uppdatera delegerade behörigheter.
• För att verifiera att alla sju behörigheter är listade, kontrollera scope-fältet i POST- eller PATCH-svaret.

Appen kunde inte hittas vid valideringen

Symtom: CLI-rapporter Application not found eller Invalid client ID fel.

Lösning:

1. Verifiera att du kopierat applikations-ID (klient-ID) i GUID-format, inte objekt-ID:

   • Gå till Microsoft Entra administrationscenter> Appregistreringar>din app>Översikt
   • Kopiera värdet under App-ID (klientens)
   • Formatet bör vara: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Verifiera att appen finns i din klientorganisation:

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

Registrera en app i Microsoft Entra ID.