Überprüfen eines Exchange-Identitätstokens
Wichtig
Legacy-Exchange-Benutzeridentitätstoken und Rückruftoken werden im Oktober 2024 für alle Exchange Online Mandanten im Rahmen der Microsoft Secure Future Initiative deaktiviert, die Organisationen die Tools bietet, die für die Reaktion auf die aktuelle Bedrohungslandschaft erforderlich sind. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft. Weitere Informationen finden Sie in unserem Blogbeitrag zur Authentifizierung geschachtelter Apps und älteren Exchange-Token.
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 aufJWTfestgelegt.alg-Anspruch ist aufRS256festgelegt.x5t-Anspruch vorhanden ist.
Überprüfen Sie die Nutzlast, und überprüfen Sie folgendes:
amurl-Anspruch innerhalb vonappctxwird auf den Speicherort einer Manifestdatei für den autorisierten Tokensignaturschlüssel festgelegt. Der erwarteteamurlWert 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
nbfAnsprüchen undexpangegebenen Zeiten. Dernbf-Anspruch gibt die früheste Zeit an, zu der das Token als gültig betrachtet wird, und derexp-Anspruch gibt die Ablaufzeit für das Token an. Es wird empfohlen, dass Sie eine gewisse Abweichung der Systemuhreinstellungen zwischen Servern berücksichtigen. audclaim ist die erwartete URL für Ihr Add-In.version-Anspruch innerhalb des Anspruchsappctxist aufExIdTok.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 dem
amurlum eine bekannte Domäne (https://outlook.office365.com:443/autodiscover/metadata/json/1) handelt oder zu einer geospezifischen oder speziellen Cloud gehört (Office 365 URLs und IP-Adressbereiche).Wenn Ihr Add-In-Dienst über eine bereits vorhandene Konfiguration mit dem Mandanten des Benutzers verfügt, können Sie feststellen, ob dieser
amurlals 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.
Siehe auch
Office Add-ins
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für