Einrichten einer externen Anmeldung per Microsoft-Konto mit ASP.NET Core

Von Valeriy Novytskyy und Rick Anderson

Dieses Beispiel zeigt Ihnen, wie Sie es Benutzer*innen ermöglichen, sich mit ihrem Geschäfts-, Schul- oder Unikonto oder ihrem persönlichen Microsoft-Konto anzumelden. Dazu verwenden Sie das ASP.NET Core 6.0-Projekt, das Sie auf der vorherigen Seite erstellt haben.

Erstellen der App im Microsoft-Entwicklerportal

Wenn Sie noch kein Microsoft-Konto besitzen, wählen Sie Ein Konto erstellen aus. Nach der Anmeldung werden Sie zur Seite App-Registrierungen umgeleitet:

  • Wählen Sie Neue Registrierung aus.
  • Geben Sie einen Namen ein.
  • Wählen Sie eine der Optionen für Unterstützte Kontotypen.
    • Das Paket MicrosoftAccount unterstützt standardmäßig App-Registrierungen, die mit den Optionen „Konten in einem beliebigen Organisationsverzeichnis“ oder „Konten in einem beliebigen Organisationsverzeichnis und Microsoft-Konten“ erstellt wurden.
    • Wenn Sie andere Optionen verwenden möchten, legen Sie die Member AuthorizationEndpoint und TokenEndpoint von MicrosoftAccountOptions, die zum Initialisieren der Microsoft-Kontoauthentifizierung verwendet werden, auf die URLs fest, die auf der Seite Endpunkte der App-Registrierung angezeigt werden, nachdem diese erstellt wurde (verfügbar durch Klicken auf die Endpunkte auf der Seite Übersicht).
  • Geben Sie unter Umleitungs-URI Ihre Entwicklungs-URL mit angefügtem /signin-microsoft ein. Beispiel: https://localhost:5001/signin-microsoft. Das später in diesem Beispiel konfigurierte Microsoft-Authentifizierungsschema verarbeitet automatisch Anforderungen an der /signin-microsoft-Route, um den OAuth-Flow zu implementieren.
  • Wählen Sie Registrieren aus.

Erstellen eines geheimen Clientschlüssels

  • Wählen Sie im linken Bereich Zertifikate und Geheimnisse aus.
  • Wählen Sie unter Geheime Clientschlüssel die Option Neuer geheimer Clientschlüssel aus.
    • Fügen Sie eine Beschreibung für den geheimen Clientschlüssel hinzu.
    • Wählen Sie die Schaltfläche Hinzufügen aus.
  • Kopieren Sie unter Geheime Clientschlüssel den Wert des geheimen Clientschlüssels.

Das URI-Segment /signin-microsoft ist als Standardrückruf des Microsoft-Authentifizierungsanbieters festgelegt. Sie können den Standardrückruf-URI beim Konfigurieren der Middleware für die Microsoft-Authentifizierung mithilfe der geerbten RemoteAuthenticationOptions.CallbackPath-Eigenschaft der MicrosoftAccountOptions-Klasse ändern.

Speichern der Microsoft-Client-ID und des Geheimnisses

Speichern Sie vertrauliche Einstellungen, wie z. B. die Microsoft-Anwendungs-ID (Client), die Sie auf der Seite Übersicht der App-Registrierung finden, und den geheimen Clientschlüssel, den Sie auf der Seite Zertifikate und Geheimnisse erstellt haben, mit dem Geheimnis-Manager. Gehen Sie für dieses Beispiel wie folgt vor:

  1. Initialisieren Sie das Projekt für den Geheimnisspeicher gemäß den Anweisungen unter Aktivieren des Geheimnisspeichers.

  2. Speichern Sie die vertraulichen Einstellungen im lokalen Geheimnisspeicher mit den geheimen Schlüsseln Authentication:Microsoft:ClientId und Authentication:Microsoft:ClientSecret:

    dotnet user-secrets set "Authentication:Microsoft:ClientId" "<client-id>"
    dotnet user-secrets set "Authentication:Microsoft:ClientSecret" "<client-secret>"
    

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen. Der doppelte Unterstrich __:

  • wird auf allen Plattformen unterstützt. Das Trennzeichen : wird beispielsweise nicht von Bash unterstützt, __ hingegen schon.
  • automatisch durch : ersetzt.

Konfigurieren der Microsoft-Kontoauthentifizierung

Fügen Sie den Authentifizierungsdienst zu Program hinzu:

var builder = WebApplication.CreateBuilder(args);
var services = builder.Services;
var configuration = builder.Configuration;

services.AddAuthentication().AddMicrosoftAccount(microsoftOptions =>
    {
        microsoftOptions.ClientId = configuration["Authentication:Microsoft:ClientId"];
        microsoftOptions.ClientSecret = configuration["Authentication:Microsoft:ClientSecret"];
    });

Die AddAuthentication(IServiceCollection, String)-Überladung legt die DefaultScheme-Eigenschaft fest. Die AddAuthentication(IServiceCollection, Action<AuthenticationOptions>)-Überladung ermöglicht das Konfigurieren von Authentifizierungsoptionen, mit deren Hilfe Standardauthentifizierungsschemas für verschiedene Zwecke eingerichtet werden können. Durch nachfolgende Aufrufe von AddAuthentication werden zuvor konfigurierte AuthenticationOptions-Eigenschaften überschrieben.

AuthenticationBuilder-Erweiterungsmethoden, die einen Authentifizierungshandler registrieren, können pro Authentifizierungsschema nur einmal aufgerufen werden. Es gibt Überladungen, die das Konfigurieren der Schemaeigenschaften, des Schemanamens und des Anzeigenamens ermöglichen.

Weitere Informationen zu den Konfigurationsoptionen, die von der Microsoft-Kontoauthentifizierung unterstützt werden, finden Sie in der Referenz zur MicrosoftAccountOptions-API. Dies kann verwendet werden, um verschiedene Informationen über den Benutzer anzufordern.

Anmeldung mit einem Microsoft-Konto

  • Führen Sie die App aus, und wählen Sie Anmelden aus. Es wird eine Option zur Anmeldung über Microsoft angezeigt.
  • Wählen Sie diese Option aus, um sich über Microsoft anzumelden. Sie werden zur Authentifizierung an Microsoft umgeleitet. Nachdem Sie sich mit Ihrem Microsoft-Konto angemeldet haben, werden Sie aufgefordert, der App Zugriff auf Ihre Daten zu gewähren:
  • Wählen Sie Ja aus. Sie werden wieder an die Website umgeleitet, auf der Sie Ihre E-Mail-Adresse festlegen können.

Sie sind jetzt mit Ihren Microsoft-Anmeldeinformationen angemeldet.

Mehrere Authentifizierungsanbieter

Wenn die App mehrere Anbieter erfordert, verketten Sie die Erweiterungsmethoden für Anbieter nach AddAuthentication:

services.AddAuthentication()
    .AddMicrosoftAccount(microsoftOptions => { ... })
    .AddGoogle(googleOptions => { ... })
    .AddTwitter(twitterOptions => { ... })
    .AddFacebook(facebookOptions => { ... });

Weiterleiten von Anforderungsinformationen mit einem Proxy oder Lastenausgleich

Wenn die App hinter einem Proxyserver oder Lastenausgleich bereitgestellt wird, können einige der ursprünglichen Anforderungsinformationen im Anforderungsheader an die App weitergeleitet werden. Zu diesen Informationen gehören in der Regel das sichere Anforderungsschema (https), den Host und die Client-IP-Adresse. Apps lesen diese Anforderungsheader nicht automatisch, um die ursprünglichen Anforderungsinformationen zu ermitteln und zu verwenden.

Das Schema wird bei der Linkgenerierung verwendet, die den Authentifizierungsflow bei externen Anbietern betrifft. Der Verlust des sicheren Schemas (https) führt dazu, dass die App falsche unsichere Umleitungs-URLs generiert.

Verwenden Sie Middleware für weitergeleitete Header, um der App zur Anforderungsverarbeitung die Informationen der ursprünglichen Anforderung verfügbar zu machen.

Weitere Informationen finden Sie unter Konfigurieren von ASP.NET Core für die Arbeit mit Proxyservern und Lastenausgleichen.

Problembehandlung

  • Wenn der Microsoft-Kontoanbieter Sie an eine Fehlerseite für die Anmeldung umleitet, beachten Sie die Abfragezeichenfolgenparameter für Fehlertitel und -beschreibung direkt nach dem # (Hashtag) im URI.

    Obwohl die Fehlermeldung auf ein Problem mit der Microsoft-Authentifizierung hinzuweisen scheint, liegt die häufigste Ursache darin, dass Ihr Anwendungs-URI mit keinem der Umleitungs-URIs übereinstimmt, die für die Webplattform angegeben sind.

  • Wenn Identity nicht durch den Aufruf von services.AddIdentity in ConfigureServices konfiguriert ist, führt der Authentifizierungsversuch zu einer Ausnahme: ArgumentException: Die Option 'SignInScheme' muss angegeben werden. Die in diesem Beispiel verwendete Projektvorlage stellt sicher, dass dies geschehen ist.

  • Wenn die Standortdatenbank nicht durch Anwendung der anfänglichen Migration erstellt wurde, erhalten Sie die Fehlermeldung Fehler bei Datenbankvorgang während der Verarbeitung der Anforderung. Tippen Sie auf Migrationen anwenden, um die Datenbank zu erstellen, und aktualisieren Sie die Ansicht, um nach dem Fehler fortzufahren.

Nächste Schritte

  • In diesem Artikel wurde gezeigt, wie Sie eine Authentifizierung über Microsoft durchführen können. Führen Sie einen ähnlichen Ansatz für die Authentifizierung mit anderen Anbietern aufgeführt, auf die Vorgängerseite.
  • Sobald Sie Ihre Website in der Azure-Web-App veröffentlicht haben, erstellen Sie im Microsoft-Entwicklerportal einen neuen geheimen Clientschlüssel.
  • Legen Sie die Authentication:Microsoft:ClientId und Authentication:Microsoft:ClientSecret Anwendungseinstellungen im Azure-Portal. Das Konfigurationssystem ist zum Lesen von Schlüsseln aus Umgebungsvariablen eingerichtet.

Dieses Beispiel zeigt Ihnen, wie Sie es Benutzer*innen ermöglichen, sich mit ihrem Geschäfts-, Schul- oder Unikonto oder ihrem persönlichen Microsoft-Konto anzumelden. Dazu verwenden Sie das ASP.NET Core 3.0-Projekt, das Sie auf der vorherigen Seite erstellt haben.

Erstellen der App im Microsoft-Entwicklerportal

Wenn Sie noch kein Microsoft-Konto besitzen, wählen Sie Ein Konto erstellen aus. Nach der Anmeldung werden Sie zur Seite App-Registrierungen umgeleitet:

  • Wählen Sie Neue Registrierung aus.
  • Geben Sie einen Namen ein.
  • Wählen Sie eine der Optionen für Unterstützte Kontotypen.
    • Das Paket MicrosoftAccount unterstützt standardmäßig App-Registrierungen, die mit den Optionen „Konten in einem beliebigen Organisationsverzeichnis“ oder „Konten in einem beliebigen Organisationsverzeichnis und Microsoft-Konten“ erstellt wurden.
    • Wenn Sie andere Optionen verwenden möchten, legen Sie die Member AuthorizationEndpoint und TokenEndpoint von MicrosoftAccountOptions, die zum Initialisieren der Microsoft-Kontoauthentifizierung verwendet werden, auf die URLs fest, die auf der Seite Endpunkte der App-Registrierung angezeigt werden, nachdem diese erstellt wurde (verfügbar durch Klicken auf die Endpunkte auf der Seite Übersicht).
  • Geben Sie unter Umleitungs-URI Ihre Entwicklungs-URL mit angefügtem /signin-microsoft ein. Beispiel: https://localhost:5001/signin-microsoft. Das später in diesem Beispiel konfigurierte Microsoft-Authentifizierungsschema verarbeitet automatisch Anforderungen an der /signin-microsoft-Route, um den OAuth-Flow zu implementieren.
  • Wählen Sie Registrieren aus.

Erstellen eines geheimen Clientschlüssels

  • Wählen Sie im linken Bereich Zertifikate und Geheimnisse aus.
  • Wählen Sie unter Geheime Clientschlüssel die Option Neuer geheimer Clientschlüssel aus.
    • Fügen Sie eine Beschreibung für den geheimen Clientschlüssel hinzu.
    • Wählen Sie die Schaltfläche Hinzufügen aus.
  • Kopieren Sie unter Geheime Clientschlüssel den Wert des geheimen Clientschlüssels.

Das URI-Segment /signin-microsoft ist als Standardrückruf des Microsoft-Authentifizierungsanbieters festgelegt. Sie können den Standardrückruf-URI beim Konfigurieren der Middleware für die Microsoft-Authentifizierung mithilfe der geerbten RemoteAuthenticationOptions.CallbackPath-Eigenschaft der MicrosoftAccountOptions-Klasse ändern.

Speichern der Microsoft-Client-ID und des Geheimnisses

Speichern Sie vertrauliche Einstellungen, wie z. B. die Microsoft-Anwendungs-ID (Client), die Sie auf der Seite Übersicht der App-Registrierung finden, und den geheimen Clientschlüssel, den Sie auf der Seite Zertifikate und Geheimnisse erstellt haben, mit dem Geheimnis-Manager. Gehen Sie für dieses Beispiel wie folgt vor:

  1. Initialisieren Sie das Projekt für den Geheimnisspeicher gemäß den Anweisungen unter Aktivieren des Geheimnisspeichers.

  2. Speichern Sie die vertraulichen Einstellungen im lokalen Geheimnisspeicher mit den geheimen Schlüsseln Authentication:Microsoft:ClientId und Authentication:Microsoft:ClientSecret:

    dotnet user-secrets set "Authentication:Microsoft:ClientId" "<client-id>"
    dotnet user-secrets set "Authentication:Microsoft:ClientSecret" "<client-secret>"
    

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen. Der doppelte Unterstrich __:

  • wird auf allen Plattformen unterstützt. Das Trennzeichen : wird beispielsweise nicht von Bash unterstützt, __ hingegen schon.
  • automatisch durch : ersetzt.

Konfigurieren der Microsoft-Kontoauthentifizierung

Fügen Sie den Microsoft-Kontodienst zu Startup.ConfigureServices hinzu:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection")));
    services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddEntityFrameworkStores<ApplicationDbContext>();
    services.AddRazorPages();

    services.AddAuthentication().AddMicrosoftAccount(microsoftOptions =>
    {
        microsoftOptions.ClientId = Configuration["Authentication:Microsoft:ClientId"];
        microsoftOptions.ClientSecret = Configuration["Authentication:Microsoft:ClientSecret"];
    });
}

Die AddAuthentication(IServiceCollection, String)-Überladung legt die DefaultScheme-Eigenschaft fest. Die AddAuthentication(IServiceCollection, Action<AuthenticationOptions>)-Überladung ermöglicht das Konfigurieren von Authentifizierungsoptionen, mit deren Hilfe Standardauthentifizierungsschemas für verschiedene Zwecke eingerichtet werden können. Durch nachfolgende Aufrufe von AddAuthentication werden zuvor konfigurierte AuthenticationOptions-Eigenschaften überschrieben.

AuthenticationBuilder-Erweiterungsmethoden, die einen Authentifizierungshandler registrieren, können pro Authentifizierungsschema nur einmal aufgerufen werden. Es gibt Überladungen, die das Konfigurieren der Schemaeigenschaften, des Schemanamens und des Anzeigenamens ermöglichen.

Weitere Informationen zu den Konfigurationsoptionen, die von der Microsoft-Kontoauthentifizierung unterstützt werden, finden Sie in der Referenz zur MicrosoftAccountOptions-API. Dies kann verwendet werden, um verschiedene Informationen über den Benutzer anzufordern.

Anmeldung mit einem Microsoft-Konto

Führen Sie die App aus, und wählen Sie Anmelden aus. Es wird eine Option zur Anmeldung über Microsoft angezeigt. Wenn Sie Microsoft auswählen, werden Sie zur Authentifizierung an Microsoft umgeleitet. Nachdem Sie sich mit Ihrem Microsoft-Konto angemeldet haben, werden Sie aufgefordert, der App Zugriff auf Ihre Daten zu gewähren:

Tippen Sie auf Ja, um wieder an die Website umgeleitet zu werden, auf der Sie Ihre E-Mail-Adresse festlegen können.

Sie sind jetzt mit Ihren Microsoft-Anmeldeinformationen angemeldet.

Mehrere Authentifizierungsanbieter

Wenn die App mehrere Anbieter erfordert, verketten Sie die Erweiterungsmethoden für Anbieter nach AddAuthentication:

services.AddAuthentication()
    .AddMicrosoftAccount(microsoftOptions => { ... })
    .AddGoogle(googleOptions => { ... })
    .AddTwitter(twitterOptions => { ... })
    .AddFacebook(facebookOptions => { ... });

Weiterleiten von Anforderungsinformationen mit einem Proxy oder Lastenausgleich

Wenn die App hinter einem Proxyserver oder Lastenausgleich bereitgestellt wird, können einige der ursprünglichen Anforderungsinformationen im Anforderungsheader an die App weitergeleitet werden. Zu diesen Informationen gehören in der Regel das sichere Anforderungsschema (https), den Host und die Client-IP-Adresse. Apps lesen diese Anforderungsheader nicht automatisch, um die ursprünglichen Anforderungsinformationen zu ermitteln und zu verwenden.

Das Schema wird bei der Linkgenerierung verwendet, die den Authentifizierungsflow bei externen Anbietern betrifft. Der Verlust des sicheren Schemas (https) führt dazu, dass die App falsche unsichere Umleitungs-URLs generiert.

Verwenden Sie Middleware für weitergeleitete Header, um der App zur Anforderungsverarbeitung die Informationen der ursprünglichen Anforderung verfügbar zu machen.

Weitere Informationen finden Sie unter Konfigurieren von ASP.NET Core für die Arbeit mit Proxyservern und Lastenausgleichen.

Problembehandlung

  • Wenn der Microsoft-Kontoanbieter Sie an eine Fehlerseite für die Anmeldung umleitet, beachten Sie die Abfragezeichenfolgenparameter für Fehlertitel und -beschreibung direkt nach dem # (Hashtag) im URI.

    Obwohl die Fehlermeldung auf ein Problem mit der Microsoft-Authentifizierung hinzuweisen scheint, liegt die häufigste Ursache darin, dass Ihr Anwendungs-URI mit keinem der Umleitungs-URIs übereinstimmt, die für die Webplattform angegeben sind.

  • Wenn Identity nicht durch den Aufruf von services.AddIdentity in ConfigureServices konfiguriert ist, führt der Authentifizierungsversuch zu einer Ausnahme: ArgumentException: Die Option 'SignInScheme' muss angegeben werden. Die in diesem Beispiel verwendete Projektvorlage stellt sicher, dass dies geschehen ist.

  • Wenn die Standortdatenbank nicht durch Anwendung der anfänglichen Migration erstellt wurde, erhalten Sie die Fehlermeldung Fehler bei Datenbankvorgang während der Verarbeitung der Anforderung. Tippen Sie auf Migrationen anwenden, um die Datenbank zu erstellen, und aktualisieren Sie die Ansicht, um nach dem Fehler fortzufahren.

Nächste Schritte

  • In diesem Artikel wurde gezeigt, wie Sie eine Authentifizierung über Microsoft durchführen können. Führen Sie einen ähnlichen Ansatz für die Authentifizierung mit anderen Anbietern aufgeführt, auf die Vorgängerseite.
  • Sobald Sie Ihre Website in der Azure-Web-App veröffentlicht haben, erstellen Sie im Microsoft-Entwicklerportal einen neuen geheimen Clientschlüssel.
  • Legen Sie die Authentication:Microsoft:ClientId und Authentication:Microsoft:ClientSecret Anwendungseinstellungen im Azure-Portal. Das Konfigurationssystem ist zum Lesen von Schlüsseln aus Umgebungsvariablen eingerichtet.