Table of contents
TOC
Inhaltsverzeichnis reduzieren
Inhaltsverzeichnis erweitern
Zuletzt aktualisiert: 20.06.2018

Erstellen von Dienst- und Daemon-Apps in Office 365

Gilt für: Office 365

Geräte- und Webserveranwendungen erfordern in der Regel die Anmeldung und Zustimmung eines Benutzers, damit die Anwendung auf ihre Informationen in Office 365 zugreifen und damit arbeiten kann. Das zugrunde liegende Protokoll für den Zugriff basiert auf dem OAuth2 Berechtigungscode Grant Flow. Als Teil dieses OAuth2-Flusses erhält die Anwendung ein Zugriffstoken/Aktualisierungs-Token-Paar, das eine Delegation repräsentiert, die der Anwendung von einem einzelnen Benutzer für eine Reihe von Berechtigungen erteilt wurde. Bevor die Anwendung auf die Daten eines Benutzers zugreifen kann, muss sie für jeden Benutzer ein Zugriffstoken/Refresh-Token erhalten, und um diese zu erhalten, muss sich der Benutzer mindestens einmal an der Anwendung anmelden.

Dies ist nicht möglich für Anwendungen, die im Hintergrund laufen, wie z.B. eine Daemon- oder Dienst-App. Diese Anwendungen benötigen Zugriff, ohne dass sich ein Benutzer anmelden muss. OAuth2 bietet die Client-Anmeldeinformationen Grant Flow für diese Art von Anwendungen, und Office 365 unterstützt die Verwendung dieses Flusses.

Bei Verwendung dieses Flusses präsentiert die App ihre Client-Anmeldeinformationen dem OAuth2-Token ausstellenden Endpunkt und erhält im Gegenzug ein Zugriffstoken, das die Anwendung selbst ohne jegliche Benutzerinformationen repräsentiert. Das Token in diesem Szenario wird als App-Only Zugriffstoken bezeichnet.

Es besteht keine Notwendigkeit für die App, einen Refresh-Token zu erhalten, denn wenn der Zugriffstoken abläuft, geht es einfach zurück zum OAuth2-Token-Ausgabe-Endpunkt, um einen neuen zu erhalten. Da es keine Benutzerinformationen im App-Only-Token gibt, muss die Anwendung den Benutzer innerhalb des API-Aufrufs angeben, wenn sie dieses Token verwendet.

Definieren der Berechtigungen

Um Ihre Anwendung für App-Only-Token zu konfigurieren, müssen Sie zunächst festlegen, welche Berechtigungen Ihre Anwendung benötigt. Diese Berechtigungen geben Sie bei der Registrierung Ihrer Anwendung im Azure Management Portal für Microsoft Azure Active Directory (Azure AD) an. Wählen Sie den Typ der Anwendungsberechtigungen, da diese direkt der Anwendung zugeordnet sind. Siehe Abbildung 1 für einen Screenshot des Abschnitts Azure AD Berechtigungen zur Anwendungsregistrierung.

Abbildung 1. Konfiguration der Anwendungsberechtigungen in Azure ADEin Screenshot, der die Anwendungsberechtigungen in der Azure-Verwaltungskonsole zeigt.

Hinweis Bei der Registrierung der App in Azure AD müssen Sie den Typ Web-Anwendung und/oder Web API auswählen, da für systemeigene Client-Anwendungen keine App-only-Berechtigungen verfügbar sind.

Sobald die Berechtigungen in der App-Registrierung festgelegt sind, kann die App um Zustimmung bitten, um in einer anderen Office 365-Organisation verfügbar zu sein. App-Berechtigungen müssen von einem Office 365-Mandanten-Administrator genehmigt werden. Dies liegt daran, dass diese Anwendungen in Bezug auf die Daten, auf die sie innerhalb einer Office 365-Organisation zugreifen können, sehr leistungsfähig sind. Beispielsweise kann eine Service-Anwendung mit der Berechtigung Mail.Read, die über den Client-Anmeldefluss Zugriffstoken erhält, E-Mails in jedem Postfach innerhalb der Office 365-Organisation lesen.

Aufgrund des breiten Zugriffs auf diese Anwendungen müssen Anwendungen auch ein X.509-Zertifikat mit einem öffentlichen/privaten Schlüsselpaar verwenden, um erfolgreich ein Zugriffstoken zu erhalten. Die Verwendung von einfachen symmetrischen Schlüsseln ist nicht erlaubt, und während die Anwendung ein Zugriffstoken mit einem symmetrischen Schlüssel erhalten könnte, gibt die API einen Zugriffsverweigerungsfehler für diese Zugriffstoken zurück. Selbst erstellte X.509-Zertifikate werden akzeptiert, aber die App muss das öffentliche X.509-Zertifikat mit der Anwendungsdefinition in Azure AD registrieren. Die App pflegt dann den privaten Schlüssel und verwendet ihn, um seine Identität gegenüber dem Token ausstellenden Endpunkt zu behaupten.

Sie implementieren den Autorisierungsablauf analog zum Autorisierungscode Grant Flow, indem Sie eine Anfrage an den OAuth2 Authorize Endpunkt senden. Sobald der autorisierte Endpunkt jedoch mit einem Autorisierungscode an die Anwendung zurückgeleitet wird, kann der verbleibende Code ignoriert werden; um Token zu erhalten, sind nur die Client-Anmeldeinformationen erforderlich. Sie könnten eine Routine wie "Meine Organisation anmelden" in Ihre Anwendung einbauen, um die erste einmalige Einwilligung zu erhalten. Der Schlüssel zum Erfolg ist, dass Sie eine einmalige Einwilligung in die Konfiguration Ihrer Daemon- oder Dienst-Anwendung vornehmen müssen. Sobald die Zustimmung erteilt wurde, kann die Anwendung Zugriffstoken erhalten und die Office 365-APIs aufrufen.

Sie können die Zustimmung zu Dienst-Apps wie alle anderen von einem Office 365-Mandantenadministrator installierten Apps widerrufen. Der Administrator kann entweder zum Azure-Verwaltungsportalgehen, die Anwendung in der Anwendungsansicht finden, sie auswählen und löschen oder alternativ das Remove-MSOLServicePrincipal Cmdlet aus dem Azure AD-Modul für Windows PowerShell verwenden.

Erwerb eines Zugriffstokens mit dem Fluss Client-Berechtigungsnachweise

Bei der Anforderung von App-Only-Token müssen Sie einen mandantenspezifischen Token-Ausgabe-Endpunkt verwenden. Wenn Sie den gemeinsamen (mandantenunabhängigen) Endpunkt verwenden, wird ein Fehler zurückgegeben.

Während des Zustimmungsprozesses, wenn der autorisierte Endpunkt getroffen wird und ein Code in der Weiterleitung an die App geliefert wird, kann Ihre App ein ID-Token zusammen mit dem Code anfordern. Dieses Token ist ein JSON-Web-Token, das die Mandanten-ID als tid Claim-Typ enthält, so dass Sie diese nur analysieren müssen, um die ID für den mandantenspezifischen Endpunkt zu erhalten.

Das folgende Beispiel zeigt, wie die Einwilligung durch eine OpenID Connect Hybrid Flow Anfrage ausgelöst wird:

GET https://login.microsoftonline.com/common/oauth2/authorize?state=e82ea723-7112-472c-94d4-6e66c0ca52b6&response_type=code+id_token&scope=openid&nonce=c328d2df-43d1-4e4d-a884-7cfb492beadc&client_id=0308CDD9-874D-4F87-85E0-A0DA7E05F999&redirect_uri=https:%2f%2flocalhost:44304%2fHome%2f&resource=https:%2f%2fgraph.windows.net%2f&prompt=admin_consent&response_mode=form_post HTTP/1.1

Diese Anfrage versorgt Ihre App mit dem Zustimmungsfluss und leitet sie mit dem Code und dem ID-Token in einer POST-Anfrage zurück. Ihre App kann den Code ignorieren und das ID-Token aus den empfangenen Formulardaten abrufen. Weitere Informationen zum Formular Bereitstellen Antwort-Modus finden Sie unter OpenID spec.

In ASP.Net können Sie das ID-Token über Request.Form["id_token"] auf der Redirect-Seite abrufen und die Mandanten-ID in der tid claim innerhalb der id_tokenfinden.

Einen App-only-Token erhalten

Der folgende Codeausschnitt zeigt die Verwendung der Azure AD-Clientbibliothek, um ein App-only-Token über den Fluss Client-Berechtigungsnachweis zu erhalten:

//need to address the tenant specific authority/token issuing endpoint
//https://login.microsoftonline.com/<tenant-id>/oauth2/authorize
//retrieved tenantID from ID token for the app during consent flow (authorize flow)
string authority = appConfig.AuthorizationUri.Replace("common", tenantId);
AuthenticationContext authenticationContext = new AuthenticationContext(authority,false);
string certfile = Server.MapPath(appConfig.ClientCertificatePfx);
X509Certificate2 cert = new X509Certificate(certfile,appConfig.ClientCertificatePfxPassword, X509KeyStorageFlags.MachineKeySet);
ClientAssertionCertificate cac = new ClientAssertionCertificate(appConfig.ClientId, cert);
var authenticationResult = await authenticationContext.AcquireTokenAsync(resource, cac);
return authenticationResult.AccessToken;

Die Anwendung für dieses Beispiel verwaltet den privaten Schlüssel in einem gut geschützten Verzeichnis auf dem Webserver als PFX-Datei. Es ist jedoch besser, den privaten Schlüssel in einem sichereren Speicher wie dem Windows-Zertifikatsspeicher des Computerkontos aufzubewahren. Ein vollständiges Beispiel einer Webanwendung, die den Anmelde-Informationsfluss für Clients verwendet, finden Sie in der o365api-as-apponly-webapp sample.

Konfigurieren eines öffentlichen X.509-Zertifikats für Ihre Anwendung

Der letzte Teil ist die Konfiguration eines öffentlichen X.509-Zertifikats für Ihre Anwendung. Da dies in der Benutzeroberfläche des Azure-Management-Portals nicht sichtbar ist, müssen Sie dies durch manuelle Bearbeitung des App-Manifests konfigurieren. Führen Sie dazu die folgenden Aktionen aus:

  • Erstellen Sie ein selbst ausgestelltes Zertifikat, wenn Sie noch kein X.509-Zertifikat besitzen.

  • Rufen Sie den base64-codierten Zertifikatswert und den Fingerabdruck aus einer öffentlichen .cer X509-Zertifikatsdatei mit Windows PowerShell ab.

  • Laden Sie das Zertifikat über die App-Manifestdatei hoch. Sie können das makecert.exe tool, das in der .NET Framework Toolsenthalten ist, verwenden, um ein selbst ausgestelltes Zertifikat zu erzeugen.

Um ein selbst ausgestelltes Zertifikat mit dem Tool makecert.exe zu erzeugen gehen Sie wie folgt vor:

  1. Geben Sie in der Befehlszeile Folgendes ein und führen Sie Folgendes aus:

    makecert -r -pe -n "CN=MyCompanyName MyAppName Cert" -b 12/15/2014 -e 12/15/2016 -ss my -len 2048

  2. Öffnen Sie das Snap-In Zertifikate Verwaltungskonsole und verbinden Sie sich mit Ihrem Benutzerkonto.

  3. Suchen Sie das neue Zertifikat im Ordner Personal und exportieren Sie es in eine base64-kodierte CER-Datei.

    Hinweis Stellen Sie sicher, dass die Schlüssellänge mindestens 2048 beträgt, wenn Sie das X.509-Zertifikat generieren. Kürzere Schlüssellängen werden nicht als gültige Schlüssel akzeptiert.

Um den base64-codierten cert Wert und den Fingerabdruck aus einer öffentlichen .cer X509-Zertifikatsdatei zu erhalten, gehen Sie wie folgt vor:

  1. Geben Sie in der Windows PowerShell-Eingabeaufforderung die folgenden Cmdlets ein und führen Sie sie aus:

    $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
    $cer.Import("mycer.cer")
    $bin = $cer.GetRawCertData()
    $base64Value = [System.Convert]::ToBase64String($bin)
    $bin = $cer.GetCertHash()
    $base64Thumbprint = [System.Convert]::ToBase64String($bin)
    $keyid = [System.Guid]::NewGuid().ToString()
    

    Hinweis Dieser Schritt zeigt die Verwendung von Windows PowerShell zum Abrufen der Eigenschaften eines x.509-Zertifikats. Andere Plattformen bieten ähnliche Werkzeuge, um die Eigenschaften von Zertifikaten abzurufen.

  2. Speichern Sie die Werte für $base64Thumbprint, $base64Value und $keyid, da Sie sie beim Hochladen des Zertifikats im nächsten Schritt benötigen.

Laden Sie das Zertifikat über die Manifestdatei hoch

  1. Melden Sie sich am Microsoft Azure-Verwaltungsportal an.

  2. Klicken Sie im linken Menü auf Active Directory und dann auf das gewünschte Verzeichnis.

  3. Klicken Sie im oberen Menü auf Anwendungen, und klicken Sie dann auf die Anwendung, die Sie konfigurieren möchten. Die Seite Schnellstart erscheint mit Einzelanmeldung und weiteren Konfigurationsinformationen.

  4. Klicken Sie auf Manifest verwalten in der Befehlsleiste und wählen Sie Manifest herunterladen.

  5. Öffnen Sie die heruntergeladene Datei zur Bearbeitung und ersetzen Sie die leere KeyCredentials -Eigenschaft durch die folgende JSON:

    "keyCredentials": [
    {
      "customKeyIdentifier": "$base64Thumbprint_from_above",
      "keyId": "$keyid_from_above",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value":  "$base64Value_from_above"
     }
    ], 
    

    Beispiel:

    "keyCredentials": [
     {
       "customKeyIdentifier": "ieF43L8nkyw/PEHjWvj+PkWebXk=",
       "keyId": "2d6d849e-3e9e-46cd-b5ed-0f9e30d078cc",
       "type": "AsymmetricX509Cert",
       "usage": "Verify",
       "value": "MIICWjCCAgSgAwIBA***omitted for brevity***qoD4dmgJqZmXDfFyQ"
     }
    ],
    

    Die Eigenschaft KeyCredentials ist eine Sammlung, die es ermöglicht, mehrere X.509-Zertifikate für Rollover-Szenarien hochzuladen oder Zertifikate für Kompromissszenarien zu löschen.

  6. Speichern Sie Ihre Änderungen und laden Sie die aktualisierte App-Manifestdatei hoch, indem Sie auf Manifest verwalten in der Befehlsleiste klicken, Manifest hochladenwählen, zu Ihrer aktualisierten Manifestdatei navigieren und diese dann auswählen.

© 2018 Microsoft