Korumalı web API'si: Kapsamları ve uygulama rollerini doğrulama

Bu makalede, web API'nize nasıl yetkilendirme ekleyebileceğiniz açıklanır. Bu koruma, API'nin yalnızca şu şekilde çağrılmasını sağlar:

• Doğru kapsamlara ve rollere sahip kullanıcılar adına uygulamalar.
• Doğru uygulama rollerine sahip Daemon uygulamaları.

Bu makaledeki kod parçacıkları GitHub'daki aşağıdaki kod örneklerinden ayıklanır:

• ASP.NET Core web API'sinde artımlı öğretici
• web API'si örneğini ASP.NET

bir ASP.NET veya ASP.NET Core web API'sini [Authorize] korumak için özniteliğini aşağıdaki öğelerden birine eklemeniz gerekir:

• Tüm denetleyici eylemlerinin korunmasını istiyorsanız denetleyicinin kendisi
• API'niz için tek tek denetleyici eylemi

    [Authorize]
    public class TodoListController : Controller
    {
     // ...
    }

Ama bu koruma yeterli değil. Yalnızca ASP.NET ve ASP.NET Core'un belirteci doğrulamasını garanti eder. API'nizin, API'yi çağırmak için kullanılan belirtecin beklenen taleplerle istendiğini doğrulaması gerekir. Özellikle bu taleplerin doğrulanması gerekir:

• API bir kullanıcı adına çağrılırsa kapsamlar.
• API bir daemon uygulamasından çağrılabiliyorsa uygulama rolleri.

KULLANıCıLAR adına çağrılan API'lerdeki kapsamları doğrulama

bir istemci uygulaması API'nizi bir kullanıcı adına çağırırsa, API'nin API için belirli kapsamlara sahip bir taşıyıcı belirteci istemesi gerekir. Daha fazla bilgi için bkz. Kod yapılandırması | Taşıyıcı belirteci.

ASP.NET Core

ASP.NET Core'da, her denetleyici eylemindeki kapsamları doğrulamak için Microsoft.Identity.Web'i kullanabilirsiniz. Bunları denetleyici düzeyinde veya uygulamanın tamamı için de doğrulayabilirsiniz.

Her denetleyici eylemindeki kapsamları doğrulama

özniteliğini kullanarak [RequiredScope] denetleyici eylemindeki kapsamları doğrulayabilirsiniz. Bu özniteliğin çeşitli geçersiz kılmaları vardır. Gerekli kapsamları doğrudan alan ve yapılandırmanın anahtarını alan bir kapsam.

Bir denetleyici eylemindeki kapsamları sabit kodlanmış kapsamlarla doğrulama

Aşağıdaki kod parçacığı, sabit kodlanmış kapsamlarla özniteliğin [RequiredScope] kullanımını gösterir.

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : Controller
{
    /// <summary>
    /// The web API will accept only tokens that have the `access_as_user` scope for
    /// this API.
    /// </summary>
    const string scopeRequiredByApi = "access_as_user";

    // GET: api/values
    [HttpGet]
    [RequiredScope(scopeRequiredByApi)]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Yapılandırmada tanımlanan kapsamlarla bir denetleyici eylemindeki kapsamları doğrulama

Ayrıca yapılandırmada bu gerekli kapsamları bildirebilir ve yapılandırma anahtarına başvurabilirsiniz:

Örneğin, appsettings.json aşağıdaki yapılandırmaya sahipseniz:

{
 "AzureAd" : {
   // more settings
   "Scopes" : "access_as_user access_as_admin"
  }
}

Ardından, özniteliğinde [RequiredScope] buna başvurun:

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : Controller
{
    // GET: api/values
    [HttpGet]
    [RequiredScope(RequiredScopesConfigurationKey = "AzureAd:Scopes")]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Kapsamları koşullu olarak doğrulama

Kapsamları koşullu olarak doğrulamak istediğiniz durumlar vardır. Bunu, üzerindeki HttpContextuzantı yöntemini kullanarak VerifyUserHasAnyAcceptedScope yapabilirsiniz.

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : Controller
{
    /// <summary>
    /// The web API will accept only tokens 1) for users, 2) that have the `access_as_user` scope for
    /// this API.
    /// </summary>
    static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

    // GET: api/values
    [HttpGet]
    public IEnumerable<TodoItem> Get()
    {
         HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);
        // Do the work and return the result.
        // ...
    }
 // ...
}

Kapsamları denetleyici düzeyinde doğrulayın

Ayrıca, denetleyicinin tamamı için kapsamları doğrulayabilirsiniz

Sabit kodlanmış kapsamlara sahip bir denetleyicideki kapsamları doğrulama

Aşağıdaki kod parçacığı, denetleyicide [RequiredScope] sabit kodlanmış kapsamlarla özniteliğin kullanımını gösterir. RequiredScopeAttribute'u kullanmak için aşağıdakilerden birini yapmanız gerekir:

• Kod yapılandırmasında görüldüğü gibi Startup.cs kullanın AddMicrosoftIdentityWebApi
• veya yetkilendirme ilkelerinde açıklandığı gibi öğesini yetkilendirme ilkelerine ekleyinScopeAuthorizationRequirement.

using Microsoft.Identity.Web

[Authorize]
[RequiredScope(scopeRequiredByApi)]
public class TodoListController : Controller
{
    /// <summary>
    /// The web API will accept only tokens 1) for users, 2) that have the `access_as_user` scope for
    /// this API.
    /// </summary>
    static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

    // GET: api/values
    [HttpGet]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Yapılandırmada tanımlanan kapsamlarla bir denetleyicideki kapsamları doğrulama

Eylemde olduğu gibi, yapılandırmada da bu gerekli kapsamları bildirebilir ve yapılandırma anahtarına başvurabilirsiniz:

using Microsoft.Identity.Web

[Authorize]
[RequiredScope(RequiredScopesConfigurationKey = "AzureAd:Scopes")]
public class TodoListController : Controller
{
    // GET: api/values
    [HttpGet]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Kapsamları daha genel olarak doğrulama

Web API'niz için ayrıntılı kapsamlar tanımlamak ve her denetleyici eylemindeki kapsamları doğrulamak önerilen yaklaşımdır. Ancak kapsamları uygulama veya denetleyici düzeyinde doğrulamak da mümkündür. Ayrıntılar için ASP.NET Core belgelerinde talep tabanlı yetkilendirme bölümüne bakın.

Doğrulanan nedir?

[RequiredScope] özniteliği ve VerifyUserHasAnyAcceptedScope yöntemi aşağıdaki adımlara benzer bir işlem yapar:

• veya scpadlı http://schemas.microsoft.com/identity/claims/scope bir talep olduğunu doğrulayın.
• Talebin API tarafından beklenen kapsamı içeren bir değere sahip olduğunu doğrulayın.

klasik ASP.NET

ASP.NET bir uygulamada kapsamları aşağıdaki şekilde doğrulayabilirsiniz:

[Authorize]
public class TodoListController : ApiController
{
    public IEnumerable<TodoItem> Get()
    {
       ValidateScopes(new[] {"read"; "admin" } );
       // ...
    }

Aşağıda basitleştirilmiş bir sürümü yer almaktadır ValidateScopes:

private void ValidateScopes(IEnumerable<string> acceptedScopes)
{
    //
    // The `role` claim tells you what permissions the client application has in the service.
    // In this case, we look for a `role` value of `access_as_application`.
    //
    Claim scopeClaim = ClaimsPrincipal.Current.FindFirst("scp");
    if (scopeClaim == null || !scopeClaim.Value.Split(' ').Intersect(acceptedScopes).Any())
    {
        throw new HttpResponseException(new HttpResponseMessage
        { StatusCode = HttpStatusCode.Forbidden,
            ReasonPhrase = $"The 'scp' claim does not contain '{scopeClaim}' or was not found"
        });
    }
}

ASP.NET Core için tam sürümü ValidateScopes için bkz . ScopesRequiredHttpContextExtensions.cs

Daemon uygulamaları tarafından çağrılan API'lerde uygulama rollerini doğrulama

Web API'niz bir daemon uygulaması tarafından çağrılırsa, bu uygulama web API'niz için bir uygulama izni gerektirmelidir. Uygulama izinlerini (uygulama rolleri) kullanıma sunma bölümünde gösterildiği gibi, API'niz bu tür izinleri kullanıma sunar. Örneklerden biri uygulama rolüdür access_as_application .

Şimdi API'nizin aldığı belirtecin talebi içerdiğini ve bu talebin roles beklenen değere sahip olduğunu doğrulamasını sağlamalısınız. Doğrulama kodu, temsilci izinlerini doğrulayan koda benzer, ancak denetleyici eyleminiz kapsamlar yerine roller için sınar:

ASP.NET Core

Aşağıdaki kod parçacığı, uygulama rolünün nasıl doğrulandığını gösterir;

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : ApiController
{
    public IEnumerable<TodoItem> Get()
    {
        HttpContext.ValidateAppRole("access_as_application");
        // ...
    }

Bunun yerine, denetleyicideki [Authorize(Roles = "access_as_application")] öznitelikleri veya bir eylemi (veya razor sayfasını) kullanabilirsiniz.

[Authorize(Roles = "access_as_application")]
MyController : ApiController
{
    // ...
}

ASP.NET Core'da rol tabanlı yetkilendirme, rol tabanlı yetkilendirme uygulamak için çeşitli yaklaşımları listeler. Geliştiriciler, kendi senaryolarına uygun bir tane seçebilir.

Çalışan örnekler için, rollere ve gruplara göre yetkilendirmeyle ilgili web uygulaması artımlı öğreticisine bakın.

klasik ASP.NET

ASP.NET bir uygulamada uygulama rollerini aşağıdaki şekilde doğrulayabilirsiniz:

[Authorize]
public class TodoListController : ApiController
{
    public IEnumerable<TodoItem> Get()
    {
       ValidateAppRole("access_as_application");
       // ...
    }

Basitleştirilmiş bir sürümü ValidateAppRole :

private void ValidateAppRole(string appRole)
{
    //
    // The `role` claim tells you what permissions the client application has in the service.
    // In this case, we look for a `role` value of `access_as_application`.
    //
    Claim roleClaim = ClaimsPrincipal.Current.FindFirst("roles");
    if (roleClaim == null || !roleClaim.Value.Split(' ').Contains(appRole))
    {
        throw new HttpResponseException(new HttpResponseMessage
        { StatusCode = HttpStatusCode.Unauthorized,
            ReasonPhrase = $"The 'roles' claim does not contain '{appRole}' or was not found"
        });
    }
}

ASP.NET Core için tam sürümü ValidateAppRole için RolesRequiredHttpContextExtensions.cs koduna bakın.

Kullanıcılar adına çağrılan API'lerde uygulama rollerini doğrulama

Kullanıcılar, uygulamanıza uygulama rolleri ekleme ve bunları belirteçte alma bölümünde gösterildiği gibi kullanıcı atama desenlerinde rol taleplerini de kullanabilir. Roller her ikisine de atanabilirse, rollerin denetlenmesinde uygulamalar kullanıcı ve kullanıcı olarak oturum açar. Bu karışıklığı önlemek için kullanıcılar ve uygulamalar için farklı roller bildirmenizi öneririz.

Kullanıcı/grup ile uygulama rolleri tanımladıysanız, roller talebi kapsamlarla birlikte API'de de doğrulanabilir. Bu senaryoda uygulama rollerinin doğrulama mantığı, kullanıcı/grup ve uygulama için rol taleplerinde farklılaşma olmadığından API'nin daemon uygulamaları tarafından çağrılır olmasıyla aynı kalır.

Web API'sinin yalnızca daemon uygulamaları tarafından çağrılması gerekiyorsa yalnızca uygulama belirteçlerini kabul etme

Web API'nizi yalnızca daemon uygulamalarının çağırmasını istiyorsanız, uygulama rolünü doğruladığınızda belirtecin yalnızca uygulama belirteci olması koşulunu ekleyin.

string oid = ClaimsPrincipal.Current.FindFirst("oid")?.Value;
string sub = ClaimsPrincipal.Current.FindFirst("sub")?.Value;
bool isAppOnly = oid != null && sub != null && oid == sub;

Ters koşulun denetlenmesinin yapılması, yalnızca bir kullanıcıda oturum açabilen uygulamaların API'nizi çağırmasına olanak tanır.

ACL tabanlı yetkilendirmeyi kullanma

Uygulama rolleri tabanlı yetkilendirmeye alternatif olarak, talep olmadan belirteçleri denetlemek için web API'nizi Erişim Denetim Listesi (ACL) tabanlı yetkilendirme düzeniyle roles koruyabilirsiniz.

ASP.NET Core'da kullanıyorsanız Microsoft.Identity.Web , ACL tabanlı yetkilendirme kullandığınızı bildirmeniz gerekir, aksi takdirde Microsoft Identity Web sağlanan taleplerde roller veya kapsamlar olmadığında bir özel durum oluşturur:

System.UnauthorizedAccessException: IDW10201: Neither scope or roles claim was found in the bearer token.

Bu özel durumu önlemek için yapılandırma özelliğini true appsettings.json veya program aracılığıyla olarak ayarlayınAllowWebApiToBeAuthorizedByACL.

{
 "AzureAD"
 {
  // other properties
  "AllowWebApiToBeAuthorizedByACL" : true,
  // other properties
 }
}

olarak ayarlarsanız AllowWebApiToBeAuthorizedByACL true, ACL mekanizmasını güvence altına almak sizin sorumluluğunuzdadır.

Sonraki adımlar

• Aşağıdaki çok bölümlü öğretici serisinde kullanıcıların oturumunu kuran bir ASP.NET Core web uygulaması oluşturarak daha fazla bilgi edinin

• Microsoft kimlik platformu web API'si örneklerini keşfetme