Authentifizieren eines Benutzers mit einem Single Sign-On-Token in einem Outlook-Add-In

Single Sign-On-Zugriffstoken bieten Ihrem Add-In eine nahtlose Möglichkeit, Zugriffstoken zum Aufrufen der Microsoft Graph-API zu authentifizieren und abzurufen. Erwägen Sie die Verwendung von SSO-Zugriffstoken, wenn für Ihr Add-In Folgendes gilt:

  • Es wird hauptsächlich von Office 365-Benutzern verwendet
  • Es benötigt Zugriff auf:
    • Microsoft-Dienste, die im Rahmen von Microsoft Graph bereitgestellt werden
    • Ein Nicht-Microsoft-Dienst, den Sie steuern

Die SSO-Authentifizierungsmethode verwendet den von Azure Active Directory bereitgestellten OAuth2-Im-Auftrag-von-Ablauf. Sie erfordert, dass sich das Add-In im Anwendungsregistrierungsportal registriert und alle erforderlichen Microsoft Graph-Bereiche im Manifest angibt.

Mit dieser Methode kann Ihr Add-In ein Zugriffstoken abrufen, das auf Ihre Server-Back-End-API ausgelegt ist. Das Add-In verwendet dieses als Bearertoken in der Authorization-Kopfzeile, um einen Aufruf wieder bei Ihrer API zu authentifizieren. An diesem Punkt kann Ihr Server Folgendes:

  • Den Im-Auftrag-von-Ablauf abschließen, um ein Zugriffstoken zu erhalten, das auf die Microsoft Graph-API ausgelegt ist
  • Die Identitätsinformationen im Token verwenden, um die Identität des Benutzers zu ermitteln und bei Ihren eigenen Back-End-Diensten zu authentifizieren

Registrieren Ihres Add-Ins

Um am Azure-OAuth-Fluss teilzunehmen, muss das Add-In im Anwendungsregistrierungsportal registriert sein. Das Add-In muss zumindest eine Web-API registrieren, damit das Add-In einen SSO-Token erhält. Wenn das Add-In Zugriff auf die Microsoft Graph-API benötigt, muss das Add-In auch eine Web-App registrieren.

Der Registrierungsvorgang beginnt mit der Erstellung einer Anwendung im Portal. Dadurch wird eine Anwendungs-ID generiert. Nachdem die App erstellt wurde, werden Komponenten als Plattformen hinzugefügt.

Registrieren einer Web-API

Die Web-API-Komponente des Add-Ins ist der Endpunkt, der den SSO-Token erhält.

  1. Wählen Sie in den Details der Anwendung im Portal die Schaltfläche Plattform hinzufügen aus.
  2. Wählen Sie Web-API aus.
  3. Geben Sie die folgenden Details ein:
    • Application-ID-URI: Verwenden Sie das Format api://{add-in server host}/{application id}
    • Durch diese API definierte Bereiche: Standardwert beibehalten
    • Vorautorisierte Anwendungen: Fügen Sie die Anwendungs-ID für Office hinzu: d3590ed6-52b3-4102-aeff-aad2292ab01c, mit dem Bereich api://{add-in server host}/{application id}/access_as_user

Bei einem Add-In, das beispielsweise bei https://addin.contoso.com mit der Anwendungs-ID 5661fed9-f33d-4e95-b6cf-624a34a2f51d gehostet wird, sieht der Abschnitt Web-API Teil der Anwendungsregistrierung in etwa folgendermaßen aus.

Ein Screenshot des Abschnitts „Web-API“ einer Anwendungsregistrierung für ein Add-In, das Single Sign-On verwendet

Registrieren einer Web-App

Mithilfe der Web-App-Komponente des Add-Ins kann Ihr Server-Back-End den Im-Auftrag-von-Ablauf abschließen, um den ersten Token gegen einen Zugriffstoken auszutauschen, der Zugriff auf die Microsoft Graph-API erlaubt.

  1. Wählen Sie in den Details der Anwendung im Portal die Schaltfläche Plattform hinzufügen aus.
  2. Wählen Sie Web aus.
  3. Geben Sie die folgenden Details ein:
    • Umleitungs-URLs: Geben Sie die Basis-URL des Add-Ins ein.

Bei dem oben beschriebenen Add-In beispielsweise, das bei https://addin.contoso.com gehostet wird, sieht der Abschnitt Web der Anwendungsregistrierung in etwa folgendermaßen aus.

Ein Screenshot des Abschnitts „Web“ einer Anwendungsregistrierung für ein Add-In, das Single Sign-On verwendet

Generieren eines Anwendungskennworts

Um einen Microsoft Graph-Token anzufordern, muss die Web-App-Registrierung in den client_secret-Parameter der Tokenanforderung einen gemeinsamen geheimen Schlüssel einschließen.

  1. Wählen Sie die Schaltfläche Neues Kennwort generieren unter Anwendungsgeheimnisse.
  2. Kopieren Sie das generierte Kennwort, wenn es angezeigt wird, und speichern Sie es an einem sicheren Ort.

Konfigurieren erforderlicher Microsoft Graph-Berechtigungen

Als letzter Schritt im Registrierungsvorgang werden die erforderlichen Berechtigungen für Microsoft Graph konfiguriert. Diese Berechtigungen sollten als delegierte Berechtigungen hinzugefügt werden, NICHT als Anwendungsberechtigungen.

Beachten Sie die folgenden Richtlinien:

  • Die Office-JS-API setzt voraus, dass Sie sowohl User.Read als auch profile zu den delegierten Berechtigungen hinzufügen.
  • Wenn Sie eine OAuth-Bibliothek zum Verarbeiten der Tokenanforderungen von Ihrem Back-End verwenden, fordert sie (zusätzlich zu denen, die Sie speziell anfordern) möglicherweise weitere Bereiche an, die auch hier aufgelistet werden sollten. So fügt z. B. die Microsoft Authentication Library immer openid und offline_access zu Tokenanforderungen hinzu.

Wenn Ihr Add-In z. B. Lesezugriff auf die OneDrive-Dateien des Benutzers erfordert, sieht der Abschnitt Microsoft Graph-Berechtigungen in etwa folgendermaßen aus.

Ein Screenshot des Abschnitts „Microsoft Graph-Berechtigungen“ einer Anwendungsregistrierung für ein Add-In, das Single Sign-On verwendet

Wenn ein Add-In, das SSO verwendet, aus dem Office Store erworben wird, wird der Benutzer auf der Store-Benutzeroberfläche aufgefordert, den angeforderten Graph-Berechtigungen zuzustimmen. Wird das Add-In allerdings zum Testen quergeladen, wird die Store-Benutzeroberfläche mit der Zustimmung umgangen. Damit das Add-In Token erhält, müssen Sie Ihre Zustimmung geben.

Sie haben zwei Möglichkeiten, Ihre Zustimmung zu geben. Sie können ein Administratorkonto verwenden und einmal für alle Benutzer in Ihrer Office 365-Organisation zustimmen, oder Sie können jedes beliebige Konto verwenden, um nur für diesen Benutzer zuzustimmen.

Wenn Sie Zugriff auf ein Mandantenadministratorkonto haben, können Sie mit dieser Methode Ihre Zustimmung für alle Benutzer in Ihrer Organisation geben. Das kann praktisch sein, wenn Sie mehrere Entwickler haben, die Ihr Add-In entwickeln und testen müssen.

  1. Navigieren Sie zu https://login.microsoftonline.com/common/adminconsent?client_id={application_ID}&state=12345, wobei {application_ID} die Anwendungs-ID ist, die in der Registrierung Ihrer App angezeigt wird.
  2. Melden Sie sich mit Ihrem Administratorkonto an.
  3. Überprüfen Sie die Berechtigungen, und klicken Sie auf Annehmen.

Der Browser versucht, Sie wieder zu Ihrer App umzuleiten, die möglicherweise nicht ausgeführt wird. Nachdem Sie auf Annehmen geklickt haben, wird möglicherweise die Fehlermeldung angezeigt, dass diese Website nicht erreicht werden kann. Das ist in Ordnung. Die Zustimmung wurde dennoch erfasst.

Wenn Sie keinen Zugriff auf ein Mandantenadministratorkonto haben oder Sie Ihre Zustimmung nur für ein paar Benutzer geben möchten, können Sie mithilfe dieser Methode Ihre Zustimmung für einen einzelnen Benutzer geben.

  1. Navigieren Sie zu https://login.microsoftonline.com/common/oauth2/authorize?client_id={application_ID}&state=12345&response_type=code, wobei {application_ID} die Anwendungs-ID ist, die in der Registrierung Ihrer App angezeigt wird.
  2. Melden Sie sich mit Ihrem Konto an.
  3. Überprüfen Sie die Berechtigungen, und klicken Sie auf Annehmen.

Der Browser versucht, Sie wieder zu Ihrer App umzuleiten, die möglicherweise nicht ausgeführt wird. Nachdem Sie auf Annehmen geklickt haben, wird möglicherweise die Fehlermeldung angezeigt, dass diese Website nicht erreicht werden kann. Das ist in Ordnung. Die Zustimmung wurde dennoch erfasst.

Aktualisieren des Add-In-Manifests

Der nächste Schritt zum Aktivieren von SSO im Add-In besteht darin, ein WebApplicationInfo-Element in das VersionOverridesV1_1 VersionOverrides-Element einzufügen. Dieses Element enthält die folgenden untergeordneten Elemente:

  • Id: festgelegt auf die Anwendungs-ID, die Sie bei der Registrierung der App erhalten haben
  • Resource: festgelegt auf den Anwendungs-ID-URI, der im Abschnitt Web-API der App-Registrierung konfiguriert wurde
  • Scopes: enthält ein Scope-Element für jeden Microsoft Graph-Bereich, der vom Add-In benötigt wird

Bei dem Add-In, das in den vorherigen Beispielen genannt wurde, sieht das WebApplicationInfo-Element beispielsweise folgendermaßen aus.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">

  ...

  <WebApplicationInfo>
    <Id>5661fed9-f33d-4e95-b6cf-624a34a2f51d</Id>
    <Resource>api://addin.contoso.com/5661fed9-f33d-4e95-b6cf-624a34a2f51d</Resource>
    <Scopes>
      <Scope>user.read</Scope>
      <Scope>files.read</Scope>
    </Scopes>
  </WebApplicationInfo>
</VersionOverrides>

Abrufen des SSO-Tokens

Das Add-In erhält ein Token für einmaliges Anmelden, indem es Office.context.auth.getAccessTokenAsync aufruft.

Office.context.auth.getAccessTokenAsync(function (result) {
    if (result.status === "succeeded") {
        // No need to prompt user, use this token to call Web API
        var ssoToken = result.value;
        ...
    } else {
        if (result.error.code === 13003) {
            // SSO is not supported for this user, fallback
            // on another authentication method
        } else {
            // Handle error
        }
    }
});

Das Add-In schließt den Token in die Authorization-Kopfzeile ein, wenn es eine Anforderung an die Web-API zurücksendet.

$.ajax({
    type: "POST",
    url: "/api/DoSomething",
    headers: {
        "Authorization": "Bearer " + ssoToken
    },
    data: { /* some JSON payload */ },
    contentType: "application/json; charset=utf-8"
}).done(function (data) {
    // Handle success
}).fail(function (error) {
    // Handle error
}).always(function () {
    // Cleanup
});

Verwenden des SSO-Tokens im Back-End

Nachdem die Web-API den Zugriffstoken erhalten hat, muss sie ihn vor Verwendung überprüfen. Der Token ist ein JSON-Webtoken (JWT), was bedeutet, dass die Überprüfung genauso wie die Tokenüberprüfung in den meisten standardmäßigen OAuth-Flüssen erfolgt. Es gibt eine Reihe von Bibliotheken, welche die JWT-Überprüfung verarbeiten können, aber zu den grundlegenden Schritten zählen folgende:

  • Überprüfen, ob der Token wohlgeformt ist
  • Überprüfen, ob der Token von der vorgesehenen Autorität ausgestellt wurde
  • Überprüfen, ob der Token auf die Web-API ausgerichtet ist

Beachten Sie bei der Überprüfung des Tokens die folgenden Richtlinien:

  • Gültige SSO-Token werden von der Azure-Autorität, https://login.microsoftonline.com, ausgestellt. Der iss-Anspruch im Token sollte mit diesem Wert beginnen.
  • Der aud-Parameter des Tokens wird auf die Anwendungs-ID der Registrierung des Add-Ins festgelegt.
  • Der scp-Parameter des Tokens wird auf access_as_user festgelegt.

Verwenden des SSO-Tokens als eine Identität

Wenn Ihr Add-In die Identität des Benutzers überprüfen muss, enthält der SSO-Token Informationen, mit denen die Identität ermittelt werden kann. Die folgenden Ansprüche im Token beziehen sich auf die Identität.

  • name: der Anzeigename des Benutzers.
  • preferred_username: der Anmeldename des Benutzers.
  • oid: eine GUID, welche die ID des Benutzers im Azure Active Directory darstellt.
  • tid: eine GUID, welche die ID der Organisation des Benutzers im Azure Active Directory darstellt.

Da sich die Werte name und preferred_username ändern könnten, wird empfohlen, die Werte oid und tid zu verwenden, um die Identität mit dem Autorisierungsdienst Ihres Back-Ends zu korrelieren.

Wenn Ihr Dienst z. B. diese Werte wie {oid-value}@{tid-value} zusammen formatieren konnte, speichern Sie dies in Ihrer internen Benutzerdatenbank als Wert im Datensatz des Benutzers. Bei nachfolgenden Anforderungen könnte der Benutzer mit demselben Wert abgerufen werden, und der Zugriff auf bestimmte Ressourcen könnte basierend auf Ihren vorhandenen Zugriffskontrollmechanismen ermittelt werden.

Wichtig

Wenn Sie den SSO-Token als Identität verwenden, sollten Sie auch den Exchange-Identitätstoken als eine andere Identität verwenden. Benutzer Ihres Add-Ins verwenden möglicherweise mehrere Clients, von denen einige möglicherweise keine SSO-Token unterstützen. Wenn Sie den Exchange-Identitätstoken als eine Alternative verwenden, müssen diese Benutzer nicht mehrmals zur Eingabe von Anmeldeinformationen aufgefordert werden. Weitere Informationen finden Sie unter .

Abzurufen eines Microsoft Graph-Tokens mithilfe eines SSO-Tokens

Um auf die Microsoft Graph-API zuzugreifen, sendet das Add-In an den Azure Active Directory v2.0-Token-Endpunkt mithilfe des Im-Auftrag-von-Ablaufs eine Dienst-zu-Dienst-Anforderung unter Verwendung eines gemeinsamen geheimen Schlüssels.

Die Antwort enthält eine JSON-Nutzlast, wobei der Microsoft Graph-Token in der access_token-Eigenschaft bereitgestellt wird. Dieser Token wird in der Authorization-Kopfzeile verwendet, wenn Aufrufe an die Microsoft Graph-API durchgeführt werden.

Ressourcen

Ein Beispiel-Add-In, das mit dem SSO-Token auf die Microsoft Graph-API zugreift, finden Sie unter AttachmentsDemo-Beispiel-Add-In.