Minimum API'lerde kimlik doğrulaması ve yetkilendirme

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 10 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

En düşük API'ler ASP.NET Core'da sağlanan tüm kimlik doğrulama ve yetkilendirme seçeneklerini destekler ve kimlik doğrulamasıyla çalışma deneyimini geliştirmek için bazı ek işlevler sağlar.

Kimlik doğrulaması ve yetkilendirmedeki temel kavramlar

Kimlik doğrulaması, bir kullanıcının kimliğini belirleme işlemidir. Yetkilendirme, bir kullanıcının bir kaynağa erişip erişemeyeceğini belirleme işlemidir. Hem kimlik doğrulama hem de yetkilendirme senaryoları ASP.NET Core'da benzer uygulama semantiğini paylaşır. Kimlik doğrulaması, kimlik doğrulama ara yazılımı tarafından kullanılan IAuthenticationService kimlik doğrulama hizmeti tarafından işlenir. Yetkilendirme, yetkilendirme ara yazılımı tarafından kullanılan IAuthorizationService yetkilendirme hizmeti tarafından işlenir.

Kimlik doğrulaması hizmeti, kimlik doğrulamasıyla ilgili eylemleri tamamlamak için kayıtlı kimlik doğrulaması işleyicilerini kullanır. Örneğin, kimlik doğrulamasıyla ilgili bir eylem, bir kullanıcının kimliğini doğrulamak ya da bir kullanıcının oturumunu kapatmaktır. Kimlik doğrulama düzenleri, kimlik doğrulama işleyicisini ve yapılandırma seçeneklerini benzersiz olarak tanımlamak için kullanılan adlardır. Kimlik doğrulama işleyicileri, kimlik doğrulaması stratejilerini uygulamak ve OAuth veya OIDC gibi belirli bir kimlik doğrulama stratejisine bağlı olarak kullanıcının taleplerini oluşturmakla sorumludur. Yapılandırma seçenekleri de stratejiye özeldir ve işleyiciye yeniden yönlendirme URI'leri gibi kimlik doğrulama davranışını etkileyen yapılandırmayı sağlar.

Yetkilendirme katmanındaki kaynaklara kullanıcı erişimini belirlemek için iki strateji vardır:

Rol tabanlı stratejiler, kullanıcının erişimini, Administrator veya User gibi atandıkları role göre belirler. Rol tabanlı yetkilendirme hakkında daha fazla bilgi için rol tabanlı yetkilendirme belgelerine bakın.
Talep tabanlı stratejiler, merkezi bir yetkili tarafından verilen taleplere göre kullanıcının erişimini belirler. Talep tabanlı yetkilendirme hakkında daha fazla bilgi için talep tabanlı yetkilendirme belgelerine bakın.

ASP.NET Core'da her iki strateji de bir yetkilendirme gereksinimine yakalanır. Yetkilendirme hizmeti, belirli bir kullanıcının kaynağa uygulanan yetkilendirme gereksinimlerini karşılayıp karşılamadığını belirlemek için yetkilendirme işleyicilerinden yararlanır.

Minimum uygulamalarda kimlik doğrulamasını etkinleştirme

Kimlik doğrulamasını etkinleştirmek için, AddAuthentication öğesini çağırarak uygulamanın hizmet sağlayıcısında gerekli kimlik doğrulama hizmetlerini kaydedin.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Genellikle belirli bir kimlik doğrulama stratejisi kullanılır. Aşağıdaki örnekte, uygulama JWT taşıyıcı tabanlı kimlik doğrulaması desteğiyle yapılandırılır. Bu örnek, Microsoft.AspNetCore.Authentication.JwtBearer NuGet paketinde mevcut olan API'leri kullanır.

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Varsayılan olarak, WebApplication belirli kimlik doğrulama ve yetkilendirme hizmetleri etkinleştirildiğinde, kimlik doğrulama ve yetkilendirme için ara yazılımları otomatik olarak kaydeder. Aşağıdaki örnekte, ara yazılımların kayıt edilmesi için UseAuthentication veya UseAuthorization çağırmaya gerek yoktur çünkü WebApplication, AddAuthentication veya AddAuthorization çağrıldıktan sonra bu işlemi otomatik olarak yapar.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Ara yazılım sırasını denetleme gibi bazı durumlarda kimlik doğrulaması ve yetkilendirmeyi açıkça kaydetmek gerekir. Aşağıdaki örnekte, kimlik doğrulama ara yazılımı CORS ara yazılımı çalıştırıldıktan sonra çalıştırılır. Ara yazılım ve bu otomatik davranış hakkında daha fazla bilgi için lütfen Minimal API uygulamalarında Ara Yazılım bölümüne bakınız.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

Kimlik doğrulama stratejisini yapılandırma

Kimlik doğrulama stratejileri genellikle seçenekler aracılığıyla yüklenen çeşitli yapılandırmaları destekler. Minimalist uygulamalar, aşağıdaki kimlik doğrulama stratejileri için yapılandırmadan yükleme seçeneklerini destekler:

ASP.NET Core çerçevesi, yapılandırma bölümündeki Authentication:Schemes:{SchemeName}bu seçenekleri bulmayı bekler. Aşağıdaki örnekte, iki farklı düzen Bearer ve LocalAuthIssuer, ilgili seçenekleriyle tanımlanır. seçeneği Authentication:DefaultScheme , kullanılan varsayılan kimlik doğrulama stratejisini yapılandırmak için kullanılabilir.

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

Program.cs içinde, iki adet JWT taşıyıcı tabanlı kimlik doğrulama stratejisi, aşağıdakilerle beraber kaydedilir:

Bearer şeması adı.
"LocalAuthIssuer" şeması adı.

"Taşıyıcı", JWT taşıyıcı tabanlı etkin uygulamalarda tipik varsayılan düzendir, ancak önceki örnekte olduğu gibi özelliği ayarlanarak DefaultScheme varsayılan düzen geçersiz kılınabilir.

Düzen adı, bir kimlik doğrulama stratejisini benzersiz olarak tanımlamak için kullanılır ve aşağıdaki örnekte gösterildiği gibi yapılandırmadan kimlik doğrulama seçenekleri çözümlendiğinde arama anahtarı olarak kullanılır:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Minimum uygulamalarda yetkilendirme ilkelerini yapılandırma

Kimlik doğrulaması, kullanıcıların kimliğini bir API'ye göre tanımlamak ve doğrulamak için kullanılır. Yetkilendirme, bir API'deki kaynaklara erişimi doğrulamak ve onaylamak için kullanılır ve IAuthorizationService uzantı yöntemi tarafından kaydedilen AddAuthorization tarafından kolaylaştırılır. Aşağıdaki senaryoda, bir /hello kaynağı eklenir ve kullanıcıdan bir admin kapsam talebiyle birlikte bir greetings_api rol talebi sunması istenir.

Bir kaynakta yetkilendirme gereksinimlerini yapılandırmak, şunları gerektiren iki adımlı bir işlemdir:

İlkedeki yetkilendirme gereksinimlerini genel olarak yapılandırma.
Kaynaklara bireysel politikalar uygulama.

Aşağıdaki kodda AddAuthorizationBuilder çağrılır ve:

DI kapsayıcısına yetkilendirmeyle ilgili hizmetler ekler.
Yetkilendirme ilkelerini doğrudan kaydetmek için kullanılabilecek bir AuthorizationBuilder döndürür.

Kod, iki yetkilendirme gereksinimini kapsayan adlı admin_greetingsyeni bir yetkilendirme ilkesi oluşturur:

RequireRole rolüne sahip kullanıcılar için admin aracılığıyla rol tabanlı bir gereksinim.
Kullanıcıdan RequireClaim kapsam talebi sağlamasını gerektiren greetings_api talep tabanlı bir gereksinim.

admin_greetings politikası, uç nokta /hello için gerekli bir politika olarak sağlanır.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

Geliştirme testi için `dotnet user-jwts` kullan

Bu makale boyunca JWT taşıyıcı tabanlı kimlik doğrulaması ile yapılandırılan bir uygulama kullanılır. JWT taşıyıcı tabanlı kimlik doğrulaması, istemcilerin kimliklerini ve taleplerini doğrulamak için istek üst bilgisinde bir belirteç sunmalarını gerektirir. Bu belirteçler genellikle kimlik sunucusu gibi merkezi bir yetkili tarafından verilir.

Yerel makinede geliştirme yaparken, araç kullanılarak dotnet user-jwts taşıyıcı belirteçler oluşturulabilir.

dotnet user-jwts create

Not

Bir projede çağrıldığında, araç oluşturulan belirteçle eşleşen kimlik doğrulama seçeneklerini appsettings.json otomatik olarak ekler.

Belirteçler çeşitli özelleştirmelerle yapılandırılabilir. Örneğin, önceki kodda yetkilendirme ilkesi tarafından beklenen admin rolü ve greetings_api kapsamı için bir belirteç oluşturmak üzere:

dotnet user-jwts create --scope "greetings_api" --role "admin"

Oluşturulan belirteç daha sonra tercih edilen test aracında üst bilginin bir parçası olarak gönderilebilir. Örneğin, curl ile:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/hello

Araç hakkında dotnet user-jwts daha fazla bilgi için tüm belgeleri okuyun.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-19