Mukautetun asiakassovelluksen rekisteröinti Agent 365 -sovellusta varten

Agent 365 CLI -sovellus tarvitsee agentin käyttäjätietojen etenemissuunnitelman todennukseen ja hallintaan Microsoft Entra ID -vuokraajaan rekisteröidyn mukautetun asiakassovelluksen.

Tämä artikkeli jakaa prosessin neljään päävaiheeseen:

  1. Sovelluksen rekisteröinti
  2. Uudelleenohjauksen URI-osoitteen määrittäminen
  3. Sovelluksen (asiakasohjelman) tunnuksen kopiointi
  4. Ohjelmointirajapinnan oikeuksien määrittäminenTarvitaan järjestelmänvalvojan käyttöoikeudet
  5. wids-rooliväitteen lisääminen

Ongelmatilanteessa lisätietoja on kohdassa Vianmääritys.

Edellytykset

Varmista, ennen aloittamista, että voit käyttää Microsoft Entra -hallintakeskukseen ja että sinulla on tarvittaessa jokin suostumuksen myöntämiseen tarvittavista järjestelmänvalvojan rooleista:

Sovelluksen rekisteröinti

Oletusarvoisesti kuka tahansa vuokraajan käyttäjä voi rekisteröidä sovelluksiaMicrosoft Entra -hallintakeskuksessa. Vuokraajan järjestelmänvalvojat voivat kuitenkin rajoittaa tätä mahdollisuutta. Jos sovelluksen rekisteröinti ei onnistu, ota yhteys järjestelmänvalvojaan.

Jokin seuraavista järjestelmänvalvojan rooleista tarvitaan vaiheessa 4. Ohjelmointirajapinnan oikeuksien määrittäminen.

Vinkki

Puuttuuko järjestelmänvalvojan käyttöoikeus? Voit suorittaa vaiheet 1–3 itse ja pyytää vuokraajan järjestelmänvalvojaa suorittamaan vaiheen 4. Toimita järjestelmänvalvojalle sovelluksen (asiakasohjelman) tunnus vaiheesta 3 ja linkki Ohjelmointirajapinnan oikeuksien määrittäminen -osaan.

Vinkki

Yleiset järjestelmänvalvojat voivat ohittaa manuaalisen rekisteröinnin. Suorita a365 setup requirements ja jos Agent 365 CLI -sovellusta ei löydy vuokraajan ympäristöstä, komentorivikäyttöliittymä pyytää luomaan sen ja myöntämään järjestelmänvalvojan suostumuksen automaattisesti. Luo sovellus yhtenä vaiheena kirjoittamalla kehotteeseen C. Jos käytät tätä automatisoitua polkua, voit ohittaa tämän osion vaiheet.

1. Sovelluksen rekisteröinti

Nämä ohjeet ovat yhteenveto sovelluksen rekisteröinnin kattavista luontiohjeista.

  1. Siirry Microsoft Entra -hallintakeskukseen.

  2. Valitse Sovelluksen rekisteröinnit

  3. Valitse Uusi rekisteröinti

  4. Syötä:

    • Nimi: Syötä sovellukselle merkityksellinen nimi, kuten my-agent-app. Sovelluksen käyttäjät näkevät tämän nimen, jonka voit vaihtaa milloin tahansa. Samalla nimellä rekisteröityjä sovelluksia voi olla useita.

      Vinkki

      Jos haluat käyttää a365 setup all --agent-name-työnkulkua, jossa määritystä ei tarvita, sovelluksen nimen on oltava täsmälleen Agent 365 CLI. Komentorivikäyttöliittyvä hakee tämän tunnetun näyttönimen omaavan asiakassovelluksen automaattisesti, joten asiakastunnusta ei tarvitse kopioida määritystiedostoon.

    • Tuetut tili: vain organisaation tässä hakemistossa olevat tilit (yksi vuokraaja)

    • Uudelleenohjauksen URI-osoite: valitse Julkinen asiakas tai alkuperäinen (mobiili ja työpöytä) ja syötä http://localhost:8400/

  5. Valitse Rekisteröi

Komentorivikäyttöliittymää edellyttää yhteensä kolme uudelleenohjauksen URI-osoitetta. Komentorivikäyttöliittymä lisää automaattisesti kaikki puuttuvat, kun a365 setup requirements suoritetaan:

URI Tarkoitus
http://localhost:8400/ Vuorovaikutteinen selaimen MSAL (Microsoft-todennuskirjasto) -todennus
http://localhost Microsoft Graph PowerShell SDK Connect-MgGraph
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} Verkkotilien hallinnan (WAM) käyttö

Lisätietoja on kohdassa Komentorivikäyttöliittymän automaattiset määritykset.

2. Uudelleenohjauksen URI-osoitteen määrittäminen

  1. Valitse Yleiskatsaus ja kopioi Sovelluksen (asiakasohjelman) tunnus -arvo.
  2. Valitse ensin Todennus (esiversio) ja sitten Lisää uudelleenohjauksen URI.
  3. Valitse Mobiili- ja työpöytäsovellukset ja määritä arvoksi ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, jossa {client-id} on kopioitu Sovelluksen (asiakasohjelman) tunnus.
  4. Lisää arvo valitsemalla Määritä.

3. Sovelluksen (asiakasohjelman) tunnuksen kopiointi

Kopioi sovelluksen Yleiskatsaus-sivulta Sovelluksen (asiakasohjelma) tunnus GUID-muodossa. Tätä arvoa käytetään, kun a365 setup all suoritetaan tai a365.config.json luodaan manuaalisesti.

Vinkki

Älä sekoita tätä arvoa objektitunnukseen; tarvitset siis sovelluksen (asiakasohjelman) tunnuksen.

Jos annoit vaiheessa 1 sovelluksen nimeksi Agent 365 CLI, voit ohittaa tämän vaiheen, kun käytössä on a365 setup all --agent-name. CLI ratkaisee asiakastunnuksen automaattisesti näyttönimen perusteella.

4. Ohjelmointirajapinnan oikeuksien määrittäminen

Tärkeää

Tässä vaiheessa tarvitaan järjestelmänvalvojan käyttöoikeudet. Kehittäjä, jolla ei ole järjestelmänvalvojan käyttöoikeuksia, voi lähettää vaiheessa 3 luodun sovelluksen (asiakasohjelman) tunnuksen vuokraajan järjestelmänvalvojalle ja tätä suorittamaan tämän vaiheen.

Muistiinpano

Joulukuusta 2025 alkaen AgentIdentityBlueprint.*-, AgentInstance.*- ja AgentIdentity.*-käyttöoikeudet beetaversioiden ohjelmointirajapintoja, jotka eivät ehkä näy Microsoft Entra -hallintakeskuksessa. Jos nämä käyttöoikeudet tulevat yleisesti saataville vuokraajaan, voit käyttää vaihtoehtoa A kaikkien käyttöoikeuksien osalta.

Valitse sopiva menetelmä:

  • Vaihtoehto A: Microsoft Entra -hallintakeskuksen käyttäminen kaikkien käyttöoikeuksien osalta (jos beetaversioiden käyttöoikeudet ovat näkyvissä)
  • Vaihtoehto B: kaikkien käyttöoikeuksien lisääminen Microsoft Graph API:n avulla (suositus, jos beetaversioiden käyttöoikeudet eivät ole näkyvissä)

Vaihtoehto A: Microsoft Entra -hallintakeskus (vakiomenetelmä)

Käytä tätä menetelmää, jos beetaversioiden käyttöoikeudet näkyvät vuokraajassa.

  1. Valitse sovelluksen rekisteröinnissä Ohjelmointirajapinnan oikeudet.

  2. Valitse Lisää oikeus>Microsoft Graph>Delegoidut käyttöoikeudet.

    Tärkeää

    Käytössä on oltava Delegoidut käyttöoikeudet (eikä Sovelluksen käyttöoikeudet). Komentorivikäyttöliittymä todentuu vuorovaikutteisesti eli kirjaudut sisään ja se toimii puolestasi. Lisätietoja on kohdassa Väärä käyttöoikeustyyppi.

  3. Lisää seuraavat seitsemän käyttöoikeutta yksitellen:

    Käyttöoikeus Tarkoitus
    AgentIdentityBlueprint.ReadWrite.All Etenemissuunnitelman luonti, asiakasohjelman salasanan hallinta, periytyvät käyttöoikeudet, organisaation ulkopuolisten käyttäjätietojen tunnistetietiedot ja poisto (beetaversion ohjelmointirajapinta)
    AgentIdentityBlueprintPrincipal.Create Agentin etenemissuunnitelman palveluobjektin luonti (beetaversion ohjelmointirajapinta)
    AgentIdentity.Read.All Ainutkertaisuuden tarkistus ja agentin käyttäjätietojen palveluobjektin haku (beetaverson ohjelmointirajapinta)
    AgentIdentity.DeleteRestore.All Agentin käyttäjätietojen palveluobjektien poisto puhdistuksen aikana (ohjelmointirajapinnan beetaversio)
    AgentRegistration.ReadWrite.All Kaikkien agenttirekisteröintien luku ja kirjoitus
    Application.Read.All Palveluobjektin haku sovellustunnuksen perusteella (tarkennettu Directory.Read.Allille-oikeuden korvaaja)
    User.Read Kirjautuneen käyttäjäprofiilin luku etenemissuunnitelman omistajan ja sponsorin määritystä varten

    Muistiinpano

    AgentRegistration.ReadWrite.All on pakollinen agenttia määritettäessä. Komentorivikäyttöliittymän varmentaja tarkistaa nimenomaisesti tämän käyttöoikeuden. Sen on oltava sovellusrekisteröinnissä ja sillä on oltava järjestelmänvalvojan myöntämä suostumus.

    Kussakin käyttöoikeudessa:

    • Kirjoita hakukenttään käyttöoikeuden nimi (esimerkiksi AgentIdentityBlueprint.ReadWrite.All).
    • Valitse käyttöoikeuden vieressä oleva valintaruutu.
    • Valitse Lisää käyttöoikeudet.
    • Toista nämä vaiheet jokaisessa seitsemässä käyttöoikeudessa.

  4. Valitse Myönnä järjestelmänvalvojan suostumus vuokraajalle [vuokraaja].

    • Miksi tämä tarvitaan? Agentin käyttäjätietojen etenemissuunnitelmat ovat koko vuokraajassa käytettäviä resursseja, joita useat käyttäjät ja sovellukset voivat hyödyntää. Ilman vuokraajatason suostumusta, komentorivikäyttöliittymä ei onnistu todennuksessa.
    • Miten epäonnistuttaessa toimitaan? Tarvitset sovelluksen järjestelmänvalvojan- , pilvisovelluksen järjestelmän valvojan tai yleisen järjestelmänvalvojan roolin. Pyydä apua vuokraajan järjestelmänvalvojalta.

  5. Varmista, että kaikkien käyttöoikeuksien vieressä on vihreä valintamerkki Tila-kohdassa.

Jos beetaversioiden käyttöoikeudet (AgentIdentityBlueprint.*) eivät näy, siirry vaihtoehtoon B.

Vaihtoehto B: Microsoft Graph API (beetaversioiden käyttöoikeuksia varten)

Käytä tätä menetelmää, jos Microsoft Entra -hallintakeskus ei näytä AgentIdentityBlueprint.*-käyttöoikeuksia.

Varoitus

Jos käytät tätä ohjelmointirajapintamenetelmää, älä käytä Microsoft Entra -hallintakeskuksen Myönnä järjestelmänvalvojan suostumus -painiketta sen jälkeen. Ohjelmointirajapintamenetelmä myöntää järjestelmänvalvojan suostumuksen automaattisesti, ja Microsoft Entra -hallintakeskuksen painikkeen käyttö poistaa beetaversioiden käyttöoikeudet. Lisätietoja on kohdassa Beetaversioiden käyttöoikeuksien häviäminen.

  1. Avaa Graph-työkalun testaus.

  2. Käytä kirjautumiseen järjestelmänvalvojan tiliä (sovelluksen järjestelmänvalvoja tai pilvisovelluksen järjestelmänvalvoja).

  3. Myönnä järjestelmänvalvojan suostumus Graph API:n avulla. Tämän vaiheen suorittamiseen tarvitaan seuraavat:

    • Palvelun päänimen tunnus. SP_OBJECT_ID-muuttujan arvo.
    • Graph-resurssin tunnus. GRAPH_RESOURCE_ID-muuttujan arvo.
    • Luo (tai päivitä) delegoidut käyttöoikeudet käyttämällä oAuth2PermissionGrant-resurssityyppiä sekä SP_OBJECT_ID- ja GRAPH_RESOURCE_ID-muuttujien arvoja.

Suorita nämä vaiheet seuraavien osioiden ohjeiden mukaisesti.

Palvelun päänimen tunnuksen hankkiminen

Palvelun päänimi on sovelluksen käyttäjätieto vuokraajassa. Tarvitset sen ennen käyttöoikeuksien myöntämistä ohjelmointirajapinnan kautta.

  1. Määritä Graph-työkalun testauksen menetelmäksi GET ja käytä tätä URL-osoitetta. Korvaa <YOUR_CLIENT_APP_ID> sovelluksen varsinaisella asiakastunnuksella, joka luotiin vaiheessa Vaihe 3: Sovelluksen (asiakasohjelman) tunnuksen kopiointi:

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

  2. Valitse Suorita kysely.

    • Jos kysely onnistuu, palautettu arvo on oma SP_OBJECT_ID.

    • Jos kysely epäonnistuu käyttöoikeusvirheen vuoksi, valitse Muokkaa käyttöoikeuksia -välilehti, hyväksy vaaditut käyttöoikeudet ja valitse sitten uudelleen Suorita kysely. Palautettu arvo on oma SP_OBJECT_ID.

    • Jos kysely palauttaa tyhjiä tuloksia ("value": []), luo palvelun päänimi seuraavasti:

      1. Määritä menetelmäksi POST ja käytä tätä URL-osoitetta:

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

        Pyynnön teksti (korvaa YOUR_CLIENT_APP_ID varsinaisella sovelluksen asiakasohjelman tunnuksella):

        {
   "appId": "YOUR_CLIENT_APP_ID"
}

      2. Valitse Suorita kysely. Vastauksen pitäisi olla 201 Created. Palautettu id-arvo on oma SP_OBJECT_ID.

Graph-resurssin tunnuksen hankkiminen

  1. Määritä Graph-työkalun testausmenetelmäksi GET ja käytä tätä URL-osoitetta:

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

  2. Valitse Suorita kysely.

    • Jos kysely onnistuu, kopioi id-arvo. Tämä arvo on oma GRAPH_RESOURCE_ID.
    • Jos kysely epäonnistuu käyttöoikeusvirheen vuoksi, valitse Muokkaa käyttöoikeuksia -välilehti, hyväksy vaaditut käyttöoikeudet ja valitse sitten uudelleen Suorita kysely. Kopioi id-arvo. Tämä arvo on oma GRAPH_RESOURCE_ID.

Delegoitujen käyttöoikeuksien luominen

Tämä ohjelmointirajapintakutsu myöntää koko vuokraajaa koskevan järjestelmänvalvojan suostumuksen kaikille seitsemälle käyttöoikeudelle, mukaan lukien beetaversioiden käyttöoikeudet, jotka eivät näy Microsoft Entra -hallintakeskuksessa.

  1. Määritä Graph-työkalun testausmenetelmäksi POST sekä käytä tätä URL-osoitetta ja pyynnön tekstiä:

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

    Pyynnön teksti:

    {
"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. Valitse Suorita kysely.

    • Jos vastauksena on 201 Created: Kysely onnistui. Vastauksen scope-kenttä näyttää kaikkien seitsemän käyttöoikeuden nimet. Kaikki on valmista.
    • Jos kysely epäonnistuu käyttöoikeusvirheen vuoksi, valitse Muokkaa käyttöoikeuksia -välilehti, hyväksy vaaditut käyttöoikeudet ja valitse sitten uudelleen Suorita kysely.
    • Jos tuloksena on virhe Request_MultipleObjectsWithSameKeyValue: Suostumus on jo annettu. Joku on ehkä lisännyt käyttöoikeudet aiemmin. Lisätietoja on kohdassa Delegoitujen käyttöoikeuksien päivittäminen.

Varoitus

POST-pyynnön consentType: "AllPrincipals"myöntää jo koko vuokraajaa koskevan järjestelmänvalvojan suostumuksen. ÄLÄ valitse Myönnä järjestelmänvalvojan suostumus -kohtaa Microsoft Entra -hallintakeskuksessa tämän ohjelmointirajapintamenetelmän käytön jälkeen, sillä se poistaa beetaversion käyttöoikeudet, koska Microsoft Entra -hallintakeskus ei näe beetaversioiden käyttöoikeuksia ja korvaa ohjelmointirajapinnan myöntämän suostumuksen vain näkyvillä käyttöoikeuksilla.

Delegoitujen käyttöoikeuksien päivittäminen

Kun Request_MultipleObjectsWithSameKeyValue-virhe saadaan delegoitujen käyttöoikeuksien luonnin ohjeiden mukaan toimittaessa, päivitä delegoidut käyttöoikeudet seuraavien ohjeiden mukaisesti.

  1. Määritä Graph-työkalun testausmenetelmäksi GET ja käytä tätä URL-osoitetta:

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

  2. Valitse Suorita kysely. Kopioi vastauksen id-arvo. Tämä arvo on YOUR_GRANT_ID.

  3. Määritä Graph-työkalun testausmenetelmäksi PATCH ja käytä tätä URL-osoitetta YOUR_GRANT_ID-tunnuksen kanssa.

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

    Pyynnön teksti:

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

  4. Valitse Suorita kysely. 200 OK-vastaus pitäisi saada scope-kentän jokaiseen seitsemään käyttöoikeuteen.

5. wids-rooliväitteen lisääminen

Agent 365 CLI lukee Entra-hakemiston roolimääritykset suoraan käyttöoikeustietueesta ja selvittää tällä tavoin, onko käyttäjä järjestelmänvalvojan käyttöoikeudet. Tämä edellyttää wids-väitteen lisäämistä sovelluksen rekisteröintiin myönnettyihin käyttöoikeustietueisiin.

Ilman tätä väitettä komentorivikäyttöliittymä ei tunnista sääntöä ja palautuu näyttämään PowerShell-ohjeet kussakin järjestelmänvalvojan käyttöoikeuksia edellyttävässä vaiheessa, vaikka olisit järjestelmänvalvoja. Varmista oikea toiminta suorittamalla tämä vaihe.

  1. Valitse sovelluksen rekisteröinnissä Tunnuksen määritys.

  2. Valitse Lisää valinnainen väite.

  3. Valitse tunnuksen tyypiksiKäyttöoikeus.

  4. Valitse väiteluettelossa wids-kohdan valintaruutu.

  5. Valitse Lisää.

    Valitse Kyllä, lisää, jos Microsoft Graphin profile-käyttöoikeus pyydetään ottamaan käyttöön väitteen käyttöönottoa varten.

Muistiinpano

wids-väite sisältää Entra-hakemiston roolimallien GUID-tunnisteet, jotka on määritetty suoraan kirjautuneelle käyttäjälle. Komentorivikäyttöliittymä tunnistaa näiden GUID-tunnisteiden avulla yleisen järjestelmänvalvojan ja agenttitunnuksen järjestelmänvalvojan ilman Graph API -lisäkutsua.

Rajoitus:wids koskee vain suoraan määritettyjä rooleja. Jos vuokraaja määrittää hakemistorooleja sellaisten käyttöoikeusryhmien kautta, joissa rooleja voidaan määrittää, komentorivikäyttöliittymä ei ehkä tunnista kyseisiä ryhmäpohjaisia roolimäärityksiä. Roolin suora määritys on sekä agentin tunnuksen kehittäjän että järjestelmänvalvojan roolien vakiotoimintamalli.

Suojauksen parhaat käytännöt

Tutustu näihin ohjeisiin ja varmista, että sovelluksen rekisteröinti pysyy suojattuna ja vaatimustenmukaisena.

Voit

  • käyttää yhden vuokraajan rekisteröintiä
  • myöntää vain tarvittavat delegoidut käyttöoikeudet
  • seurata käyttöoikeuksia säännöllisesti.
  • poistaa sovelluksen, kun sitä ei enää tarvita.

Älä

  • myönnä sovelluksen käyttöoikeuksia vaan vain delegoituja käyttöoikeuksia
  • jaa asiakastunnusta julkisesti
  • myönnä muita tarpeettomia oikeuksia
  • käytä sovellusta muihin tarkoituksiin.

Komentorivikäyttöliittymän automaattiset määritykset

Kun a365 setup requirements suoritetaan, komentorivikäyttöliittymä tarkistaa sovelluksen rekisteröinnin ja saattaa edellyttää muutoksia. Komentorivikäyttöliittymä näyttää ennen muutosten käyttämistä yhteenvedon ja pyytää vahvistusta:

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):

Vahvistuskehotteen voi ohittaa (esimerkiksi CI-ympäristössä) käyttämällä --yes-lippua:

a365 setup requirements --yes

Seuraavassa taulukossa käsitellään jokainen muutos, jonka komentorivikäyttöliittymä saattaa tehdä:

Muutos Syy
Uudelleenohjauksen URI-osoitteen http://localhost lisääminen Microsoft Graph PowerShell SDK edellyttää tämän URI-osoitteen käyttöä selaintodennuksessa. Ilman sitä OAuth2-myöntötoiminnot palautuvat tietueeseen, jossa ei ole tarvittavia delegoituja käyttöoikeuksia, mikä johtaa virheilmoitukseen 403.
Uudelleenohjauksen URI-osoitteen http://localhost:8400/ lisääminen MSAL edellyttää tämä URI-osoitteen käyttöä vuorovaikutteisessa selaintodennuksessa.
Uudelleenohjauksen URI-osoitteen ms-appx-web://Microsoft.AAD.BrokerPlugin/{id} lisääminen Pakollinen verkkotilien hallinnassa (WAM), joka on Windows-käyttöjärjestelmän todennuksen välittäjä. Lisätietoja on kohdassa Laitteisiin sidottujen tunnusten hankkiminen.
Salli julkisen asiakkaan työnkulut -ominaisuuden ottaminen käyttöön Tarvitaan laitekoodin todennuksen vararatkaisuna macOS-, Linux- ja WSL (Windows-käyttöjärjestelmän Linux-alijärjestelmä) -ympäristöissä, palvelittomissa ympäristöissä sekä ehdollisen käyttöoikeuskäytännön vararatkaisuna Windowsissa.
Puuttuvien käyttöoikeuksien lisääminen sovelluksen rekisteröintiin Pitää sovelluksen rekisteröinnin ja uudet tarvittavat käyttöoikeudet synkronoituina komentorivikäyttöliittymän päivityksen jälkeen.
Järjestelmänvalvojan myöntämän suostumuksen laajentaminen Laajentaa aiemmin myönnetyn OAuth2-käyttöoikeuden sisältämään uudet käyttöoikeudet.

Jos hylkäät kehotteen, komentorivikäyttöliittymä ei muokkaa sovelluksen rekisteröintiä. Jos komentorivikäyttöliittymän toiminta edellyttää muutoksia, ne voidaan määrittää manuaalisesti Microsoft Entra -hallintakeskuksessa tai suorittaa uudelleen komennolla --yes.

Seuraavat vaiheet

Kun mukautettu asiakassovellus on rekisteröity, voit viimeistellä Agent 365 -määritykset käyttämällä sitä yhdessä Agent 365 CLI -sovelluksen kanssa.

Agent 365:n kehittämisen aloittaminen

Vianmääritys

Tässä osiossa käsitellään mukautetun asiakassovelluksen rekisteröintiin liittyvien virheiden vianmääritystä.

Vinkki

Agent 365:n vianmääritysopas sisältää yleisluontoisia vianmääritykseen liittyviä suosituksia, parhaita käytäntöjä sekä linkkejä vianmääritykseen liittyvään sisältöön Agent 365:n kehityksen elinkaaren kaikissa vaiheissa.

Komentorivikäyttöliittymän tarkistus epäonnistuu määrityksen aikana

Oire:a365 setup- tai a365 setup requirements-komennon suorittaminen epäonnistuu ja virheilmoituksissa mainitaan mukautettu asiakassovellus.

Ratkaisu: varmista sovelluksen rekisteröinnin oikeellisuus seuraavan tarkistusluettelon avulla:

# Run requirements validation to see validation messages
a365 setup requirements

Odotettu tulos: komentorivikäyttöliittymässä on teksti Custom client app validation successful.

Jos tulos ei ole odotetunlainen, varmista kukin seuraavista tarkistuksista:

Sekki Varmistuskeino Korjaus
✅ Oikean tunnuksen käyttö Kopioitiin sovelluksen (asiakasohjelman) tunnus (eikä objektitunnusta) Valitse YleiskatsausMicrosoft Entra -hallintakeskuksessa
✅ Delegoidut käyttöoikeudet Ohjelmointirajapinnan käyttöoikeuksissa käyttöoikeuksin näkyy Tyyppi: Delegoitu Lisätietoja on kohdassa Väärä käyttöoikeustyyppi
✅ Kaikki käyttöoikeudet lisätty Katso kaikki alla olla oleva kaikki käyttöoikeudet sisältävä luettelo Toimi uudelleen vaiheen 4 ohjeiden mukaisesti
✅ Järjestelmänvalvojan suostumus myönnetty Kaikkien Tila-valintaruudussa on vihreä valintamerkki Lisätietoja on kohdassa Järjestelmänvalvojan virheellisesti myöntämä suostumus

Vaaditut delegoidut käyttöoikeudet:

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

Oire: tarkistus epäonnistuu, vaikka käyttöoikeudet lisättiin.

Juurisyy: järjestelmänvalvojan suostumusta ei myönnetty tai se myönnettiin virheellisesti.

Ratkaisu: valitse Microsoft Entra -hallintakeskuksessa sovelluksen rekisteröinnissä ensin Ohjelmointirajapinnan oikeudet ja sitten Myönnä järjestelmänvalvojan suostumus vuokraajalle [vuokraaja]. Varmista, että kaikkien käyttöoikeuksien vieressä on vihreä valintamerkki Tila-kohdassa.

Oire: a365 setup all tulostaa Delegoidun sovelluksen suostumuksen varmistus onnistuu, mutta heti sen jälkeen virhe etenemissuunnitelmaa luotaessa:

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>

Juurisyy: Vuokraajassa on jo mukautetun asiakassovelluksen oauth2PermissionGrant-tietue (aiemmasta osittaisesta määrityksestä tai muiden vaikutusalueiden Microsoft Entra -hallintakeskuksen Myönnä järjestelmänvalvojan suostumus -toiminnosta), mutta kyseisestä tietueesta puuttuu tarvittava vaikutusalue (AgentIdentityBlueprint.ReadWrite.All). Komentorivikäyttöliittymä tunnistaa puuttuvan vaikutusalueen ja näyttää suostumuksen URL-osoitteen, jonka avulla järjestelmänvalvoja voi viimeistellä suostumuksen.

Ratkaisu:

Jaa virheilmoituksessa näkyvä suostumuksen URL-osoite sovelluksen järjestelmänvalvojalle tai yleiselle järjestelmänvalvojalle. URL-osoite on seuraavanlainen:

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

Kun järjestelmänvalvoja on myöntänyt suostumuksen, suorita a365 setup all --agent-name <name> uudelleen.

Jos sinulla on järjestelmänvalvojan oikeudet, voit avata URL-osoitteen suoraan selaimessa ja myöntää suostumuksen ilman odottamista.

Väärä käyttöoikeustyyppi

Oire: komentorivikäyttöliittymässä todennusta tai käytön estoa koskevia virheitä.

Juurisyy: lisättiin sovelluksen käyttöoikeudet eikä delegoituja käyttöoikeuksia.

Taulukko sisältää erilaiset käyttöoikeustyypit.

Käyttöoikeuden tyyppi Milloin kannattaa käyttää Käyttö Agent 365 CLI -sovelluksessa
Delegoitu (Vaikutusalue) Käyttäjä kirjautuu sisään vuorovaikutteisesti Agent 365 CLI -käyttö – komentorivikäyttöliittymä toimii kirjautuneen käyttäjän puolesta
Sovellus (Rooli) Palvelu toimii ilman käyttäjää Älä käytä – vain taustapalvelut/daemonit

Miksi delegoitu?

  • Vuorovaikutteinen kirjautuminen (selaintodennus)
  • Komentorivikäyttöliittymä suorittaa toimintoja käyttäjänä (kirjausketjut näyttävät käyttäjätiedot)
  • Turvallisuus – rajoituksena omat käyttöoikeudet
  • Varmistaa vastuullisuuden ja vaatimustenmukaisuuden

Ratkaisu:

  1. Valitse Microsoft Entra -hallintakeskus>Sovellusten rekisteröinnit> Oma sovellus >Ohjelmointirajapinnan oikeudet
  2. Poista sovelluksen mahdolliset käyttöoikeudet. Nämä käyttöoikeudet sovelluksenaTyyppi-sarakkeessa.
  3. Lisää samat käyttöoikeudet delegoituina käyttöoikeuksina.
  4. Myönnä järjestelmänvalvojan suostumus uudelleen.

Oire: beetaversioiden käyttöoikeudet lisättiin käyttämällä vaihtoehtoa B: Microsoft Graph API (beetaversioiden käyttöoikeuksia varten), mutta ne häviävät, kun Myönnä järjestelmänvalvojan suostumus valitaan Microsoft Entra -hallintakeskuksessa.

Juurisyy: Microsoft Entra -hallintakeskus ei näytä beataversioiden käyttöoikeuksia käyttöliittymässä. Kun Myönnä järjestelmänvalvojan suostumus valitaan, portaali myöntää suostumuksen vain näkyville käyttöoikeuksille ja korvaa ohjelmointirajapinnan myöntämän suostumuksen.

Miksi näin tapahtuu:

  1. Kaikki seitsemän käyttöoikeutta, mukaan lukien beetaversioiden käyttöoikeudet, lisätään käyttämällä Graph API:a (vaihtoehto B).
  2. Ohjelmointirajapintakutsu, jossa on consentType: "AllPrincipals"myöntää jo koko vuokraajaan koskevan järjestelmänvalvojan suostumuksen.
  3. Kun Microsoft Entra -hallintakeskukseen siirrytään, näkyvissä on vain osan käyttöoikeuksista, sillä beetaversioiden käyttöoikeudet eivät näy portaalissa.
  4. Myönnä järjestelmänvalvojan suostumus valitaan, koska sitä luullaan tarvittavan.
  5. Microsoft Entra -hallintakeskus korvaa ohjelmointirajapinnan myöntämän suostumuksen vain näkyvissä olevilla käyttöoikeuksilla.
  6. Beetaversioiden käyttöoikeudet poistetaan.

Ratkaisu:

  • Älä käytä Microsoft Entra -hallintakeskuksen järjestelmänvalvojan suostumusta ohjelmointirajapintamenetelmän jälkeen: ohjelmointirajapintamenetelmä myöntää jo järjestelmänvalvojan suostumuksen.
  • Jos beetaversion käyttöoikeudet poistetaan vahingossa, palauta ne suorittamalla vaihtoehdon B vaihe 3 (Järjestelmänvalvojan suostumuksen myöntäminen Graphin API:n avulla) uudelleen. Jos kyseessä on virhe Request_MultipleObjectsWithSameKeyValue, noudat ohjeita kohdassa Delegoitujen käyttöoikeuksien päivittäminen.
  • Varmista, että kaikki seitsemän käyttöoikeutta ovat luettelossa, tarkistamalla scope-kenttä POST- tai PATCH-vastauksesta.

Sovellusta ei löytynyt tarkistuksen aikana

Oire: komentorivikäyttöliittymä ilmoittaa Application not found- tai Invalid client ID-virheen.

Ratkaisu:

  1. Varmista, että sovelluksen (asiakasohjelman) tunnus eikä objektin tunnus on kopioitu GUID-muodossa.

    • Valitse Microsoft Entra -hallintakeskus>Sovellusten rekisteröinnit> Oma sovellus >Yleiskatsaus
    • Kopioi arvo Sovelluksen (asiakasohjelman) tunnus -kohdassa
    • Oikea muoto: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

  2. Varmista, että sovellus on vuokraajassa:

    # Sign in to the correct tenant
az login

# List your app registrations
az ad app list --display-name "<The display name of your app>"

Tietoja sovelluksen rekisteröimisestä Microsoft Entra ID:ssä.

  • Last updated on