Überprüfen eines Exchange-Identitätstokens

Artikel
04/11/2024

Wichtig

Legacy-Exchange-Token sind veraltet. Ab Oktober 2024 werden ältere Exchange-Benutzeridentitäts - und -Rückruftoken für Exchange Online-Mandanten deaktiviert. Die Zeitachse und Details finden Sie auf unserer Faq-Seite. Dies ist Teil der Secure Future Initiative von Microsoft, die Organisationen die Tools zur Verfügung stellt, die sie benötigen, um auf die aktuelle Bedrohungslandschaft zu reagieren. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft.

Ihr Outlook-Add-In kann Ihnen ein Exchange-Benutzeridentitätstoken senden, bevor Sie der Anforderung jedoch vertrauen, müssen Sie das Token überprüfen, um sicherzustellen, dass es von dem erwarteten Exchange-Server stammt. Exchange-Benutzeridentitätstoken sind JSON Web Token (JWT). Die erforderlichen Schritte zum Überprüfen eines JWT werden in RFC 7519 JSON Web Token (JWT) beschrieben.

Es wird empfohlen, einen aus vier Schritten bestehenden Vorgang zum Überprüfen des Identitätstokens und Abrufen der eindeutigen ID des Benutzers zu verwenden. Extrahieren Sie zunächst das JSON Web Token (JWT) aus einer base64-URL-codierten Zeichenfolge. Stellen Sie anschließend sicher, dass das Token wohlgeformt ist, dass es für Ihr Outlook-Add-In bestimmt und nicht abgelaufen ist und dass Sie eine gültige URL für das Dokument mit den Authentifizierungsmetadaten extrahieren können. Rufen Sie als Nächstes das Dokument mit den Authentifizierungsmetadaten vom Exchange-Server ab, und überprüfen Sie die an das Identitätstoken angefügte Signatur. Berechnen Sie schließlich einen eindeutigen Bezeichner für den Benutzer, indem Sie die Exchange-ID des Benutzers mit der URL des Authentifizierungsmetadatendokuments verketten.

Extrahieren des JSON Web Token

Das von getUserIdentityTokenAsync zurückgegebene Token ist eine codierte Zeichenfolgendarstellung des Tokens. In diesem Formula, RFC 7519 bestehen alle JWTs aus drei Teilen, die durch einen Punkt getrennt sind. Das Format ist wie folgt.

{header}.{payload}.{signature}

Der Header und die Nutzlast sollten base64-entschlüsselt sein, um eine JSON-Darstellung jedes Teils zu erhalten. Die Signatur sollte base64-entschlüsselt sein, um ein Bytearray mit der binären Signatur zu erhalten.

Weitere Informationen zu den Inhalten des Tokens finden Sie unter Innenleben des Exchange-Identitätstokens.

Nachdem Sie die drei Komponenten entschlüsselt haben, können Sie mit der Überprüfung der Tokeninhalte fortfahren.

Überprüfen der Tokeninhalte

Um den Tokeninhalt zu überprüfen, sollten Sie Folgendes überprüfen:

Überprüfen Sie den Header, und vergewissern Sie sich, dass:
- typ -Anspruch ist auf JWTfestgelegt.
- alg -Anspruch ist auf RS256festgelegt.
- x5t -Anspruch vorhanden ist.
Überprüfen Sie die Nutzlast, und überprüfen Sie folgendes:
- amurl -Anspruch innerhalb von appctx wird auf den Speicherort einer Manifestdatei für den autorisierten Tokensignaturschlüssel festgelegt. Der erwartete amurl Wert für Microsoft 365 ist https://outlook.office365.com:443/autodiscover/metadata/json/1beispielsweise . Weitere Informationen finden Sie im nächsten Abschnitt Überprüfen der Domäne .
- Die aktuelle Zeit liegt zwischen den in den nbf Ansprüchen und exp angegebenen Zeiten. Der nbf-Anspruch gibt die früheste Zeit an, zu der das Token als gültig betrachtet wird, und der exp-Anspruch gibt die Ablaufzeit für das Token an. Es wird empfohlen, dass Sie eine gewisse Abweichung der Systemuhreinstellungen zwischen Servern berücksichtigen.
- aud claim ist die erwartete URL für Ihr Add-In.
- version -Anspruch innerhalb des Anspruchs appctx ist auf ExIdTok.V1festgelegt.

Überprüfen der Domäne

Beim Implementieren der im vorherigen Abschnitt beschriebenen Überprüfungslogik müssen Sie auch verlangen, dass die Domäne des amurl Anspruchs der AutoErmittlungsdomäne für den Benutzer entspricht. Dazu müssen Sie autoErmittlung für Exchange verwenden oder implementieren.

Vergewissern Sie sich für Exchange Online, dass es sich bei um amurl eine bekannte Domäne (https://outlook.office365.com:443/autodiscover/metadata/json/1) handelt oder zu einer geospezifischen oder spezialisierten Cloud (Office 365-URLs und IP-Adressbereiche) gehört.
Wenn Ihr Add-In-Dienst über eine bereits vorhandene Konfiguration mit dem Mandanten des Benutzers verfügt, können Sie feststellen, ob dieser amurl als vertrauenswürdig eingestuft wird.
Verwenden Sie für eine Exchange-Hybridbereitstellung die OAuth-basierte AutoErmittlung, um die für den Benutzer erwartete Domäne zu überprüfen. Obwohl sich der Benutzer im Rahmen des AutoErmittlungsflows authentifizieren muss, sollte Ihr Add-In niemals die Anmeldeinformationen des Benutzers erfassen und die Standardauthentifizierung durchführen.

Wenn Ihr Add-In mit amurl einer dieser Optionen nicht überprüfen kann, können Sie das Add-In ordnungsgemäß herunterfahren lassen, indem Sie eine entsprechende Benachrichtigung an den Benutzer erhalten, wenn die Authentifizierung für den Workflow des Add-Ins erforderlich ist.

Überprüfen der Identitätstokensignatur

Nachdem Sie überprüft haben, dass das JWT die erforderlichen Ansprüche enthält, können Sie mit dem Überprüfung der Tokensignatur fortfahren.

Abrufen des öffentlichen Signaturschlüssels

Der erste Schritt besteht darin, den öffentlichen Schlüssel abzurufen, der dem Zertifikat entspricht, das der Exchange-Serer zum Signieren des Tokens verwendet hat. Der Schlüssel befindet sich im Dokument mit den Authentifizierungsmetadaten. Dieses Dokument ist eine JSON-Datei, die an der im amurl-Anspruch angegebenen URL gehostet wird.

Das Dokument mit den Authentifizierungsmetadaten verwendet das folgende Format.

{
    "id": "_70b34511-d105-4e2b-9675-39f53305bb01",
    "version": "1.0",
    "name": "Exchange",
    "realm": "*",
    "serviceName": "00000002-0000-0ff1-ce00-000000000000",
    "issuer": "00000002-0000-0ff1-ce00-000000000000@*",
    "allowedAudiences": [
        "00000002-0000-0ff1-ce00-000000000000@*"
    ],
    "keys": [
        {
            "usage": "signing",
            "keyinfo": {
                "x5t": "enh9BJrVPU5ijV1qjZjV-fL2bco"
            },
            "keyvalue": {
                "type": "x509Certificate",
                "value": "MIIHNTCC..."
            }
        }
    ],
    "endpoints": [
        {
            "location": "https://by2pr06mb2229.namprd06.prod.outlook.com:444/autodiscover/metadata/json/1",
            "protocol": "OAuth2",
            "usage": "metadata"
        }
    ]
}

Die verfügbaren Signaturschlüssel befinden sich im keys-Array. Wählen Sie den richtigen Schlüssel aus, indem Sie sicherstellen, dass der x5t-Wert in der keyinfo-Eigenschaft dem x5t-Wert in der Kopfzeile des Tokens entspricht. Der öffentliche Schlüssel ist in der Eigenschaft value in der Eigenschaft keyvalue als base64-verschlüsseltes Bytearray gespeichert.

Überprüfen Sie die Signatur, sobald Sie den richtigen öffentlichen Schlüssel gefunden haben. Die signierten Daten sind die ersten beiden Teile des codierten Tokens, getrennt durch einen Punkt:

{header}.{payload}

Berechnen der eindeutigen ID für ein Exchange-Konto

Erstellen Sie einen eindeutigen Bezeichner für ein Exchange-Konto, indem Sie die Dokument-URL für die Authentifizierungsmetadaten mit dem Exchange-Bezeichner für das Konto verketten. Wenn Sie über diesen eindeutigen Bezeichner verfügen, verwenden Sie ihn, um ein System für einmaliges Anmelden (Single Sign-On, SSO) für Ihren Outlook-Add-In-Webdienst zu erstellen. Ausführliche Informationen zur Verwendung des eindeutigen Bezeichners für SSO finden Sie unter Authentifizieren eines Benutzers mit einem Identitätstoken für Exchange.

Verwenden einer Bibliothek zum Überprüfen des Tokens

Es gibt eine Reihe von Bibliotheken, die eine allgemeine JWT-Analyse und -Überprüfung durchführen können. Microsoft stellt die System.IdentityModel.Tokens.Jwt Bibliothek bereit, die zum Überprüfen von Exchange-Benutzeridentitätstoken verwendet werden kann.

Wichtig

Die verwaltete Api für Exchange-Webdienste wird nicht mehr empfohlen, da die Microsoft.Exchange.WebServices.Auth.dll, obwohl sie noch verfügbar ist, veraltet ist und auf nicht unterstützten Bibliotheken wie Microsoft.IdentityModel.Extensions.dll basiert.

System.IdentityModel.Tokens.Jwt

Die System.IdentityModels.Tokens.Jwt-Bibliothek kann das Token analysieren und auch die Überprüfung durchführen, Sie müssen aber den appctx-Anspruch selbst analysieren und den öffentlichen Signaturschlüssel abrufen.

// Load the encoded token
string encodedToken = "...";
JwtSecurityToken jwt = new JwtSecurityToken(encodedToken);

// Parse the appctx claim to get the auth metadata url
string authMetadataUrl = string.Empty;
var appctx = jwt.Claims.FirstOrDefault(claim => claim.Type == "appctx");
if (appctx != null)
{
    var AppContext = JsonConvert.DeserializeObject<ExchangeAppContext>(appctx.Value);

    // Token version check
    if (string.Compare(AppContext.Version, "ExIdTok.V1", StringComparison.InvariantCulture) != 0) {
        // Fail validation
    }

    authMetadataUrl = AppContext.MetadataUrl;
}

// Use System.IdentityModel.Tokens.Jwt library to validate standard parts
JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
TokenValidationParameters tvp = new TokenValidationParameters();

tvp.ValidateIssuer = false;
tvp.ValidateAudience = true;
tvp.ValidAudience = "{URL to add-in}";
tvp.ValidateIssuerSigningKey = true;
// GetSigningKeys downloads the auth metadata doc and
// returns a List<SecurityKey>
tvp.IssuerSigningKeys = GetSigningKeys(authMetadataUrl);
tvp.ValidateLifetime = true;

try
{
    var claimsPrincipal = tokenHandler.ValidateToken(encodedToken, tvp, out SecurityToken validatedToken);

    // If no exception, all standard checks passed
}
catch (SecurityTokenValidationException ex)
{
    // Validation failed
}

Die ExchangeAppContext-Klasse ist wie folgt definiert:

using Newtonsoft.Json;

/// <summary>
/// Representation of the appctx claim in an Exchange user identity token.
/// </summary>
public class ExchangeAppContext
{
    /// <summary>
    /// The Exchange identifier for the user
    /// </summary>
    [JsonProperty("msexchuid")]
    public string ExchangeUid { get; set; }

    /// <summary>
    /// The token version
    /// </summary>
    public string Version { get; set; }

    /// <summary>
    /// The URL to download authentication metadata
    /// </summary>
    [JsonProperty("amurl")]
    public string MetadataUrl { get; set; }
}

Ein Beispiel, das diese Bibliothek zum Überprüfen von Exchange-Token verwendet und über eine Implementierung von GetSigningKeys verfügt, finden Sie unter Outlook-Add-In-Token-Viewer.

Freigeben über