Szybki start: logowanie użytkowników w aplikacji internetowej ASP.NET Core

W tym przewodniku szybkiego startu utworzysz aplikację internetową ASP.NET Core, która loguje użytkowników za pomocą Microsoft Entra ID używając Microsoft.Identity.Web. Możesz utworzyć szkielet nowego projektu z szablonu lub dodać uwierzytelnianie do istniejącej aplikacji.

Jeśli nie masz dzierżawy Microsoft Entra, przed rozpoczęciem utwórz bezpłatne konto.

Wymagania wstępne

• .NET 9 SDK
• Dzierżawa Microsoft Entra ID
• Rejestracja aplikacji w dzierżawie Microsoft Entra. Jeśli musisz go utworzyć, zobacz Rejestrowanie aplikacji.

Tworzenie projektu na podstawie szablonu

Najszybszym sposobem rozpoczęcia pracy jest utworzenie szkieletu nowego projektu ze wstępnie skonfigurowanym uwierzytelnianiem.

Uruchom następujące polecenia, aby utworzyć nową aplikację internetową z uwierzytelnianiem jednej organizacji i przejść do katalogu projektu:

dotnet new webapp --auth SingleOrg --name MyWebApp
cd MyWebApp

Szablon generuje projekt z Microsoft.Identity.Web już skonfigurowany. Wystarczy podać szczegóły rejestracji aplikacji.

Otwórz appsettings.json i zamień wartości symboli zastępczych na identyfikator aplikacji (klienta) i identyfikator katalogu (dzierżawy) z rejestracji aplikacji:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc"
  }
}

Uruchom aplikację, aby sprawdzić, czy logowanie działa:

dotnet run

Przejdź do https://localhost:5001 strony i wybierz pozycję Zaloguj się. Jeśli zostanie wyświetlony Microsoft monit logowania, konfiguracja jest poprawna.

Dodawanie uwierzytelniania do istniejącej aplikacji internetowej

Jeśli masz istniejącą aplikację ASP.NET Core, wykonaj poniższe kroki, aby dodać Microsoft Entra do logowania.

Instalowanie pakietów NuGet

Dodaj biblioteki Microsoft.Identity.Web. Pakiet Microsoft.Identity.Web obsługuje uwierzytelnianie, a Microsoft.Identity.Web.UI udostępnia wstępnie utworzone składniki logowania i wylogowania interfejsu użytkownika:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI

Konfigurowanie usług uwierzytelniania

Otwórz Program.cs i dodaj usługi uwierzytelniania. Poniższy kod rejestruje uwierzytelnianie openID Connect za pomocą Microsoft Entra, umożliwia pozyskiwanie tokenów dla wywołań interfejsu API podrzędnego i dodaje interfejs użytkownika logowania/wylogowania:

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApp(builder.Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi() // Optional: if calling APIs
                .AddInMemoryTokenCaches(); // For production, use distributed cache

// Add Razor Pages or MVC
builder.Services.AddRazorPages()
    .AddMicrosoftIdentityUI(); // Adds sign-in/sign-out UI

var app = builder.Build();

// Configure middleware
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapRazorPages();
app.MapControllers();

app.Run();

Dodaj konfigurację Microsoft Entra

Otwórz appsettings.json i dodaj sekcję AzureAd . Zastąp wartości symboli zastępczych Identyfikatorem aplikacji (klienta). Określ TenantId odpowiednią grupę odbiorców dla swojej aplikacji.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-client-id-from-app-registration",
    "CallbackPath": "/signin-oidc"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

Wartość TenantId określa, które konta mogą się zalogować:

Wartość	Zaakceptowane konta
common	Konta służbowe i osobiste Microsoft
organizations	Tylko konta służbowe lub szkolne
consumers	Tylko osobiste konta Microsoft
<your-tenant-id>	Jedna dzierżawa — tylko Twoja organizacja

Ochrona stron

[Authorize] Dodaj atrybut do stron lub kontrolerów, które wymagają logowania.

W przypadku stron Razor, atrybut [Authorize] przekierowuje nieuwierzytelnionych użytkowników do strony logowania. Po zalogowaniu się oświadczenia użytkownika, takie jak Name i preferred_username, są dostępne za pośrednictwem obiektu User.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.RazorPages;

[Authorize] //  Require authentication
public class IndexModel : PageModel
{
    public void OnGet()
    {
        var userName = User.Identity?.Name;
        var userEmail = User.FindFirst("preferred_username")?.Value;
    }
}

W przypadku kontrolerów MVC ten sam [Authorize] atrybut ma zastosowanie na poziomie kontrolera lub akcji:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require authentication
public class HomeController : Controller
{
    public IActionResult Index()
    {
        var userName = User.Identity?.Name;
        return View();
    }
}

Dodawanie linków logowania i wylogowywanie

Dodaj łącza nawigacji do układu, aby użytkownicy mogli się zalogować i wylogować. Trasy obszaru MicrosoftIdentity są udostępniane przez pakiet Microsoft.Identity.Web.UI. Następujący kod znaczników Razor warunkowo renderuje Wyloguj się lub Zaloguj się na podstawie stanu uwierzytelniania użytkownika.

<ul class="navbar-nav">
    @if (User.Identity?.IsAuthenticated == true)
    {
        <li class="nav-item">
            <span class="nav-link">Hello @User.Identity.Name!</span>
        </li>
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
        </li>
    }
    else
    {
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
        </li>
    }
</ul>

Uruchamianie i testowanie

Uruchom aplikację, aby sprawdzić, czy uwierzytelnianie działa:

dotnet run

Przejdź do strony https://localhost:5001. Powinien zostać wyświetlony link Zaloguj. Wybierz go, aby potwierdzić pomyślne zakończenie przepływu logowania Microsoft.

Rejestrowanie aplikacji

Jeśli nie masz jeszcze rejestracji aplikacji, wykonaj następujące kroki, aby utworzyć aplikację w portalu Azure.

1. Zaloguj się do portalu Azure.
2. Przejdź do Microsoft Entra ID>Rejestracje aplikacji>Nowa rejestracja.
3. Wprowadź nazwę wyświetlaną (na przykład "Moja aplikacja internetowa").
4. Wybierz obsługiwane typy kont:
   • Jedna dzierżawa — tylko dla użytkowników w Twojej organizacji
   • Wielo-tenancy — użytkownicy z dowolnych organizacji
   • Multi-tenant + personal — wszystkie konta Microsoft
5. W obszarze Identyfikator URI przekierowania ustaw platformę na Web i wprowadź wartość https://localhost:5001/signin-oidc.
6. Wybierz pozycję Zarejestruj.
7. Na stronie przeglądu skopiuj identyfikator aplikacji (klienta) i identyfikator katalogu (najemcy). Te wartości są potrzebne dla pól ClientId i TenantId w pliku appsettings.json.

Konfigurowanie opcjonalnych ustawień

Twój scenariusz może wymagać tych dodatkowych ustawień.

Włącz wystawianie tokenu identyfikatora — niektóre scenariusze uwierzytelniania hybrydowego wymagają wystawiania tokenów identyfikatorów bezpośrednio z punktu końcowego autoryzacji. Przepływ kodu autoryzacji (używany przez Microsoft.Identity.Web) jest zalecaną metodą. Włącz to ustawienie tylko wtedy, gdy w twoim scenariuszu jest to wymagane:

1. W rejestracji aplikacji przejdź do pozycji Uwierzytelnianie.
2. W obszarze Niejawne udzielanie i przepływy hybrydowe wybierz pozycję Tokeny ID.
3. Wybierz opcję Zapisz.

Note

Przepływ udzielania zasobów w trybie implicit to przestarzały przepływ. Microsoft zaleca przepływ kodu autoryzacji z mechanizmem PKCE dla wszystkich nowych aplikacji. Aby uzyskać więcej informacji, zobacz dokumentację Platforma tożsamości Microsoft.

Konfigurowanie adresu URL wylogowywania kanału przedniego — gwarantuje, że użytkownicy zostaną wylogowani z aplikacji, kiedy wylogują się z Microsoft Entra.

1. W rejestracji aplikacji przejdź do pozycji Uwierzytelnianie.
2. W obszarze Adres URL wylogowywania kanału frontonu wprowadź https://localhost:5001/signout-oidc.
3. Wybierz opcję Zapisz.

Rozwiązywanie typowych błędów

Jeśli podczas logowania wystąpią problemy, sprawdź te typowe błędy.

Błąd	Przyczyna	Rozwiązanie
AADSTS50011: Brak zarejestrowanego adresu odpowiedzi	Niezgodność identyfikatora URI przekierowania między kodem a rejestracją aplikacji	Sprawdź, czy identyfikator URI przekierowania w rejestracji aplikacji zgadza się z CallbackPath (/signin-oidc domyślnie)
AADSTS700016: Nie znaleziono aplikacji	Niepoprawne ClientId w konfiguracji	Upewnij się, że identyfikator aplikacji (klienta) w pliku appsettings.json jest zgodny z rejestracją aplikacji
Błąd konfiguracji autorytetu	Brak lub nieprawidłowy Instance lub TenantId	Ustaw Instance na https://login.microsoftonline.com/ i potwierdź, że TenantId jest prawidłowe

Treści powiązane

• Wywoływanie podrzędnych interfejsów API z aplikacji internetowych
• Autoryzacja
• Omówienie pamięci podręcznej tokenów
• Szybki start: internetowy interfejs API