Freigeben über

Microsoft Entra-Manifest bearbeiten

  • Artikel

Das Microsoft Teams-Toolkit verwaltet jetzt Microsoft Entra Anwendung mit der App-Manifestdatei als Quelle der Wahrheit während des Entwicklungslebenszyklus Ihrer Microsoft Teams-Anwendung.

Anpassen Microsoft Entra Manifestvorlage

Sie können Microsoft Entra Manifestvorlage anpassen, um Microsoft Entra Anwendung zu aktualisieren.

  1. Öffnen Sie aad.template.json in Ihrem Projekt.

    Screenshot: Vorlage

  2. Aktualisieren Sie die Vorlage direkt, oder verweisen Sie auf Werte aus einer anderen Datei. Es folgen die Anpassungsszenarien:

    Hinzufügen einer Anwendungsberechtigung

    Wenn die Teams-Anwendung mehr Berechtigungen benötigt, um eine API mit zusätzlichen Berechtigungen aufzurufen, müssen Sie die Eigenschaft in der Microsoft Entra Manifestvorlage aktualisierenrequiredResourceAccess. Sie sehen das folgende Beispiel für diese Eigenschaft:

            "requiredResourceAccess": [
{
        "resourceAppId": "Microsoft Graph",
        "resourceAccess": [
            {
                "id": "User.Read", // For Microsoft Graph API, you can also use uuid for permission id
                "type": "Scope" // Scope is for delegated permission
            },
            {
                "id": "User.Export.All",
                "type": "Role" // Role is for application permission
            }
        ]
    },
    {
        "resourceAppId": "Office 365 SharePoint Online",
        "resourceAccess": [
            {
                    "id": "AllSites.Read",
            "type": "Scope"
            }
        ]
    }
]

    Die folgende Liste enthält verschiedene Eigenschafts-IDs und deren Verwendung:

    • Die resourceAppId -Eigenschaft wird für verschiedene APIs verwendet. Microsoft Graph Geben Sie für und Office 365 SharePoint Onlineden Namen direkt anstelle von UUID ein, und verwenden Sie für andere APIs UUID.

    • Die resourceAccess.id -Eigenschaft wird für unterschiedliche Berechtigungen verwendet. Geben Sie für Microsoft Graph und Office 365 SharePoint Onlineden Berechtigungsnamen direkt anstelle von UUID ein, und verwenden Sie für andere APIs UUID.

    • Die resourceAccess.type -Eigenschaft wird für delegierte Oder Anwendungsberechtigungen verwendet. Scope bedeutet delegierte Berechtigung und Role bedeutet Anwendungsberechtigung.

    Vorabauthentifizierung einer Clientanwendung

    Sie können die -Eigenschaft verwenden preAuthorizedApplications , um eine Clientanwendung zu autorisieren, um anzugeben, dass die API der Anwendung vertraut. Benutzer stimmen nicht zu, wenn der Client die verfügbar gemachte API aufruft. Sie sehen das folgende Beispiel für diese Eigenschaft:

    
      "preAuthorizedApplications": [
      {
          "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
          "permissionIds": [
               "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
           ]
      }
      ...
  ]

    preAuthorizedApplications.appId -Eigenschaft wird für die Anwendung verwendet, die Sie autorisieren möchten. Wenn Sie die Anwendungs-ID nicht kennen und nur den Anwendungsnamen kennen, führen Sie die folgenden Schritte aus, um die Anwendungs-ID zu durchsuchen:

    1. Wechseln Sie zu Azure-Portal, und öffnen Sie Anwendungsregistrierungen.

    2. Wählen Sie Alle Anwendungen aus, und suchen Sie nach dem Anwendungsnamen.

    3. Wählen Sie den Anwendungsnamen aus, und rufen Sie die Anwendungs-ID auf der Übersichtsseite ab.

    Aktualisieren der Umleitungs-URL für die Authentifizierungsantwort

    Umleitungs-URLs werden verwendet, wenn Authentifizierungsantworten wie Token nach erfolgreicher Authentifizierung zurückgegeben werden. Sie können Umleitungs-URLs mithilfe der -Eigenschaft replyUrlsWithTypeanpassen. Wenn Sie beispielsweise als Umleitungs-URL hinzufügen https://www.examples.com/auth-end.html möchten, können Sie sie im folgenden Beispiel hinzufügen:

        "replyUrlsWithType": [
       ...
     {
         "url": "https://www.examples.com/auth-end.html",
         "type": "Spa"
     }
]

  3. Aktualisieren sie Microsoft Entra Anwendungsänderungen für lokale oder Remoteumgebungen.

    1. Wählen Sie Preview codeLens in aus aad.template.json.

      Screenshot: Vorschau

    2. Wählen Sie lokale oder Entwicklungsumgebung aus.

      Screenshot: Umgebungsliste

    3. Wählen Sie Deploy Azure AD Manifest CodeLens in aad.local.json oder aad.dev.jsonaus.

      Screenshot: Hervorgehobene Bereitstellungsoption

    4. Die Änderungen für Microsoft Entra Anwendung, die in der lokalen Oder Entwicklungsumgebung verwendet wird, werden bereitgestellt.

    5. Darüber hinaus können Sie die Befehlspalette öffnen und Teams: Update Microsoft Entra App auswählen, um Microsoft Entra App zu aktualisieren. Screenshot: Option

Es ist ein Problem aufgetreten.

Microsoft Entra Platzhalter für Manifestvorlagen

Die Microsoft Entra Manifestdatei enthält Platzhalterargumente mit {{...}} -Anweisungen wird sie während des Builds für verschiedene Umgebungen ersetzt. Sie können mit den Platzhalterargumenten auf Umgebungsvariablen verweisen.

Referenzumgebungsvariable in Microsoft Entra Manifestvorlage

Sie müssen keine dauerhaften Werte in Microsoft Entra Manifestvorlage eingeben, und Microsoft Entra Manifestvorlagendatei unterstützt Referenzumgebungsvariablenwerte. Sie können die Syntax ${{YOUR_ENV_VARIABLE_NAME}} im Tool als Parameterwerte verwenden, um die Umgebungsvariablenwerte aufzulösen.

Bearbeiten und Anzeigen einer Vorschau Microsoft Entra Manifests mit CodeLens

Microsoft Entra Manifestvorlagendatei enthält CodeLens zum Überprüfen und Bearbeiten des Codes.

Microsoft Entra Manifestvorlagendatei

Am Anfang der Microsoft Entra Manifestvorlagendatei befindet sich eine CodeLens-Vorschau. Wählen Sie codeLens aus, um ein Microsoft Entra Manifest basierend auf Ihrer Umgebung zu generieren.

Screenshot: Vorschau des Hinzufügens von CodeLens

Platzhalterargument CodeLens

Das Platzhalterargument CodeLens hilft Ihnen, die Werte für das lokale Debuggen und die Entwicklung Ihrer Umgebung anzuzeigen. Wenn Sie mit dem Mauszeiger auf das Platzhalterargument zeigen, wird das QuickInfo-Feld für die Werte aller Umgebungen angezeigt.

Screenshot: Hinzufügen von Argumenten

Erforderliche RessourcenzugriffscodeLens

Microsoft Entra Manifestvorlage im Teams Toolkit unterstützt auch vom Benutzer lesbare Zeichenfolgen für Microsoft Graph - und Office 365 SharePoint Online -Berechtigungen. Das offizielle Microsoft Entra Manifestschema, bei dem es sich um die resourceAppId - und resourceAccess -requiredResourceAccessEigenschaft handelt, unterstützt nur die UUID. Wenn Sie UUID eingeben, zeigt CodeLens lesbare Zeichenfolgen an, andernfalls wird die UUID angezeigt.

Screenshot: Hinzufügen einer Ressource zum erforderlichen Ressourcenzugriff

Vorautorisierte Anwendungen CodeLens

CodeLens zeigt den Anwendungsnamen für die vorautorisierte Anwendungs-ID für die preAuthorizedApplications Eigenschaft an.

Anzeigen Microsoft Entra Anwendung auf dem Azure-Portal

  1. Kopieren Sie die client-ID der Microsoft Entra Anwendung aus der .env.xxx Datei () in der AAD_APP_CLIENT_ID -Eigenschaft.

    Screenshot: Client-ID

    Hinweis

    xxx in der Client-ID gibt den Umgebungsnamen an, in dem Sie die Microsoft Entra Anwendung bereitgestellt haben.

  2. Wechseln Sie zu Azure-Portal, und melden Sie sich beim Microsoft 365-Konto an.

    Hinweis

    Stellen Sie sicher, dass die Anmeldeinformationen der Teams-Anwendung und des M365-Kontos identisch sind.

  3. Öffnen Sie die Seite App-Registrierungen, und durchsuchen Sie die Microsoft Entra Anwendung mithilfe der Zuvor kopierten Client-ID.

    Screenshot: Client-ID auf der Registerkarte

  4. Wählen Sie Microsoft Entra Anwendung aus dem Suchergebnis aus, um die ausführlichen Informationen anzuzeigen.

  5. Wählen Sie Microsoft Entra App-Informationsseite das Menü Manifest aus, um das Manifest dieser Anwendung anzuzeigen. Das Schema des Manifests ist identisch mit dem Schema in der aad.template.json Datei. Weitere Informationen zum Manifest finden Sie unter Microsoft Entra App-Manifest.

    Screenshot: Bildschirm

  6. Sie können andere Menüs auswählen, um Microsoft Entra Anwendung über das zugehörige Portal anzuzeigen oder zu konfigurieren.

Es ist ein Problem aufgetreten.

Verwenden einer vorhandenen Microsoft Entra-Anwendung

Sie können die vorhandene Microsoft Entra-Anwendung für das Teams-Projekt verwenden. Weitere Informationen finden Sie unter Verwenden einer vorhandenen Microsoft Entra-Anwendung für Ihre Teams-Anwendung.

Microsoft Entra Anwendung im Teams-Anwendungsentwicklungslebenszyklus

Sie müssen in verschiedenen Phasen ihres Teams-Anwendungsentwicklungslebenszyklus mit Microsoft Entra Anwendung interagieren.

  1. So erstellen Sie Ein Projekt

    Sie können ein Projekt mit dem Teams Toolkit erstellen, das standardmäßig unterstützung für einmaliges Anmelden (Single Sign-On, SSO) bietet, z SSO-enabled tab. B. . Weitere Informationen zum Erstellen einer neuen App finden Sie unter Erstellen einer neuen Teams-Anwendung mithilfe des Teams-Toolkits. In wird automatisch eine Microsoft Entra Manifestdatei für Sie aad.template.jsonerstellt. Teams Toolkit erstellt oder aktualisiert die Microsoft Entra Anwendung während der lokalen Entwicklung oder während des Verschiebens der Anwendung in die Cloud.

  2. So fügen Sie Ihrem Bot oder Ihrer Registerkarte SSO hinzu

    Nachdem Sie eine Teams-Anwendung ohne integriertes einmaliges Anmelden erstellt haben, hilft Ihnen das Teams Toolkit schrittweise beim Hinzufügen von SSO für das Projekt. Daher wird in aad.template.jsonautomatisch eine Microsoft Entra Manifestdatei für Sie erstellt.

    Teams Toolkit erstellt oder aktualisiert die Microsoft Entra-Anwendung während der nächsten lokalen Entwicklungssitzung oder beim Verschieben der Anwendung in die Cloud.

  3. So erstellen Sie lokal

    Das Teams-Toolkit führt während der lokalen Entwicklung die folgenden Funktionen aus:

    • Lesen Sie die .env.local Datei, um nach einer vorhandenen Microsoft Entra Anwendung zu suchen. Wenn bereits eine Microsoft Entra Anwendung vorhanden ist, wird die vorhandene Microsoft Entra-Anwendung wiederverwendet. Andernfalls müssen Sie mithilfe der aad.template.json Datei eine neue Anwendung erstellen.

    • Ignoriert anfänglich einige Eigenschaften in der Manifestdatei, die mehr Kontext erfordern, zreplyUrls. B. die Eigenschaft, die bei der Erstellung einer neuen Microsoft Entra Anwendung mit der Manifestdatei einen lokalen Entwicklungsendpunkt erfordert.

    • Nachdem die lokale Entwicklungsumgebung erfolgreich gestartet wurde, werden die Microsoft Entra, und andere Eigenschaften der AnwendungidentifierUrisreplyUrls, die während der Erstellungsphase nicht verfügbar sind, entsprechend aktualisiert.

    • Die Änderungen, die Sie an Ihrer Microsoft Entra Anwendung vorgenommen haben, werden während der nächsten lokalen Entwicklungssitzung geladen. Sie können sehen, Microsoft Entra Anwendungsänderungen manuell angewendet wurden.

  4. So stellen Sie Cloudressourcen bereit

    Sie müssen Cloudressourcen bereitstellen und Ihre Anwendung bereitstellen, während Sie Ihre Anwendung in die Cloud verschieben. In Phasen, z. B. lokales Debuggen, Teams Toolkit:

    • Liest die .env.{env} Datei, um nach einer vorhandenen Microsoft Entra-Anwendung zu suchen. Wenn bereits eine Microsoft Entra Anwendung vorhanden ist, wird die vorhandene Microsoft Entra-Anwendung wiederverwendet. Andernfalls müssen Sie mithilfe der aad.template.json Datei eine neue Anwendung erstellen.

    • Ignoriert zunächst einige Eigenschaften in der Manifestdatei, die mehr Kontext erfordern, z replyUrls . B. die -Eigenschaft. Diese Eigenschaft erfordert einen Front-End- oder Botendpunkt während der Erstellung einer neuen Microsoft Entra Anwendung mit der Manifestdatei.

    • Schließt die Bereitstellung anderer Ressourcen ab und Microsoft Entra anwendung identifierUrisreplyUrls und wird entsprechend den richtigen Endpunkten aktualisiert.

  5. So erstellen Sie eine Anwendung

    • Der Cloudbefehl stellt Ihre Anwendung für die bereitgestellten Ressourcen bereit. Die Bereitstellung Microsoft Entra von Ihnen vorgenommenen Anwendungsänderungen ist nicht enthalten.

    • Teams Toolkit aktualisiert die Microsoft Entra-Anwendung gemäß der Microsoft Entra Manifestvorlagendatei.

Begrenzungen

  1. Die Teams Toolkit-Erweiterung unterstützt nicht alle Eigenschaften, die in Microsoft Entra Manifestschema aufgeführt sind.

    In der folgenden Tabelle sind die Eigenschaften aufgeführt, die in der Teams Toolkit-Erweiterung nicht unterstützt werden:

    Nicht unterstützte Eigenschaften Grund
    passwordCredentials Im Manifest nicht zulässig
    createdDateTime Schreibgeschützt und kann nicht geändert werden
    logoUrl Schreibgeschützt und kann nicht geändert werden
    publisherDomain Schreibgeschützt und kann nicht geändert werden
    oauth2RequirePostResponse Ist in Graph-API nicht vorhanden
    oauth2AllowUrlPathMatching Ist in Graph-API nicht vorhanden
    samlMetadataUrl Ist in Graph-API nicht vorhanden
    orgRestrictions Ist in Graph-API nicht vorhanden
    certification Ist in Graph-API nicht vorhanden

  2. Die requiredResourceAccess -Eigenschaft wird nur für vom Benutzer lesbare Ressourcenanwendungsnamen- oder Berechtigungsnamenzeichenfolgen für Microsoft Graph apIs und Office 365 SharePoint Online verwendet. Sie müssen UUID für andere APIs verwenden. Führen Sie die folgenden Schritte aus, um IDs aus Azure-Portal abzurufen:

    1. Registrieren Sie eine neue Microsoft Entra-Anwendung auf Azure-Portal.
    2. Wählen Sie API permissions auf der Anwendungsseite Microsoft Entra aus.
    3. Wählen Sie aus add a permission , um die erforderliche Berechtigung hinzuzufügen.
    4. Wählen Sie Manifest aus der requiredResourceAccess Eigenschaft aus, in der Sie die IDs der API und die Berechtigungen finden.

Siehe auch