Freigeben über

Dienst-zu-Dienst-Authentifizierung

Microsoft Community Training-APIs unterstützen die Dienst-zu-Dienst-Authentifizierung (Service to Service, S2S), damit externe Dienste die APIs aufrufen können, ohne dass sich ein Benutzer bzw. eine Benutzerin explizit bei einer MCT-Instanz anmelden muss.

Führen Sie die folgenden Schritte aus, um beliebigen externen Diensten das Aufrufen von Microsoft Community Training-APIs zu ermöglichen:

Schritt 1: Registrieren der Dienstanwendung

Führen Sie die im Anschluss angegebenen Schritte aus, um die Dienst-App zu registrieren. Registrieren Sie die Dienst-App:

  1. Melden Sie sich beim Azure-Portal an.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im Menü am oberen Rand den Filter Verzeichnis + Abonnement Verzeichnis-/Abonnementfilter, um den Mandanten auszuwählen, für den Sie eine Anwendung registrieren möchten.

    Hinweis

    Die zu registrierende Dienstanwendung muss im gleichen Azure-Mandanten erstellt werden, der auch für die betroffene MCT-Instanz verwendet wird.

  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.

  4. Wählen Sie unter „Verwalten“ Folgendes aus: „App-Registrierungen“ > „Neue Registrierung“.

  5. Geben Sie auf der daraufhin angezeigten Seite Anwendung registrieren die Registrierungsinformationen für Ihre Anwendung ein:

    • Geben Sie im Abschnitt „Name“ einen aussagekräftigen Anwendungsnamen ein, der den Benutzer*innen der App angezeigt werden soll (beispielsweise „MCT service“).
    • Behalten Sie für die unterstützten Kontotypen die Standardeinstellung „Nur Konten in diesem Organisationsverzeichnis“ bei.

  6. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.

  7. Wählen Sie den Abschnitt Eine API verfügbar machen aus, und gehen Sie dann folgendermaßen vor:

    • Klicken Sie neben „Anwendungs-ID-URI“ auf „Festlegen“. Behalten Sie den vorgeschlagenen Wert bei (beispielsweise api://webapi-clientid).
    • Klicken Sie auf „Speichern“. s2s picture 1.png

  8. Wählen Sie den Abschnitt „Manifest“ aus, und gehen Sie dann wie folgt vor:

    • Bearbeiten Sie das Manifest. Suchen Sie hierzu nach den App-Rollen (appRoles).
    • Die Rollendefinition finden Sie im JSON-Codeausschnipsel weiter unten.
    • Legen Sie „allowedMemberTypes“ auf „Application“ fest.
    • Geben Sie den Anzeigenamen (displayName) Ihrer App-Rollen ein. (Im folgenden Codeschnipsel wird beispielsweise „S2SAppRole“ als Anzeigename verwendet).
    • Für jede Rollendefinition in diesem Manifest muss eine andere gültige GUID für die Eigenschaft „Id“ angegeben werden.
    • Führen Sie zum Erstellen einer eindeutigen GUID in PowerShell den Befehl „new-guid“ aus.
    • Geben Sie den Wert der Rolle ein, wie oben im Schritt „Registrieren der Dienstanwendung“ erstellt. (Beispiel: S2SAppRole)
    • Ordnen Sie die entsprechenden Werte ordnungsgemäß zu, und speichern Sie das Manifest.

Hinweis

Der Inhalt von „appRoles“ muss wie folgt aussehen, und die ID muss eine eindeutige GUID sein:

{…
   "appRoles": [
      {
           "allowedMemberTypes": [
               "Application"
           ],
           "description": "Apps in this role can consume the web api.",
           "displayName": "S2SAppRole",
           "id": "Your guid created above",
           "isEnabled": true,
           "lang": null,
           "origin": "Application",
           "value": "S2SAppRole"
       }
   ],
...}

Speichern Sie die folgenden Werte zur späteren Verwendung:

  • Mandanten-ID: Kopieren Sie die Mandanten-ID von der Active Directory-Übersichtsseite.
  • Mandantenname: Kopieren Sie den Mandantennamen von der Übersichtsseite. (Beispiel: {beliebiger Name}.onmicrosoft.com)

Die Übersichtsseite sieht wie folgt aus:

s2s page overview.png

Anwendungs-ID-URI: Kopieren Sie den Wert von der Übersichtsseite der registrierten Anwendung, nachdem Sie den Schritt Verfügbarmachen einer API wie oben beschrieben abgeschlossen haben (z. B. api://<webapi-clientid>).

Die Übersichtsseite einer registrierten Anwendung sieht wie folgt aus:

s2s registered app overview.png

Wert: Die Rolle, die beim Bearbeiten des Manifests in den oben beschriebenen Schritten erstellt wurde (beispielsweise „S2SAppRole“).

Schritt 2: Registrieren von Clientanwendungen

Führen Sie für jede der Anwendungen, die die Microsoft Community Training-APIs aufrufen, die Schritte unter Ansatz 1 oder Ansatz 2 aus (je nach Art der Anwendung, die die APIs aufruft).

Ansatz 1: Der Dienst, der die API aufruft, wird in Azure gehostet. (Liste der Dienste)

Die im Anschluss beschriebenen Schritte gelten für Azure Functions. Für andere Dienste können ähnliche Schritte ausgeführt werden.

  1. Gehen Sie wie in diesem Dokument beschrieben vor, um eine neue Azure-Funktions-App zu erstellen.
  2. Navigieren Sie zu der erstellten Funktions-App, und klicken Sie links auf den Abschnitt „Identität“.

    1. Legen Sie den Status auf „Ein“ fest. Klicken Sie auf „Speichern“.

    2. Kopieren Sie den auf dem nächsten Bildschirm angezeigten Wert der Objekt-ID. Er wird später noch benötigt.

      Objekt-ID

    3. Führen Sie die in diesem Dokument beschriebenen Schritte aus, um ein Token zum Aufrufen der APIs zu generieren. Zum Generieren des Tokens wird ein Ressourcenparameter benötigt. Geben Sie für diesen Parameter den Wert des Anwendungs-ID-URI an, der im Schritt „Registrieren der Dienstanwendung“ erstellt wurde. (Beispiel: api://{ID})

Hinweis

Sie können eine beliebige Programmiersprache verwenden (basierend auf dem Laufzeitstapel, der beim Erstellen der Funktions-App gewählt wurde).

Ansatz 2 (Alternative): Erstellen eines Clients mithilfe des Flusses von Clientanmeldeinformationen

Führen Sie die im Anschluss angegebenen Schritte aus, um die Client-App zu registrieren.

  1. Melden Sie sich beim Azure-Portal an.
  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie den Verzeichnis- und Abonnementfilter Verzeichnis- und Abonnementfilter im oberen Menü, um den Mandanten auszuwählen, in dem Sie eine Anwendung registrieren möchten.
  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.
  4. Wählen Sie unter Verwalten Folgendes aus: App-Registrierungen > Neue Registrierung.
    • Geben Sie im Abschnitt Name einen aussagekräftigen Anwendungsnamen ein, der den Benutzer*innen der App angezeigt werden soll (beispielsweise „S2S-client“).
    • Wählen Sie im Abschnitt Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis ({Mandantenname}) aus.
    • Wählen Sie Registrieren aus, um die Anwendung zu erstellen.
  5. Suchen Sie auf der Seite Übersicht den Wert von Anwendungsclient-ID und notieren Sie ihn zur späteren Verwendung.
  6. Wählen Sie auf der Seite "Zertifikate und geheime Schlüssel" im Abschnitt "Geheime Clientschlüssel" die Option "Neuer geheimer Clientschlüssel" aus:
    • Geben Sie eine Schlüsselbeschreibung (des App-Geheimnisses der Instanz) ein.
    • Wählen Sie eine Schlüsseldauer aus: In 1 Jahr, In 2 Jahren oder „Läuft nie ab.“.
    • Wenn Sie auf die Schaltfläche Hinzufügen klicken, wird der Schlüsselwert angezeigt. Kopieren Sie den Wert, und speichern Sie ihn an einem sicheren Ort.
    • Dieser Schlüssel wird später benötigt, um das Projekt in Visual Studio zu konfigurieren. Der Schlüsselwert wird nicht erneut angezeigt und kann auch nicht auf andere Weise abgerufen werden. Erfassen Sie ihn daher, sobald er im Azure-Portal angezeigt wird.
  7. Wählen Sie in der Liste mit den Seiten für die App die Option API-Berechtigungen aus.
    • Klicken Sie auf die Schaltfläche Berechtigung hinzufügen.
    • Stellen Sie sicher, dass die Registerkarte Meine APIs ausgewählt ist.
    • Wählen Sie die API aus, die im vorherigen Schritt erstellt wurde (z. B. „MCT service“ aus dem Schritt „Registrieren der Dienstanwendung“).
    • Vergewissern Sie sich im Abschnitt „Anwendungsberechtigungen“, dass die richtigen Berechtigungen aktiviert sind (beispielsweise „S2SAppRole“ aus dem Schritt Registrieren der Dienstanwendung).
    • Wählen Sie die Schaltfläche Berechtigungen hinzufügen aus.
  8. In dieser Phase werden Berechtigungen ordnungsgemäß zugewiesen, aber die Client-App lässt keine Interaktion zu. Daher kann keine Einwilligung über eine Benutzeroberfläche angezeigt und für die Nutzung der Dienst-App akzeptiert werden. Klicken Sie auf die Schaltfläche Administratoreinwilligung für {Mandant} erteilen/widerrufen, und wählen Sie anschließend Ja aus, wenn Sie gefragt werden, ob Sie Ihre Einwilligung für die angeforderten Berechtigungen für alle Konten im Mandanten erteilen möchten. Dieser Schritt kann nur von Azure AD-Mandantenadministrator*innen ausgeführt werden.

Hinweis

  • Verwenden Sie diesen Link, um Token zum Aufrufen von APIs zu generieren.
POST /{tenant}/oauth2/v2.0/token HTTP/1.1     //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=<The application ID that's assigned to your app>
&scope=https://graph.microsoft.com/.default
&client_secret=sampleCredentials
&grant_type=client_credentials
  • Bei dem Wert, der in dieser Anforderung für den Parameter scope übergeben wird, muss es sich um den Ressourcenbezeichner (Anwendungs-ID-URI) der gewünschten Ressource handeln, und er muss mit dem Suffix .default versehen werden: api://webapi-clientid/.default. Für das angegebene Microsoft Graph-Beispiel ist der Wert https://graph.microsoft.com/.default.

Schritt 3: Konfigurieren der Azure App Service-Instanz

  1. Navigieren Sie zu der Ressourcengruppe, die im Rahmen der Microsoft Community Training-Bereitstellung erstellt wurde.
  2. Wechseln Sie unter der Liste der Ressourcen zur Ressource "App Service".

    Warnung

    Der Name dieser Ressource ist der Name, der bei der Erstellung der Bereitstellung als Websitename angegeben wurde.
    Für die Funktions-App wird noch eine weitere App Service-Ressource erstellt. (Der Name dieser Ressource enthält normalerweise „-fa-“.) Diese Ressource darf NICHT ausgewählt werden.

  3. Klicken Sie links auf den Abschnitt „Konfiguration“, nachdem Sie zur App Service-Ressource navigiert sind.
  4. Klicken Sie auf „Neue Anwendungseinstellung“.
  5. Fügen Sie unter „Name“ den Namen ServiceAuthEnabled und unter „Wert“ den Wert true hinzu. Klicken Sie auf „OK“. ServiceAuthEnabled
  6. Fügen Sie in der Konfiguration auf ähnliche Weise die folgenden Werte hinzu. Klicken Sie nach dem Hinzufügen aller Werte auf „Speichern“, und starten Sie App Service neu.
    1. ServiceAuthAudience: Der Anwendungs-ID-URI, der im Schritt „Registrieren der Dienstanwendung“ erstellt wurde
    2. ServiceAuthTenantName: Der Mandantenname, der im Schritt „Registrieren der Dienstanwendung“ abgerufen wurde
    3. ServiceAuthTenantID: Die Mandanten-ID, die im Schritt „Registrieren der Dienstanwendung“ abgerufen wurde
    4. ServiceObjectIds: Nur erforderlich, wenn es sich um einen Clienttyp aus dem oben beschriebenen Ansatz 1 handelt. Geben Sie die weiter oben abgerufene Objekt-ID ein. Wenn mehrere Clients dieses Typs erstellt werden, geben Sie alle hier ein, und trennen Sie sie jeweils durch ein Semikolon (Objekt-ID 1;Objekt-ID 2...). Dies ist die Client-Objekt-ID aus Schritt 2, Ansatz 1.
    5. ServiceApplicationIds: Nur erforderlich, wenn es sich um einen Clienttyp aus dem oben beschriebenen Ansatz 2 handelt. Geben Sie die weiter oben abgerufene Anwendungs-ID ein. Wenn mehrere Clients dieses Typs erstellt werden, geben Sie alle hier ein, und trennen Sie sie jeweils durch ein Semikolon (Anwendungs-ID 1;Anwendungs-ID 2…). Dies ist die Clientanwendungs-ID aus Schritt 2, Ansatz 2.
    6. ServiceAuthRole: Nur bei Clients vom Typ 2 erforderlich. b) Geben Sie den Wert der Rolle ein, der oben im Schritt Registrieren der Dienstanwendung im Manifest erstellt wurde (Beispiel: S2SAppRole).

Warnung

Fügen Sie bei Dienstauthentifizierungsaufrufen einen neuen Header mit dem Schlüssel „ClientType“ und dem Wert „Service“ hinzu.

Die oben erstellten Clients sollten jetzt die Microsoft Community Training-APIs aufrufen können. Fügen Sie die oben generierten Token den REST-APIs hinzu, die von der Plattform verfügbar gemacht werden.