Rejestracja niestandardowej aplikacji klienckiej dla Agent 365 CLI

Agent 365 CLI wymaga niestandardowej rejestracji aplikacji klienckiej w Twoim dzierżawcy Microsoft Entra ID, aby uwierzytelniać i zarządzać szablonami tożsamości agenta.

Ten artykuł przedstawia proces w czterech głównych etapach:

  1. Zarejestruj aplikację
  2. Ustaw URI przekierowywania
  3. Kopiuj identyfikator aplikacji (klient)
  4. Skonfiguruj uprawnienia APIWymagane uprawnienia administratora
  5. Dodaj claim roli wids

Jeśli napotkasz problemy, przeczytaj sekcję Rozwiązywanie problemów.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz dostęp do centrum administracyjnego Microsoft Entra oraz, jeśli zajdzie taka potrzeba, do jednej z wymaganych ról administratora umożliwiających udzielenie zgody.

Aby zarejestrować aplikację

Domyślnie każdy użytkownik w dzierżawie może rejestrować aplikacje w centrum administracyjnym Microsoft Entra. Jednak administratorzy dzierżawy mogą ograniczyć tę możliwość. Jeśli nie możesz zarejestrować swojej aplikacji, skontaktuj się z administratorem.

Potrzebujesz jednej z tych ról administratora do 4. Konfiguracja uprawnień API.

Wskazówka

Nie masz dostępu administratora? Możesz samodzielnie wykonać kroki 1-3, a następnie poprosić administratora najemcy o wykonanie kroku 4. Podaj im swój identyfikator aplikacji (klienta) z kroku 3 oraz link do sekcji Configure API Permissions.

Wskazówka

Administratorzy globalni mogą pominąć ręczną rejestrację. Uruchom a365 setup requirements i jeśli aplikacja Agent 365 CLI nie jest dostępna w Twojej dzierżawie, CLI automatycznie wyświetli monit o utworzenie aplikacji i udzielenie zgody administratora. Wpisz C przy wyświetlonym monicie, aby utworzyć aplikację w jednym kroku. Jeśli użyjesz tej zautomatyzowanej ścieżki, możesz pominąć kroki w tej sekcji.

1. Zarejestruj aplikację

Instrukcje te podsumowują pełne instrukcje dotyczące rejestracji aplikacji.

  1. Przejdź do Centrum administracyjne Microsoft Entra

  2. Wybierz pozycję Rejestracje aplikacji

  3. Wybierz Nowa rejestracja

  4. Wprowadź:

    • Nazwa: Wprowadź czytelną nazwę dla swojej aplikacji, na przykład my-agent-app. Użytkownicy aplikacji widzą tę nazwę, a jej zmiana jest możliwa w dowolnym momencie. Możesz mieć wiele rejestracji aplikacji o tej samej nazwie.

      Wskazówka

      Jeśli chcesz użyć przepływu bez konfiguracji „a365 setup all --agent-name”, nazwij aplikację dokładnie „Agent 365 CLI”. CLI automatycznie wyszukuje aplikację kliencką po tej znanej „nazwie wyświetlanej”, więc nie musisz kopiować identyfikatora klienta do pliku konfiguracyjnego.

    • Obsługiwane typy kont: Konta tylko w tym katalogu organizacji(jedna dzierżawa)

    • URI przekierowania: Wybierz klient publiczny/natywny (mobilny stacjonarny) i wprowadź http://localhost:8400/

  5. Wybierz pozycję Zarejestruj

CLI wymaga łącznie trzech URI przekierowania. CLI automatycznie doda wszystkie brakujące URI przekierowania, gdy uruchomisz a365 setup requirements:

URI Przeznaczenie
http://localhost:8400/ Microsoft Authentication Library (MSAL) interaktywne uwierzytelnianie w przeglądarce
http://localhost Microsoft Graph PowerShell SDK Connect-MgGraph
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} Korzystanie z Web Account Manager (WAM)

Zobacz Co automatycznie konfiguruje CLI, aby uzyskać szczegóły.

2. Ustaw URI przekierowywania

  1. Skopiuj wartość Identyfikator aplikacji (klienta) w obszarze Przegląd.
  2. Przejdź do sekcji Uwierzytelnianie (wersja zapoznawcza), a następnie kliknij pozycję Dodaj adres URI przekierowania.
  3. Wybierz aplikacje mobilne i desktopowe i ustaw wartość na ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, gdzie {client-id} jest wartością aplikacji (identyfikator klienta), którą skopiowałeś.
  4. Wybierz „Konfiguruj”, aby dodać wartość.

3. Kopiuj identyfikator aplikacji (klient)

Na stronie „Przegląd” aplikacji skopiuj „identyfikator aplikacji (klienta)” w formacie GUID. Używasz tej wartości podczas uruchamiania a365 setup all lub ręcznego tworzenia a365.config.json.

Wskazówka

Nie myl tej wartości z ID obiektu — potrzebujesz ID aplikacji (klienta).

Jeśli nazwałeś swoją aplikację Agent 365 CLI w kroku 1, możesz pominąć ten krok podczas korzystania z a365 setup all --agent-name. CLI automatycznie rozpoznaje ID klienta na podstawie nazwy wyświetlanej.

4. Konfiguracja uprawnień API

Ważne

Do tego kroku potrzebujesz uprawnień administratora. Jeśli jesteś deweloperem bez dostępu administracyjnego, wyślij swój identyfikator aplikacji (klienta) z kroku 3 do administratora dzierżawy i poproś go o ukończenie tego kroku.

Notatka

Od grudnia 2025 roku uprawnienia AgentIdentityBlueprint.*, AgentInstance.* i AgentIdentity.* są interfejsami API w wersji beta i mogą nie być widoczne w centrum administracyjnym Microsoft Entra. Jeśli te uprawnienia staną się powszechnie dostępne w Twoim tenantcie, możesz użyć Opcji A dla wszystkich uprawnień.

Wybierz odpowiednią metodę:

  • Opcja A: Użyj centrum administracyjnego Microsoft Entra dla wszystkich uprawnień (jeśli uprawnienia beta są widoczne)
  • Opcja B: Użyj Microsoft interfejs Graph API, aby dodać wszystkie uprawnienia (zalecane, jeśli uprawnienia beta nie są widoczne)

Opcja A: Centrum administracyjne Microsoft Entra (Standardowa Metoda)

Użyj tej metody, jeśli uprawnienia beta są widoczne w Twoim tenant.

  1. W nowej rejestracji aplikacji przejdź do uprawnienia interfejsu API.

  2. Wybierz Dodaj uprawnienie>Microsoft Graph>Uprawnienie delegowane.

    Ważne

    Musisz używać uprawnień delegowanych (nie uprawnień aplikacji). CLI uwierzytelnia się w trybie interaktywnym – logujesz się, a narzędzie działa w Twoim imieniu. Aby uzyskać więcej informacji, zobacz Nieprawidłowy typ uprawnień.

  3. Dodaj każde z tych siedmiu uprawnień osobno:

    Uprawnienie Przeznaczenie
    AgentIdentityBlueprint.ReadWrite.All Tworzenie blueprintów, zarządzanie sekretami klienta, dziedziczne uprawnienia, federowane poświadczenia tożsamości oraz usuwanie (beta API)
    AgentIdentityBlueprintPrincipal.Create Utwórz podmiot usługi Agent Blueprint (beta API)
    AgentIdentity.Read.All Idempotency check i agent identity service principal lookup (beta API)
    AgentIdentity.DeleteRestore.All Usuń podmioty usługi tożsamości agenta podczas czyszczenia (beta API)
    AgentRegistration.ReadWrite.All Odczyt i zapis wszystkich rejestracji agentów
    Application.Read.All Wyszukiwanie podmiotu usługi według ID aplikacji (bardziej ograniczona wersja Directory.Read.All)
    User.Read Odczyt profilu zalogowanego użytkownika dla przydziału właściciela i sponsora blueprintu

    Notatka

    AgentRegistration.ReadWrite.All jest wymagany do konfiguracji agenta. Walidator CLI wprost sprawdza to uprawnienie. Musi być dodany do rejestracji aplikacji i mieć przyznaną zgodę administratora.

    Dla każdego uprawnienia:

    • W polu wyszukiwania wpisz nazwę uprawnienia (na przykład AgentIdentityBlueprint.ReadWrite.All).
    • Zaznacz pole wyboru obok uprawnienia.
    • Wybierz Przyznaj uprawnienia.
    • Powtórz dla wszystkich siedmiu uprawnień.

  4. Wybierz pozycję Wyraź zgodę administratora dla [dzierżawcy].

    • Dlaczego jest to wymagane? Szablony tożsamości agenta to zasoby dostępne w całej dzierżawie, z których mogą korzystać różni użytkownicy i aplikacje. Bez zgody na poziomie dzierżawy CLI nie powiedzie się podczas uwierzytelniania.
    • Co zrobić, jeśli się nie powiedzie? Potrzebujesz roli Application Administrator, Cloud Application Administrator lub Global Administrator. Poproś administratora dzierżawcy o pomoc.

  5. Sprawdź, czy wszystkie uprawnienia są oznaczone zielonymi znacznikami pod status.

Jeśli uprawnienia beta (AgentIdentityBlueprint.*) nie są widoczne, przejdź do Opcji B.

Opcja B: Microsoft interfejs Graph API (dla uprawnień beta)

Użyj tej metody, jeśli centrum administracyjne Microsoft Entra nie wyświetla AgentIdentityBlueprint.* uprawnień.

Ostrzeżenie

Jeśli używasz tej metody API, nie używaj potem przycisku "Grant admin consent" w Centrum administracyjne Microsoft Entra. Metoda API automatycznie udziela zgody administratora, a użycie przycisku centrum administracyjne Microsoft Entra usuwa Twoje uprawnienia beta. Aby uzyskać więcej informacji, zobacz uprawnienia Beta znikają.

  1. Otwórz Eksploratora programu Graph.

  2. Zaloguj się przy użyciu konta administratora (Administrator aplikacji lub Administrator aplikacji w chmurze).

  3. Udziel zgody administratora, korzystając z interfejs Graph API. Aby ukończyć ten przewodnik, potrzebne są:

    • Identyfikator głównej usługi. Potrzebna jest wartość zmiennej SP_OBJECT_ID.
    • Identyfikator zasobu grafu. Potrzebna jest wartość zmiennej GRAPH_RESOURCE_ID.
    • Utwórz (lub zaktualizuj) delegowane uprawnienia, korzystając z zasobu typu oAuth2PermissionGrant z wartościami zmiennych SP_OBJECT_ID i GRAPH_RESOURCE_ID.

Skorzystaj z informacji w poniższych sekcjach, aby wykonać te kroki.

Uzyskaj identyfikator podmiotu usługowego

Podmiot usługowy to tożsamość Twojej aplikacji w najemcy. Potrzebujesz go, zanim będziesz mógł przyznać uprawnienia przez API.

  1. Ustaw metodę w Graph Explorerze na GET i użyj tego adresu URL. Zastąp <YOUR_CLIENT_APP_ID> rzeczywistym identyfikatorem aplikacji (klienta) z Kroku 3: Skopiuj identyfikator aplikacji (klienta):

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

  2. Wybierz Uruchom zapytanie.

    • Jeśli zapytanie się powiedzie, zwracana wartość to Twoja SP_OBJECT_ID.

    • Jeśli zapytanie zakończy się błędem uprawnień, wybierz kartę Modyfikuj uprawnienia, zaakceptuj wymagane uprawnienia, a następnie ponownie wybierz Uruchom zapytanie. Wartość zwracana to twoja SP_OBJECT_ID.

    • Jeśli zapytanie zwraca puste wyniki (),"value": [] utwórz zasadę usługi, wykonując następujące kroki:

      1. Ustaw metodę na POST i użyj tego adresu URL:

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

        Treść żądania (zamień YOUR_CLIENT_APP_ID na rzeczywisty identyfikator klienta aplikacji):

        {
   "appId": "YOUR_CLIENT_APP_ID"
}

      2. Wybierz Uruchom zapytanie. Powinieneś otrzymać odpowiedź 201 Created. Wartość id stanowi twoją SP_OBJECT_ID.

Uzyskaj identyfikator zasobu Graph

  1. Ustaw metodę Graph Explorer na GET i użyj tego adresu URL:

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

  2. Wybierz Uruchom zapytanie.

    • Jeśli zapytanie zakończy się powodzeniem, skopiuj wartość id. Wartość ta to Twój GRAPH_RESOURCE_ID.
    • Jeśli zapytanie zakończy się błędem uprawnień, wybierz kartę Modyfikuj uprawnienia, zaakceptuj wymagane uprawnienia, a następnie ponownie wybierz Uruchom zapytanie. Skopiuj wartość id. Wartość ta to Twój GRAPH_RESOURCE_ID.

Tworzenie delegowanych uprawnień

To wywołanie API udziela zgody administratora na poziomie dzierżawy dla wszystkich siedmiu uprawnień, w tym uprawnień beta, które nie są widoczne w centrum administracyjnym Microsoft Entra.

  1. Ustaw metodę Graph Explorer na POST i użyj tego adresu URL oraz treści żądania:

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

    Treść żądania:

    {
"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. Wybierz Uruchom zapytanie.

    • Jeśli otrzymasz 201 Createdodpowiedź: Powodzenie! Pole scope w odpowiedzi wyświetla wszystkie siedem nazw uprawnień. Gotowe.
    • Jeśli zapytanie zakończy się błędem uprawnień, przejdź do zakładki „Modyfikuj uprawnienia”, wyraź zgodę na wymagane uprawnienia, a następnie wybierz „Uruchom zapytanie ponownie”.
    • Jeśli pojawi się błąd Request_MultipleObjectsWithSameKeyValue: Przydział już istnieje. Może ktoś wcześniej dodał uprawnienia. Zobacz poniższą aktualizację delegowanych uprawnień.

Ostrzeżenie

W consentType: "AllPrincipals" żądaniu POST już przyznaje zgodę administracyjną dla całego dzierżawcy . NIE wybieraj opcji „Udziel zgody administratora” w centrum administracyjnym Microsoft Entra po użyciu tej metody API – spowoduje to usunięcie uprawnień beta, ponieważ centrum administracyjne Microsoft Entra nie widzi uprawnień beta i nadpisuje zgodę udzieloną przez API tylko widocznymi uprawnieniami.

Aktualizowanie delegowanych uprawnień

Gdy otrzymasz błąd Request_MultipleObjectsWithSameKeyValue podczas wykonywania kroków do tworzenia uprawnień delegowanych, wykonaj poniższe kroki, aby zaktualizować uprawnienia delegowane.

  1. Ustaw metodę Graph Explorer na GET i użyj tego adresu URL:

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

  2. Wybierz Uruchom zapytanie. Skopiuj wartość id z odpowiedzi. Wartość to YOUR_GRANT_ID.

  3. Ustaw metodę na PATCH w Graph Explorer, a następnie użyj tego URL z YOUR_GRANT_ID.

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

    Treść żądania:

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

  4. Wybierz Uruchom zapytanie. Powinieneś otrzymać odpowiedź 200 OK ze wszystkimi siedmioma uprawnieniami w polu scope.

5. Dodaj claim roli wids

Agent 365 CLI odczytuje przypisania ról w katalogu Entra bezpośrednio z tokena dostępu, aby sprawdzić, czy posiadasz uprawnienia administratora. Wymaga to dodania atrybutu (claim) „wids” do tokenów dostępu wydanych w ramach rejestracji Twojej aplikacji.

Bez tego atrybutu CLI nie wykrywa Twojej roli i zaczyna wyświetlać instrukcje PowerShell dla każdego kroku wymagającego uprawnień administratora — nawet gdy jesteś administratorem. Wykonaj ten krok, aby zapewnić poprawne działanie.

  1. W panelu rejestracji aplikacji przejdź do Token configuration.

  2. Wybierz Dodaj opcjonalne roszczenie.

  3. Dla typ tokena wybierz Dostęp.

  4. Na liście roszczeń zaznacz pole obok wids.

  5. Wybierz Dodaj.

    Jeśli pojawi się pytanie o włączenie uprawnień Microsoft Graph profile do włączenia roszczenia, wybierz Tak, dodaj.

Notatka

wids zawiera identyfikatory szablonów ról (GUID-y) ról katalogu Entra bezpośrednio przypisanych zalogowanemu użytkownikowi. CLI wykorzystuje te GUID-y do rozpoznania ról „Global Administrator” i „Agent ID Administrator” bez dodatkowego wywołania interfejs Graph API.

Ograniczenie:wids obejmuje wyłącznie bezpośrednio przypisane role. Jeśli Twoja dzierżawa przypisuje role katalogu za pomocą grup bezpieczeństwa z możliwością przypisywania ról, CLI może nie wykryć tych przypisań ról opartych na grupach. Bezpośrednie przypisywanie ról jest standardowym wzorcem zarówno dla roli Agent ID Developer, jak i ról administratora.

Najlepsze rozwiązania dotyczące zabezpieczeń

Zapoznaj się z tymi wytycznymi, aby utrzymać bezpieczeństwo i zgodność rejestracji aplikacji.

Tak:

  • Stosuj rejestrację pojedynczego dzierżawcy.
  • Zapewnij tylko wymagane uprawnienia delegowane.
  • Regularnie kontroluj uprawnienia.
  • Usuń aplikację, gdy nie będzie już potrzebna.

Nie:

  • Nadaj aplikacji uprawnienia. Używaj tylko delegowanych.
  • Udostępnij publicznie identyfikator klienta.
  • Udziel innych niepotrzebnych uprawnień.
  • Używaj aplikacji do innych celów.

Co CLI konfiguruje automatycznie

Gdy uruchamiasz a365 setup requirements, CLI potwierdza rejestrację aplikacji i może wymagać zmian. Przed wprowadzeniem jakichkolwiek zmian CLI pokazuje podsumowanie i prosi o potwierdzenie:

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

Aby pominąć monit potwierdzenia (np. w środowisku CI), użyj flagi --yes:

a365 setup requirements --yes

Poniższa tabela opisuje każdą zmianę, jaką może wprowadzić CLI:

Zmieni się Przyczyna
Doda przekierowanie identyfikatora URIhttp://localhost Microsoft Graph PowerShell SDK wymaga tego URI do uwierzytelniania przeglądarki. Bez niego operacje przyznawania uprawnień OAuth2 zamiast tego używają tokena, który nie posiada wymaganych uprawnień delegowanych i kończą się błędem 403.
Doda przekierowanie identyfikatora URIhttp://localhost:8400/ MSAL wymaga tego URI do interaktywnej uwierzytelniania przeglądarki.
Doda przekierowanie identyfikatora URIms-appx-web://Microsoft.AAD.BrokerPlugin/{id} Wymagane dla Web Account Manager (WAM), brokera uwierzytelniania w systemie Windows. Dowiedz się więcej o uzyskiwaniu tokenów powiązanych z urządzeniami.
Włącz "Zezwalaj na publiczne przepływy klientów" Wymagane do uwierzytelniania kodu urządzenia na macOS, Linux, Podsystemie Windows dla systemu Linux (WSL), w środowiskach bezgłowych oraz jako mechanizm awaryjny polityki dostępu warunkowego w Windows.
Dodawanie uprawnień do rejestracji aplikacji Utrzymuje rejestrację aplikacji aktualną względem nowo wymaganych uprawnień po aktualizacji CLI.
Zwiększ udzielanie zgody administratora Rozszerza istniejące uprawnienia OAuth2, aby objąć wszystkie nowo dodane uprawnienia.

Jeśli odrzucisz monit, CLI nie zmieni rejestracji aplikacji. Jeśli wymagane są zmiany do poprawnego działania CLI, możesz skonfigurować je ręcznie w centrum administracyjnym Microsoft Entra lub ponownie uruchomić z --yes.

Następne kroki

Po zarejestrowaniu niestandardowej aplikacji klienckiej użyj jej razem z Agent 365 CLI, aby ukończyć konfigurację Agent 365:

Rozpocznij rozwój Agent 365

Rozwiązywanie problemów

W tej sekcji opisano, jak rozwiązywać problemy związane z rejestracją niestandardowej aplikacji klienckiej.

Wskazówka

Przewodnik po rozwiązywaniu problemów Agent 365 zawiera wysokopoziomowe zalecenia dotyczące rozwiązywania problemów, najlepsze praktyki oraz odnośniki do treści dotyczących rozwiązywania problemów dla każdego etapu cyklu rozwoju Agent 365.

Walidacja CLI kończy się niepowodzeniem podczas konfiguracji

Objaw: Uruchomienie a365 setup lub a365 setup requirements powoduje pojawienie się błędów walidacji dotyczących Twojej niestandardowej aplikacji klienckiej.

Rozwiązanie: Skorzystaj z tej listy kontrolnej, aby zweryfikować, czy rejestracja aplikacji jest prawidłowa:

# Run requirements validation to see validation messages
a365 setup requirements

Oczekiwany wynik: CLI wyświetla Custom client app validation successful.

Jeśli nie uzyskasz oczekiwanego rezultatu, zweryfikuj każdy z następujących punktów kontrolnych:

Sprawdzanie Jak sprawdzić Napraw
✅ Użyto właściwego identyfikatora Skopiowałeś ID aplikacji (klienta) (nie ID obiektu) Przejdź do Przegląd w centrum administracyjnym Microsoft Entra
✅ Delegowane uprawnienia Uprawnienia wyświetlają Typ: Delegowane w uprawnieniach API Zobacz Nieprawidłowy typ uprawnień
✅ Wszystkie uprawnienia dodane Zapoznaj się ze wszystkimi uprawnieniami wymienionymi poniżej Wykonaj ponownie krok 4
✅ Wyrażanie zgody administratora Wszystkie wyświetlają zielony znacznik w polu Status Patrz Zgoda administratora przyznana nieprawidłowo

Wymagane uprawnienia delegowane:

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

Objaw: Walidacja nie powiodła się, mimo że dodałeś uprawnienia.

Przyczyna źródłowa: Nie udzieliłeś zgody administratora lub udzieliłeś jej w niewłaściwy sposób.

Rozwiązanie: W rejestracji aplikacji w centrum administracyjne Microsoft Entra przejdź do uprawnień API i wybierz Udziel zgody administratora dla [Twój Tenant]. Sprawdź, czy wszystkie uprawnienia są oznaczone zielonymi znacznikami pod status.

Objaw: a365 setup all drukuje "Skutecznie zapewniono delegowaną zgodę aplikacji", ale natychmiast nie wychodzi podczas tworzenia planu z:

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>

Przyczyna: Twój tenant ma już oauth2PermissionGrantrekord dla niestandardowej aplikacji klienckiej (z wcześniejszego częściowego uruchomienia konfiguracji lub wcześniejszej akcji "Grant admin consent" w centrum administracyjne Microsoft Entra dla innych zakresów), ale ten rekord nie zawiera wymaganego zakresuAgentIdentityBlueprint.ReadWrite.All. CLI wykrywa brakujący zakres i wyświetla adres URL zgody, aby administrator mógł dokończyć proces przyznania uprawnień.

Rozwiązanie:

Udostępnij adres URL zgody wyświetlony w wyjściu błędu administratorowi aplikacji lub administratorowi globalnemu. URL wygląda następująco:

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

Po wyrażeniu zgody przez administratora, uruchom ponownie a365 setup all --agent-name <name>.

Jeśli masz uprawnienia administratora, możesz otworzyć adres URL bezpośrednio w przeglądarce, aby wyrazić zgodę bez czekania.

Nieprawidłowy typ uprawnień

Objaw: CLI zgłasza błędy uwierzytelniania lub błędy odmowy uprawnień.

Przyczyna: Dodano uprawnienia aplikacji zamiast uprawnień delegowanych.

Ta tabela opisuje różne typy uprawnień.

Typ uprawnienia Kiedy używać Sposób użycia przez Agent 365 CLI
Delegowane („Zakres”) Użytkownik loguje się w trybie interaktywnym Agent 365 CLI używa tego – logujesz się, CLI działa w twoim imieniu
Aplikacja („Rola”) Usługa działa bez użytkownika Nie używaj – tylko dla procesów w tle/demonów

Dlaczego delegowane?

  • Logujesz się interaktywnie (uwierzytelnianie za pomocą przeglądarki)
  • CLI wykonuje działania w twoim imieniu (ścieżki audytu pokazują twoją tożsamość)
  • Bezpieczniejsze – ograniczone przez twoje rzeczywiste uprawnienia
  • Zapewnia odpowiedzialność i zgodność

Rozwiązanie:

  1. Przejdź do centrum administracyjne Microsoft Entra>Rejestracje aplikacji> Twoja aplikacja>Uprawnienia API
  2. Usuń wszelkie uprawnienia aplikacji. Te uprawnienia pojawiają się jako Application w kolumnie Type.
  3. Dodaj te same uprawnienia jako uprawnienia delegowane.
  4. Ponowne wyrażanie zgody administratora.

Objaw: Użyłeś Opcji B: Microsoft interfejs Graph API (dla uprawnień beta), aby dodać uprawnienia beta, ale znikają one po wybraniu Udzielenia zgody administratora w centrum administracyjnym Microsoft Entra.

Przyczyna źródłowa: Centrum administracyjne Microsoft Entra nie pokazuje uprawnień beta w interfejsie. Gdy wybierzesz Udziel zgody administratora, portal udziela zgody tylko na widoczne uprawnienia i nadpisuje zgodę udzieloną przez API.

Dlaczego tak się dzieje:

  1. Używasz Microsoft interfejs Graph API (Opcja B) do dodania wszystkich siedmiu uprawnień, w tym uprawnień beta.
  2. Wywołanie API z consentType: "AllPrincipals"już przyznaje zgodę administratora dla całego dzierżawcy.
  3. Wchodzisz do centrum administracyjne Microsoft Entra i widzisz tylko podzbiór uprawnień, ponieważ uprawnienia beta są niewidoczne w portalu.
  4. Wybierasz Grant admin consent, sądząc, że musisz to zrobić.
  5. Centrum administracyjne Microsoft Entra nadpisuje Twoją zgodę przyznaną przez API, nadając jej jedynie widoczne uprawnienia.
  6. Twoje uprawnienia beta zostały teraz usunięte.

Rozwiązanie:

  • Nie korzystaj z opcji zgody administratora w centrum administracyjnym Microsoft Entra po wykonaniu metody API: Metoda API już udziela zgody administratora.
  • Jeśli przypadkowo usuniesz uprawnienia beta, wykonaj ponownie Opcję B Krok 3 (Udziel zgody administracyjnej za pomocą interfejs Graph API), aby je przywrócić. Jeśli otrzymasz błąd Request_MultipleObjectsWithSameKeyValue, wykonaj kroki dotyczące „Aktualizacji delegowanych uprawnień”.
  • Aby zweryfikować, czy wszystkich siedmiu uprawnień jest wymienionych, sprawdź pole scope w odpowiedzi POST lub PATCH.

Nie znaleziono aplikacji podczas walidacji

Objaw: CLI zgłasza błędy Application not found lub Invalid client ID.

Rozwiązanie:

  1. Sprawdź, czy skopiowałeś(aś) ID aplikacji (klienta) w formacie GUID, a nie ID obiektu:

    • Przejdź do centrum administracyjne Microsoft Entra>Rejestracje aplikacji> Twoja aplikacja>Przegląd
    • Skopiuj wartość Identyfikator aplikacji (klienta)
    • Format powinien wyglądać następująco: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

  2. Sprawdź, czy aplikacja istnieje w Twoim dzierżawcy:

    # Sign in to the correct tenant
az login

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

Dowiedz się jak zarejestrować aplikację w Microsoft Entra ID.

  • Last updated on