Hızlı Başlangıç: ASP.NET Core Web API'sini koruma

Bu hızlı başlangıçta, Microsoft.Identity.Web'i kullanarak Microsoft Entra ID ile ASP.NET Core web API'sini korursunuz. Taşıyıcı belirteçlerini doğrulayan ve yetkili arayanlara erişimi kısıtlayan kimlik doğrulama ara yazılımı eklersiniz.

Eğer bir Azure aboneliğiniz yoksa, başlamadan önce ücretsiz bir hesap oluşturun.

Önkoşullar

1. Seçenek: Şablondan oluşturma (en hızlı)

Korumalı bir API projesinin iskelesini oluşturmak için yerleşik Microsoft Entra kimlik doğrulamasıyla ASP.NET Core şablonunu kullanın.

1. Projeyi oluşturma

Tek kuruluşlu kimlik doğrulamasıyla yeni bir web API'si projesi oluşturmak ve proje dizinine gitmek için aşağıdaki komutları çalıştırın:

dotnet new webapi --auth SingleOrg --name MyWebApi
cd MyWebApi

2. Uygulama kaydını yapılandırma

appsettings.json'daki yer tutucu değerlerini Microsoft Entra uygulama kayıt ayrıntılarınızla değiştirin:

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

3. API'yi çalıştırın

Uygulamayı başlatın:

dotnet run

API'niz artık https://localhost:5001 konumunda korunmaktadır.

Bitti! İstekler artık geçerli bir erişim belirteci gerektiriyor.

2. Seçenek: Mevcut Web API'sine ekleme

Zaten bir ASP.NET Core web API'niz varsa, aşağıdaki adımlarla Microsoft Entra kimlik doğrulaması ekleyin.

1. NuGet paketini yükleme

Projenize Microsoft.Identity.Web NuGet paketini ekleyin.

dotnet add package Microsoft.Identity.Web

2. Kimlik doğrulamasını yapılandırın Program.cs

Kimlik doğrulama ve yetkilendirme hizmetlerini uygulamanızın başlangıç işlem hattına kaydedin. Aşağıdaki kod, Microsoft Entra doğrulama ile JWT taşıyıcı kimlik doğrulamasını yapılandırıyor:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(builder.Configuration, "AzureAd");

// Add authorization
builder.Services.AddAuthorization();

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

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

app.MapControllers();

app.Run();

3. Yapılandırmayı appsettings.json'ye ekleyin

Microsoft Entra yapılandırma bölümünü kiracınız ve uygulama ayrıntılarınızla ekleyin. Token doğrulama sorunlarını gidermeye yardımcı olmak için Microsoft.Identity.Web kayıt seviyesini Information olarak ayarlayın.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

4. API uç noktalarınızı koruma

Özniteliği geçerli [Authorize] bir erişim belirteci gerektiren denetleyicilere veya eylemlere uygulayın.

Tüm uç noktalar için kimlik doğrulaması gerektir:

Aşağıdaki denetleyici tüm eylemler için geçerli bir erişim belirteci gerektirir ve kullanıcı taleplerine nasıl erişilir gösterir:

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

[Authorize] //  Require valid access token
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Access user information
        var userId = User.FindFirst("oid")?.Value;
        var userName = User.Identity?.Name;

        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = "Protected data"
        });
    }
}

Belirli kapsamları gerektir:

[RequiredScope] özniteliğini kullanarak bireysel eylemlerde ayrıntılı izinler tanımlayın.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Identity.Web;

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    [HttpGet]
    [RequiredScope("access_as_user")] //  Require specific scope
    public IActionResult GetAll()
    {
        return Ok(new[] { "Todo 1", "Todo 2" });
    }

    [HttpPost]
    [RequiredScope("write")] //  Different scope for write operations
    public IActionResult Create([FromBody] string item)
    {
        return Created("", item);
    }
}

5. Çalıştırma ve test

Uygulamayı başlatın ve kimliği doğrulanmamış isteklerin reddedildiğini doğrulayın:

dotnet run

Postman veya curl gibi bir araçla test edin. Kimliği doğrulanmamış bir istek 401 Unauthorized döndürür.

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://localhost:5001/api/weatherforecast

Başarı! API'niz artık taşıyıcı belirteçleri doğrular.

Uygulama kaydı kurulumu

API'nizin belirteçleri doğrulayabilmesi için önce bir Microsoft Entra uygulama kaydına ihtiyacınız vardır. Azure portalında bu adımları izleyin.

1. API'nizi kaydetme

  1. Azure portalında oturum açın
  2. Microsoft Entra ID>Uygulama Kayıtları>Yeni kayıt
  3. Bir ad girin (örneğin, "Web API'm")
  4. Tek kiracı (API'ler için en yaygın) seçeneğini belirleyin
  5. API'ler için yeniden yönlendirme URI'sine gerek yok
  6. Kaydet'e tıklayın

2. API kapsamını kullanıma sunma

api'nizi çağırırken istemci uygulamalarının isteyebileceği izinleri (kapsamları) tanımlayın.

  1. API uygulama kaydınızda API'yi kullanıma sunma bölümüne gidin
  2. Kapsam ekle'ye tıklayın
  3. Varsayılan Uygulama Kimliği URI'sini kabul edin veya özelleştirin (örn. api://your-api-client-id)
  4. Bir kapsam ekle:
    • Kapsam adı:access_as_user
    • Kim onay verebilir: Yöneticiler ve kullanıcılar
    • Yönetici onayı görünen adı: "Web API'me eriş"
    • Yönetici onayı açıklaması: "Uygulamanın oturum açmış kullanıcı adına web API'sine erişmesine izin verir"
  5. Kapsam ekle'ye tıklayın

3. Uygulama kimliğini not edin

Uygulama kaydına genel bakış sayfasından Uygulama (istemci) kimliğini kopyalayın. Bu değer appsettings.json içindeki ClientId değerinizdir.

Test amacıyla bir istemci uygulama kaydı oluşturma

Korumalı API'nizi test etmek için belirteçleri alan ve API'yi çağıran ayrı bir istemci uygulaması kaydedin.

1. İstemci uygulamasını kaydetme

  1. Microsoft Entra ID>Uygulama kayıtları içinde başka bir kayıt oluşturun
  2. Ad verin (örneğin, "API İstemcim")
  3. Hesap türlerini seçme
  4. Yeniden yönlendirme URI'sini ekleme: https://localhost:7000/signin-oidc (bu bir web uygulamasıysa)
  5. Kaydet'e tıklayın

2. API izinleri verme

tanımladığınız kapsamlarla API'nizi çağırmak için istemci uygulamasına izin verin.

  1. İstemci uygulaması kaydında API izinleri'ne gidin
  2. İzin> ekleAPI'lerim'e tıklayın
  3. API kaydınızı seçin
  4. access_as_user Kapsamı denetle
  5. İzin ekle'ye tıklayın
  6. Yönetici onayı ver'e tıklayın (gerekirse)

3. İstemci sırrı oluşturun (gizli istemciler için)

İstemci uygulamanız bir sunucuda (tarayıcı veya mobil cihaz değil) çalışıyorsa, kimlik doğrulaması için bir istemci gizli dizisi oluşturun.

  1. Sertifikalar ve Gizli Bilgiler'e gidin
  2. Yeni istemci gizli anahtarı oluştur'a tıklayın
  3. Açıklama ve süre sonu ekleme
  4. Ekle'ye tıklayın
  5. Gizli dizi değerini hemen kopyalayın ; bir daha göremezsiniz

Korumalı API'nizi test edin

API'nizin belirteçleri doğru şekilde doğruladığını kontrol etmek için kimlik doğrulaması yapılmış istekler gönderin.

Postman'ın kullanımı

Bir belirteç almak ve API'nizi çağırmak için Postman'de OAuth 2.0 kimlik doğrulamasını ayarlayın.

  1. Postman'de yeni istek oluşturma
  2. OAuth 2.0 kimlik doğrulamasını ayarlayın:
    • Verme Türü: Yetkilendirme Kodu (kullanıcı bağlamı için) veya İstemci Kimlik Bilgileri (uygulama bağlamı için)
    • Kimlik doğrulama URL'si:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
    • Erişim Belirteci URL'si:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
    • İstemci Kimliği: İstemci uygulamanızın istemci kimliği
    • İstemci Sırrı: İstemci uygulamanızın sırrı
    • Kapsam:api://your-api-client-id/access_as_user
  3. Yeni Erişim Belirteci Al'a tıklayın
  4. API'nizi çağırmak için belirteci kullanma

Kod kullanma (C# örneği)

Aşağıdaki örnek, istemci kimlik bilgileri akışıyla belirteç almak ve korumalı API'yi çağırmak için MSAL.NET kullanır:

// In a console app or client application
using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create("client-app-id")
    .WithClientSecret("client-secret")
    .WithAuthority("https://login.microsoftonline.com/{tenant-id}")
    .Build();

var result = await app.AcquireTokenForClient(
    new[] { "api://your-api-client-id/.default" }
).ExecuteAsync();

var accessToken = result.AccessToken;

// Use the token to call your API
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync("https://localhost:5001/api/weatherforecast");

Yaygın yapılandırma seçenekleri

Microsoft. Identity.Web, farklı senaryolar için çeşitli yapılandırma desenlerini destekler.

Yapılandırmada belirli kapsamlar gerektir

[RequiredScope] özniteliğini kullanmak yerine, gerekli kapsamları genel olarak appsettings.json içerisinde yapılandırabilirsiniz.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id",
    "Scopes": "access_as_user"
  }
}

Birden fazla kiracıdan gelen belirteçleri kabul etme

Herhangi bir Microsoft Entra kiracısından belirteçleri kabul etmek için TenantId değerini common olarak ayarlayın:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-api-client-id"
  }
}

Belirteç doğrulamayı yapılandırma

API'niz aşağı akış API'lerini (Microsoft Graph gibi) çağırırsa, belirteç alımını etkinleştirin ve bir belirteç önbelleği yapılandırın:

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi() // If your API calls other APIs
    .AddInMemoryTokenCaches();

Sonraki Adımlar

Artık korumalı bir API'niz olduğuna göre şu konuları inceleyin:

Sorun giderme

401 Yetkisiz

Sorun: API, belirteçle bile 401 döndürür.

Olası nedenler:

  • Belirteç hedef kitlesi (aud talep) API'nizin hedef kitlesiyle eşleşmiyor ClientId
  • Jetonun süresi doldu
  • Jeton yanlış kiracı için
  • Gerekli kapsam eksik

Çözüm:jwt.ms'da belirtecin kodunu çözerek talepleri doğrulayın. Ayrıntılı sorun giderme için Günlük ve Tanılama bölümüne bakın.

AADSTS50013: Geçersiz imza

Sorun: Belirteç imzası doğrulaması başarısız oluyor.

Çözüm:TenantId ve ClientId öğelerinin doğru olduğundan emin olun. Jeton beklenen yetkili tarafından verilmelidir. Ayrıntılı günlüğe kaydetmeyi etkinleştirerek doğrulama hatalarını görebilirsiniz.

Belirteçte kapsamlar bulunamadı

Sorun:[RequiredScope] özniteliği başarısız oluyor.

Çözüm:

  1. İstemci uygulamasının kapsam iznine sahip olduğunu doğrulayın
  2. Yönetici onayı verildiğine emin olun (gerekirse)
  3. Tam kapsam doğrulama desenleri için bkz. Yetkilendirme Kılavuzu
  4. Belirteci edinirken kapsamın talep edildiğinden emin olun (örneğin, api://your-api/.default veya belirli kapsamlar)

Daha fazla bilgi:Web API'sinde Sorun Giderme Kılavuzu

İlgili içerik

  • Last updated on