Schnellstart: Aufrufen einer durch Microsoft Identity Platform geschützten ASP.NET-Web-APIQuickstart: Call an ASP.NET web API that's protected by Microsoft identity platform

In dieser Schnellstartanleitung laden Sie ein Codebeispiel herunter und führen es aus, das zeigt, wie Sie eine ASP.NET-Web-API schützen, indem Sie den Zugriff auf die Ressourcen ausschließlich auf autorisierte Konten beschränken.In this quickstart, you download and run a code sample that demonstrates how to protect an ASP.NET web API by restricting access to its resources to authorized accounts only. Das Beispiel unterstützt die Autorisierung von persönlichen Microsoft-Konten sowie Konten in einer beliebigen Azure AD-Organisation (Azure Active Directory).The sample supports authorization of personal Microsoft accounts and accounts in any Azure Active Directory (Azure AD) organization.

Der Artikel verwendet auch eine Windows Presentation Foundation (WPF)-App, um zu veranschaulichen, wie Sie ein Zugriffstoken für den Zugriff auf eine Web-API anfordern können.The article also uses a Windows Presentation Foundation (WPF) app to demonstrate how you can request an access token to access a web API.

VoraussetzungenPrerequisites

Klonen oder Herunterladen des BeispielsClone or download the sample

Zum Abrufen des Beispiels gibt es zwei Möglichkeiten:You can obtain the sample in either of two ways:

Registrieren Ihrer Web-APIRegister your web API

In diesem Abschnitt registrieren Sie Ihre Web-API im Azure-Portal in App-Registrierungen.In this section, you register your web API in App registrations in the Azure portal.

Auswählen Ihres Azure AD-MandantenChoose your Azure AD tenant

Wenn Sie Ihre Apps manuell registrieren möchten, wählen Sie den Azure Active Directory (Azure AD)-Mandanten aus, für den Sie Ihre Apps erstellen möchten.To register your apps manually, choose the Azure Active Directory (Azure AD) tenant where you want to create your apps.

  1. Melden Sie sich mit einem Geschäfts-, Schul- oder Unikonto oder mit einem persönlichen Microsoft-Konto beim Azure-Portal an.Sign in to the Azure portal with either a work or school account or a personal Microsoft account.
  2. Wenn sich Ihr Konto in mehreren Azure AD-Mandanten befindet, wählen Sie oben rechts Ihr Profil und anschließend Verzeichnis wechseln aus.If your account is present in more than one Azure AD tenant, select your profile at the upper right, and then select Switch directory.
  3. Ändern Sie Ihre Portalsitzung für den gewünschten Azure AD-Mandanten.Change your portal session to the Azure AD tenant you want to use.

Registrieren der TodoListService-AppRegister the TodoListService app

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im Menü am oberen Rand den Filter Verzeichnis + Abonnement  , um den Mandanten auszuwählen, für den Sie eine Anwendung registrieren möchten.

  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.Search for and select Azure Active Directory.

  4. Wählen Sie unter Verwalten Folgendes aus: App-Registrierungen > Neue Registrierung.Under Manage, select App registrations > New registration.

  5. Geben Sie unter Name einen Namen für Ihre Anwendung ein (beispielsweise AppModelv2-NativeClient-DotNet-TodoListService).Enter a Name for your application, for example AppModelv2-NativeClient-DotNet-TodoListService. Benutzern Ihrer App wird wahrscheinlich dieser Namen angezeigt. Sie können ihn später ändern.Users of your app might see this name, and you can change it later.

  6. Wählen Sie unter Unterstützte Kontotypen die Option Konten in einem beliebigen Organisationsverzeichnis aus.For Supported account types, select Accounts in any organizational directory.

  7. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.Select Register to create the application.

  8. Suchen Sie auf der Seite Übersicht für die App den Wert von Anwendungs-ID (Client) , und notieren Sie ihn zur späteren Verwendung.On the app Overview page, look for the Application (client) ID value, and then record it for later use. Sie benötigen diesen Wert, um die Visual Studio-Konfigurationsdatei für dieses Projekt (d. h. ClientId in der Datei TodoListService\Web.config) zu konfigurieren.You'll need it to configure the Visual Studio configuration file for this project (that is, ClientId in the TodoListService\Web.config file).

  9. Wählen Sie unter Verwalten die Optionen Eine API verfügbar machen > Bereich hinzufügen aus.Under Manage, select Expose an API > Add a scope. Übernehmen Sie den vorgeschlagenen Anwendungs-ID-URI (api://{clientId}), indem Sie Speichern und fortfahren auswählen. Geben Sie dann die folgenden Informationen ein:Accept the proposed Application ID URI (api://{clientId}) by selecting Save and continue, and then enter the following information:

    1. Geben Sie access_as_user als access_as_user ein.For Scope name, enter access_as_user.
    2. Stellen Sie sicher, dass unter Zum Einwilligen berechtigte Personen die Option Administratoren und Benutzer ausgewählt ist.For Who can consent, ensure that the Admins and users option is selected.
    3. Geben Sie Access TodoListService as a user im Feld Anzeigename der Administratorzustimmung ein.In the Admin consent display name box, enter Access TodoListService as a user.
    4. Geben Sie Accesses the TodoListService web API as a user im Feld Beschreibung der Administratorzustimmung ein.In the Admin consent description box, enter Accesses the TodoListService web API as a user.
    5. Geben Sie Access TodoListService as a user im Feld Anzeigename der Benutzereinwilligung ein.In the User consent display name box, enter Access TodoListService as a user.
    6. Geben Sie Accesses the TodoListService web API as a user im Feld Beschreibung der Benutzereinwilligung ein.In the User consent description box, enter Accesses the TodoListService web API as a user.
    7. Übernehmen Sie Aktiviert als Status.For State, keep Enabled.
  10. Wählen Sie Bereich hinzufügen aus.Select Add scope.

Konfigurieren des DienstprojektsConfigure the service project

Konfigurieren Sie das Dienstprojekt, damit es der registrierten Web-API entspricht. Gehen Sie dazu wie folgt vor:Configure the service project to match the registered web API by doing the following:

  1. Öffnen Sie die Projektmappe in Visual Studio, und öffnen Sie dann im Stammverzeichnis des TodoListService-Projekts die Datei Web.config.Open the solution in Visual Studio, and then open the Web.config file under the root of the TodoListService project.

  2. Ersetzen Sie den Wert des ida:ClientId-Parameters durch den Wert der Client-ID (Anwendungs-ID) der Anwendung, die Sie gerade im Portal App-Registrierungen registriert haben.Replace the value of the ida:ClientId parameter with the Client ID (Application ID) value from the application you just registered in the App registrations portal.

Hinzufügen des neuen Bereichs zur Datei „app.config“Add the new scope to the app.config file

Gehen Sie wie folgt vor, um den neuen Bereich zur Datei app.config des TodoListClient-Projekts hinzuzufügen:To add the new scope to the TodoListClient app.config file, do the following:

  1. Öffnen Sie im Stammordner des TodoListClient-Projekts die Datei app.config.In the TodoListClient project root folder, open the app.config file.

  2. Fügen Sie die Anwendungs-ID aus der Anwendung ein, die Sie soeben im TodoListServiceScope-Parameter für das TodoListService-Projekt registriert haben, und ersetzen Sie dabei die Zeichenfolge {Enter the Application ID of your TodoListService from the app registration portal}.Paste the Application ID from the application you just registered for your TodoListService project in the TodoListServiceScope parameter, replacing the {Enter the Application ID of your TodoListService from the app registration portal} string.

Hinweis

Stellen Sie sicher, das für die Anwendungs-ID das folgende Format verwendet wird: api://{TodoListService-Application-ID}/access_as_user (hierbei ist {TodoListService-Application-ID} die GUID, die für die Anwendungs-ID der TodoListService-App steht).Make sure that the Application ID uses the following format: api://{TodoListService-Application-ID}/access_as_user (where {TodoListService-Application-ID} is the GUID representing the Application ID for your TodoListService app).

Registrieren der TodoListClient-Client-AppRegister the TodoListClient client app

In diesem Abschnitt registrieren Sie im Azure-Portal unter App-Registrierungen die TodoListClient-App und konfigurieren dann den Code im TodoListClient-Projekt.In this section, you register your TodoListClient app in App registrations in the Azure portal, and then configure the code in the TodoListClient project. Wenn Client und Server als ein und dieselbe Anwendung betrachtet werden, können Sie die Anwendung wiederverwenden, die Sie in Schritt 2 registriert haben.If the client and server are considered the same application, you can reuse the application that's registered in step 2. Verwenden Sie dieselbe Anwendung, wenn sich Ihre Benutzer mit einem persönlichen Microsoft-Konto anmelden sollen.Use the same application if you want users to sign in with a Microsoft personal account.

Registrieren der AppRegister the app

Gehen Sie zum Registrieren der TodoListClient-App wie folgt vor:To register the TodoListClient app, do the following:

  1. Navigieren Sie in Microsoft Identity Platform für Entwickler zum Portal App-Registrierungen.Go to the Microsoft identity platform for developers App registrations portal.

  2. Wählen Sie Neue Registrierung aus.Select New registration.

  3. Wenn die Seite Anwendung registrieren geöffnet wird, geben Sie die Registrierungsinformationen Ihrer Anwendung ein:When the Register an application page opens, enter your application's registration information:

    1. Geben Sie im Abschnitt Name einen aussagekräftigen Anwendungsnamen ein, der den Benutzern der App angezeigt wird (z. B. NativeClient-DotNet-TodoListClient).In the Name section, enter a meaningful application name that will be displayed to users of the app (for example, NativeClient-DotNet-TodoListClient).
    2. Wählen Sie unter Unterstützte Kontotypen die Option Konten in einem beliebigen Organisationsverzeichnis aus.For Supported account types, select Accounts in any organizational directory.
    3. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.Select Register to create the application.

    Hinweis

    In der Datei app.config des TodoListClient-Projekts ist der Standardwert für ida:Tenant auf common festgelegt.In the TodoListClient project app.config file, the default value of ida:Tenant is set to common. Mögliche Werte sind:The possible values are:

    • common: Sie können sich mit einem Geschäfts-, Schul- oder Unikonto oder einem persönlichen Microsoft-Konto anmelden (aufgrund der Auswahl von Konten in einem beliebigen Organisationsverzeichnis in Schritt 3b).common: You can sign in by using a work or school account or a Microsoft personal account (because you selected Accounts in any organizational directory in step 3b).
    • organizations: Sie können sich mit einem Geschäfts-, Schul- oder Unikonto anmelden.organizations: You can sign in by using a work or school account.
    • consumers: Sie können sich nur mit einem persönlichen Microsoft-Konto anmelden.consumers: You can sign in only by using a Microsoft personal account.
  4. Wählen Sie auf der Seite Übersicht der App die Option Authentifizierung aus, und gehen Sie dann wie folgt vor:On the app Overview page, select Authentication, and then do the following:

    1. Wählen Sie unter Plattformkonfigurationen die Schaltfläche Plattform hinzufügen aus.Under Platform configurations, select the Add a platform button.
    2. Wählen Sie unter Mobilgerät- und Desktopanwendungen die Option Mobilgerät- und Desktopanwendungen aus.For Mobile and desktop applications, select Mobile and desktop applications.
    3. Aktivieren Sie unter Umleitungs-URIs das Kontrollkästchen https://login.microsoftonline.com/common/oauth2/nativeclient .For Redirect URIs, select the https://login.microsoftonline.com/common/oauth2/nativeclient check box.
    4. Wählen Sie Konfigurieren aus.Select Configure.
  5. Wählen Sie API-Berechtigungen aus, und gehen Sie dann wie folgt vor:Select API permissions, and then do the following:

    1. Wählen Sie die Schaltfläche Berechtigung hinzufügen.Select the Add a permission button.
    2. Wählen Sie die Registerkarte Meine APIs aus.Select the My APIs tab.
    3. Wählen Sie in der API-Liste den Namen AppModelv2-NativeClient-DotNet-TodoListService API bzw. den Namen aus, den Sie für die Web-API eingegeben haben.In the list of APIs, select AppModelv2-NativeClient-DotNet-TodoListService API or the name you entered for the web API.
    4. Aktivieren Sie das Kontrollkästchen für die Berechtigung access_as_user, falls es nicht bereits aktiviert ist.Select the access_as_user permission check box if it's not already selected. Verwenden Sie bei Bedarf das Suchfeld.Use the Search box if necessary.
    5. Wählen Sie die Schaltfläche Berechtigungen hinzufügen aus.Select the Add permissions button.

Konfigurieren des ProjektsConfigure your project

Gehen Sie zum Konfigurieren des TodoListClient-Projekts wie folgt vor:To configure your TodoListClient project, do the following:

  1. Kopieren Sie im Portal App-Registrierungen auf der Seite Übersicht den Wert von Anwendungs-ID (Client) .In the App registrations portal, on the Overview page, copy the value of the Application (client) ID.

  2. Öffnen Sie die Datei app.config, die sich im Stammordner des TodoListClient-Projekts befindet, und fügen Sie dann den Wert der Anwendungs-ID in den ida:ClientId-Parameter ein.From the TodoListClient project root folder, open the app.config file, and then paste the Application ID value in the ida:ClientId parameter.

Ausführen des TodoListClient-ProjektsRun your TodoListClient project

Gehen Sie zum Ausführen des TodoListClient-Projekts wie folgt vor:To run your TodoListClient project, do the following:

  1. Drücken Sie F5, um das TodoListClient-Projekt zu öffnen.Press F5 to open your TodoListClient project. Die Projektseite sollte geöffnet werden.The project page should open.

  2. Wählen Sie oben rechts die Option Anmelden aus, und melden Sie sich mit den gleichen Anmeldeinformationen an, die Sie zum Registrieren der Anwendung verwendet haben. Sie können sich aber auch als Benutzer im selben Verzeichnis anmelden.At the upper right, select Sign in, and then sign in with the same credentials you used to register your application, or sign in as a user in the same directory.

    Wenn Sie sich zum ersten Mal anmelden, werden Sie möglicherweise aufgefordert, der TodoListServiceWeb-API zuzustimmen.If you're signing in for the first time, you might be prompted to consent to the TodoListService web API.

    Mit der Anmeldung wird auch ein Zugriffstoken für den Bereich access_as_user angefordert, damit Sie auf die TodoListService-Web-API zugreifen und die To-Do-Liste bearbeiten können.To help you access the TodoListService web API and manipulate the To-Do list, the sign-in also requests an access token to the access_as_user scope.

Vorautorisieren der ClientanwendungPre-authorize your client application

Eine Möglichkeit, Benutzern aus anderen Verzeichnissen den Zugriff auf Ihre Web-API zu gestatten, besteht darin, die Clientanwendung vorab für den Zugriff auf Ihre Web-API zu autorisieren.One way you can allow users from other directories to access your web API is to pre-authorize the client application to access your web API. Dazu fügen Sie die Anwendungs-ID aus der Client-App zur Liste der vorautorisierten Anwendungen für Ihre Web-API hinzu.You do this by adding the Application ID from the client app to the list of pre-authorized applications for your web API. Durch das Hinzufügen eines vorautorisierten Clients gestatten Sie Benutzern den Zugriff auf Ihre Web-API, ohne ihre Zustimmung erteilen zu müssen.By adding a pre-authorized client, you're allowing users to access your web API without having to provide consent. Gehen Sie zum Vorautorisieren Ihrer Client-App wie folgt vor:To pre-authorize your client app, do the following:

  1. Öffnen Sie im Portal App-Registrierungen die Eigenschaften Ihrer TodoListService-App.In the App registrations portal, open the properties of your TodoListService app.
  2. Wählen Sie im Abschnitt Eine API verfügbar machen unter Autorisierte Clientanwendungen die Option Clientanwendung hinzufügen aus.In the Expose an API section, under Authorized client applications, select Add a client application.
  3. Fügen Sie im Feld Client-ID die Anwendungs-ID der TodoListClient-App ein.In the Client ID box, paste the Application ID of the TodoListClient app.
  4. Wählen Sie im Abschnitt Autorisierte Bereiche den Bereich api://<Application ID>/access_as_user für die Web-API aus.In the Authorized scopes section, select the scope for the api://<Application ID>/access_as_user web API.
  5. Wählen Sie Anwendung hinzufügen aus.Select Add application.

Ausführen des ProjektsRun your project

  1. Drücken Sie F5, um das Projekt auszuführen.Press F5 to run your project. Ihre TodoListClient-App sollte geöffnet werden.Your TodoListClient app should open.
  2. Wählen Sie oben rechts die Option Anmelden aus, und melden Sie sich mit einem persönlichen Microsoft-Konto (z. B. live.com oder hotmail.com) oder einem Geschäfts-, Schul- oder Unikonto an.At the upper right, select Sign in, and then sign in by using a personal Microsoft account, such as live.com or hotmail.com, or a work or school account.

Optional: Beschränken des Anmeldezugriffs auf bestimmte BenutzerOptional: Limit sign-in access to certain users

Wenn Sie die obigen Schritte ausgeführt haben, können standardmäßig alle persönlichen Konten (z. B. outlook.com oder live.com) oder Geschäfts-, Schul- oder Unikonten von in Azure AD integrierten Organisationen Token anfordern und auf Ihre Web-API zugreifen.By default, when you've followed the preceding steps, any personal accounts, such as outlook.com or live.com, or work or school accounts from organizations that are integrated with Azure AD can request tokens and access your web API.

Verwenden Sie eine der folgenden Optionen, um anzugeben, wer sich bei Ihrer Anwendung anmelden kann:To specify who can sign in to your application, use one of the following options:

Option 1: Beschränken des Zugriffs auf eine einzelne Organisation (einzelner Mandant)Option 1: Limit access to a single organization (single tenant)

Sie können den Anmeldezugriff für Ihre Anwendung auf bestimmte Benutzerkonten beschränken, die in einem einzelnen Azure AD-Mandanten vorhanden sind, einschließlich Gastkonten dieses Mandanten.You can limit sign-in access to your application to user accounts that are in a single Azure AD tenant, including guest accounts of that tenant. Dieses Szenario wird häufig für Branchenanwendungen eingesetzt.This scenario is common for line-of-business applications.

  1. Öffnen Sie die Datei App_Start\Startup.Auth, und ändern Sie dann den Wert des Metadatenendpunkts, der an den OpenIdConnectSecurityTokenProvider übergeben wird, in "https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration".Open the App_Start\Startup.Auth file, and then change the value of the metadata endpoint that's passed into the OpenIdConnectSecurityTokenProvider to "https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration". Sie können auch den Mandantennamen verwenden, beispielsweise contoso.onmicrosoft.com.You can also use the tenant name, such as contoso.onmicrosoft.com.
  2. Legen Sie in der gleichen Datei die Eigenschaft ValidIssuer für TokenValidationParameters auf "https://sts.windows.net/{Tenant ID}/" und das Argument ValidateIssuer auf true fest.In the same file, set the ValidIssuer property on the TokenValidationParameters to "https://sts.windows.net/{Tenant ID}/", and set the ValidateIssuer argument to true.

Option 2: Überprüfen von Ausstellern mithilfe einer benutzerdefinierten MethodeOption 2: Use a custom method to validate issuers

Sie können eine benutzerdefinierte Methode implementieren, um Aussteller mit dem Parameter IssuerValidator zu überprüfen.You can implement a custom method to validate issuers by using the IssuerValidator parameter. Weitere Informationen zur Verwendung dieses Parameters finden Sie unter TokenValidationParameters-Klasse.For more information about this parameter, see TokenValidationParameters class.

Hilfe und SupportHelp and support

Wenn Sie Hilfe benötigen, ein Problem melden möchten oder sich über Ihre Supportoptionen informieren möchten, finden Sie weitere Informationen unter Hilfe und Support für Entwickler.If you need help, want to report an issue, or want to learn about your support options, see Help and support for developers.

Nächste SchritteNext steps

Weitere Informationen zu dem Szenario mit geschützten Web-APIs, das von der Microsoft Identity Platform unterstützt wird, finden Sie hier:Learn more about the protected web API scenario that the Microsoft identity platform supports: