Talep tabanlı kimliklerle çalışmaWork with claims-based identities

GitHub Örnek kodGitHub Sample code

Azure AD'de talepClaims in Azure AD

Azure AD, bir kullanıcı oturum açtığında, kullanıcı hakkında talepler kümesi içeren bir kimlik belirteci gönderir.When a user signs in, Azure AD sends an ID token that contains a set of claims about the user. Bir talep basitçe bilgi, bir anahtar/değer çifti ifade edilen bir parçasıdır.A claim is simply a piece of information, expressed as a key/value pair. Örneğin, email=bob@contoso.com.For example, email=bob@contoso.com. Talepleri olan bir veren — bu durumda, Azure AD — kullanıcının kimliğini doğrular ve talepleri oluşturan varlık olduğu.Claims have an issuer — in this case, Azure AD — which is the entity that authenticates the user and creates the claims. Veren kişiye güvendiğiniz çünkü taleplere güvenmesini.You trust the claims because you trust the issuer. (Veren güvenmiyorsanız buna karşılık, talepleri güvenmediğiniz!)(Conversely, if you don't trust the issuer, don't trust the claims!)

Yüksek düzeyde:At a high level:

  1. Kullanıcının kimliğini doğrular.The user authenticates.
  2. IDP'nin talepler kümesi gönderir.The IDP sends a set of claims.
  3. Uygulama normalleştirir veya talepleri (isteğe bağlı) artırmaktadır.The app normalizes or augments the claims (optional).
  4. Uygulama talepleri yetkilendirme kararları vermek için kullanır.The app uses the claims to make authorization decisions.

Openıd Connect size talepler kümesi tarafından denetlenir kapsam parametresi kimlik doğrulama isteği.In OpenID Connect, the set of claims that you get is controlled by the scope parameter of the authentication request. Ancak, Azure AD talep Openıd Connect aracılığıyla sınırlı bir dizi yayınlar. bkz: desteklenen belirteç ve talep türleri.However, Azure AD issues a limited set of claims through OpenID Connect; see Supported Token and Claim Types. Kullanıcı hakkında daha fazla bilgi istiyorsanız, Azure AD Graph API'si kullanmanız gerekir.If you want more information about the user, you'll need to use the Azure AD Graph API.

Bir uygulama genellikle oluşturur, Azure AD'den talepleri bazıları şunlardır:Here are some of the claims from Azure AD that an app might typically care about:

Kimlik belirteci içinde talep türüClaim type in ID token AçıklamaDescription
audaud Kimin belirteç için verilmiş.Who the token was issued for. Bu uygulamanın istemci kimliğini olacaktırThis will be the application's client ID. Genellikle, ara yazılımı otomatik olarak doğrular çünkü bu talep hakkında endişelenmeniz gerekmez.Generally, you shouldn't need to worry about this claim, because the middleware automatically validates it. Örnek: "91464657-d17a-4327-91f3-2ed99386406f"Example: "91464657-d17a-4327-91f3-2ed99386406f"
gruplargroups Kullanıcının üyesi olduğu Azure AD gruplarının listesi.A list of Azure AD groups of which the user is a member. Örnek: ["93e8f556-8661-4955-87b6-890bc043c30f", "fc781505-18ef-4a31-a7d5-7d931d7b857e"]Example: ["93e8f556-8661-4955-87b6-890bc043c30f", "fc781505-18ef-4a31-a7d5-7d931d7b857e"]
ISSiss Veren OIDC belirtecin.The issuer of the OIDC token. Örnek: https://sts.windows.net/b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4/Example: https://sts.windows.net/b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4/
namename Kullanıcının görünen adı.The user's display name. Örnek: "Alice A."Example: "Alice A."
OIDoid Azure AD'de kullanıcı nesnesi tanımlayıcısı.The object identifier for the user in Azure AD. Bu değer sabittir ve yeniden kullanılabilir olmayan kullanıcı kimliğidir.This value is the immutable and non-reusable identifier of the user. Bu değer, e-posta değil, kullanıcılar için benzersiz bir tanımlayıcı olarak kullanın. e-posta adreslerini değiştirebilirsiniz.Use this value, not email, as a unique identifier for users; email addresses can change. Uygulamanızı Azure AD Graph API kullanıyorsanız, nesne kimliği profil bilgileri sorgulamak için kullanılan bu değer ' dir.If you use the Azure AD Graph API in your app, object ID is that value used to query profile information. Örnek: "59f9d2dc-995a-4ddf-915e-b3bb314a7fa4"Example: "59f9d2dc-995a-4ddf-915e-b3bb314a7fa4"
rolroles Kullanıcının uygulama rollerini listesi.A list of app roles for the user. Örnek: ["SurveyCreator"]Example: ["SurveyCreator"]
TIDtid Kiracı kimliğiTenant ID. Bu Kiracı için benzersiz bir tanımlayıcı Azure AD'de değerdir.This value is a unique identifier for the tenant in Azure AD. Örnek: "b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4"Example: "b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4"
unique_nameunique_name Kullanıcı bir insan tarafından okunabilir görünen adı.A human readable display name of the user. Örnek: "alice@contoso.com"Example: "alice@contoso.com"
UPNupn Kullanıcı asıl adı.User principal name. Örnek: "alice@contoso.com"Example: "alice@contoso.com"

Bu tablo, kimliği belirteçteki göründükleri gibi talep türlerini listeler.This table lists the claim types as they appear in the ID token. Asıl kullanıcı için talepleri koleksiyon doldurduğunda ASP.NET Core, bazı talep türleri Openıd Connect ara yazılımını dönüştürür:In ASP.NET Core, the OpenID Connect middleware converts some of the claim types when it populates the Claims collection for the user principal:

  • OID > http://schemas.microsoft.com/identity/claims/objectidentifieroid > http://schemas.microsoft.com/identity/claims/objectidentifier
  • TID > http://schemas.microsoft.com/identity/claims/tenantidtid > http://schemas.microsoft.com/identity/claims/tenantid
  • unique_name > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameunique_name > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • UPN > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upnupn > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

Talep dönüştürmeleriClaims transformations

Kimlik doğrulama akışı sırasında IDP'den alma talepleri değiştirmek isteyebilirsiniz.During the authentication flow, you might want to modify the claims that you get from the IDP. ASP.NET Core, talep dönüştürme içine gerçekleştirebileceğiniz AuthenticationValidated Openıd Connect ara yazılımını olay.In ASP.NET Core, you can perform claims transformation inside of the AuthenticationValidated event from the OpenID Connect middleware. (Bkz Kimlik doğrulama olayları.)(See Authentication events.)

Sırasında eklediğiniz herhangi bir talep AuthenticationValidated oturum kimlik doğrulama tanımlama bilgisinde depolanır.Any claims that you add during AuthenticationValidated are stored in the session authentication cookie. Bunlar geri Azure AD'ye itilir yok.They don't get pushed back to Azure AD.

Talep dönüştürme bazı örnekleri aşağıda verilmiştir:Here are some examples of claims transformation:

  • Talep normalleştirme, veya kullanıcılar arasında tutarlı iddiasında.Claims normalization, or making claims consistent across users. Farklı talep türlerini yönelik benzer bilgileri kullanabilir. birden çok Idp'yi gelen talep alıyorsanız bu özellikle geçerlidir.This is particularly relevant if you are getting claims from multiple IDPs, which might use different claim types for similar information. Örneğin, Azure AD, kullanıcının e-posta içeren "upn" talebi gönderir.For example, Azure AD sends a "upn" claim that contains the user's email. Diğer Idp'yi "email" talep gönderebilir.Other IDPs might send an "email" claim. Aşağıdaki kod bir "email" talep "upn" talebi dönüştürür:The following code converts the "upn" claim into an "email" claim:

    var email = principal.FindFirst(ClaimTypes.Upn)?.Value;
    if (!string.IsNullOrWhiteSpace(email))
    {
        identity.AddClaim(new Claim(ClaimTypes.Email, email));
    }
    
  • Ekleme varsayılan talep değerlerini bulunmayan talepler için — Örneğin, bir kullanıcının varsayılan rol atama.Add default claim values for claims that aren't present — for example, assigning a user to a default role. Bazı durumlarda bu, yetkilendirme mantığının kolaylaştırabilir.In some cases this can simplify authorization logic.

  • Ekleme özel talep türleri uygulamaya özgü bilgilerle kullanıcı.Add custom claim types with application-specific information about the user. Örneğin, bir veritabanında kullanıcı hakkında bazı bilgiler depolayabilir.For example, you might store some information about the user in a database. Kimlik doğrulaması bileti için bir özel talep bilgiler ekleyebilirsiniz.You could add a custom claim with this information to the authentication ticket. Böylece, yalnızca bir kez oturum açma oturumu başına veritabanından almak talep bir tanımlama bilgisinde depolanır.The claim is stored in a cookie, so you only need to get it from the database once per login session. Öte yandan, ayrıca veritabanı aramaları karşı tanımlama bilgisi boyutu arasındaki dengelemeyi dikkate almanız gereken şekilde son derece büyük bir tanımlama bilgisi oluşturmaktan kaçının istiyorsunuz.On the other hand, you also want to avoid creating excessively large cookies, so you need to consider the trade-off between cookie size versus database lookups.

Kimlik doğrulaması akışı tamamlandıktan sonra talepler kullanılabilir HttpContext.User.After the authentication flow is complete, the claims are available in HttpContext.User. Bu noktada, bunları bir salt okunur koleksiyon ele almanız—Örneğin, yetkilendirme kararları vermek için kullanılıyor.At that point, you should treat them as a read-only collection—for example, using them to make authorization decisions.

Veren doğrulamaIssuer validation

Openıd Connect verenin talep ("ISS") kimlik belirteci veren IDP tanımlar.In OpenID Connect, the issuer claim ("iss") identifies the IDP that issued the ID token. OIDC kimlik doğrulaması akışı parçası verenin talep, fiili sertifikayı verenle eşleşiyor doğrulamaktır.Part of the OIDC authentication flow is to verify that the issuer claim matches the actual issuer. OIDC ara yazılım sizin yerinize çözer.The OIDC middleware handles this for you.

Azure AD'de veren değerini AD Kiracı başına benzersiz olan (https://sts.windows.net/<tenantID>).In Azure AD, the issuer value is unique per AD tenant (https://sts.windows.net/<tenantID>). Bu nedenle, bir uygulamanın Kiracı uygulamaya oturum açmasına izin veren temsil ettiğinden emin olmak için ek bir denetim yapmanız gerekir.Therefore, an application should do an additional check, to make sure the issuer represents a tenant that is allowed to sign in to the app.

Tek kiracılı bir uygulama için yalnızca veren kendi kiracınızı olduğunu kontrol edebilirsiniz.For a single-tenant application, you can just check that the issuer is your own tenant. Aslında, OIDC ara yazılım bunu otomatik olarak varsayılan olarak yapar.In fact, the OIDC middleware does this automatically by default. Çok kiracılı bir uygulamada farklı kiracılar için karşılık gelen birden çok verenler için izin vermeniz gerekir.In a multitenant app, you need to allow for multiple issuers, corresponding to the different tenants. Kullanılacak bir genel yaklaşım şöyledir:Here is a general approach to use:

  • OIDC ara yazılımı seçenekleri kümesi ValidateIssuer false.In the OIDC middleware options, set ValidateIssuer to false. Bu, otomatik denetimini devre dışı bırakır.This turns off the automatic check.
  • Bir kiracı kaydolduğunda, kiracının ve veren kullanıcınızın DB depolayın.When a tenant signs up, store the tenant and the issuer in your user DB.
  • Veritabanındaki veren bir kullanıcı oturum açtığı her arayın.Whenever a user signs in, look up the issuer in the database. Verici bulunamazsa, bu Kiracı kaydolan henüz anlamına gelir.If the issuer isn't found, it means that tenant hasn't signed up. Bir kayıt sayfasını için yönlendirebilirsiniz.You can redirect them to a sign up page.
  • Belirli kiracılara bloke listeye; Örneğin, müşteriler için bunların abonelik ödeme kaydetmedi.You could also blacklist certain tenants; for example, for customers that didn't pay their subscription.

Daha ayrıntılı bir açıklaması için kaydolma ve Kiracı ekleme çok müşterili uygulamalarda.For a more detailed discussion, see Sign-up and tenant onboarding in a multitenant application.

Yetkilendirme için taleplerini kullanmaUsing claims for authorization

Talepleri ile bir kullanıcının kimliğini artık tek parça bir varlık değil.With claims, a user's identity is no longer a monolithic entity. Örneğin, bir kullanıcı bir e-posta adresi, telefon numarası, Doğum günü, cinsiyet, vb. olabilir. Belki de kullanıcının IDP tüm bu bilgileri depolar.For example, a user might have an email address, phone number, birthday, gender, etc. Maybe the user's IDP stores all of this information. Ancak, kullanıcı kimlik doğrulaması sırasında genellikle bir alt kümesini bu talep olarak alırsınız.But when you authenticate the user, you'll typically get a subset of these as claims. Bu modelde, kullanıcının kimliğini yalnızca talep paketidir.In this model, the user's identity is simply a bundle of claims. Bir kullanıcı hakkında yetkilendirme kararları, belirli bir talep kümeleri için görünür.When you make authorization decisions about a user, you will look for particular sets of claims. Diğer bir deyişle, sorunun "X kullanıcı eylemlerini gerçekleştirebilir Y" sonuç olarak "Mu X sahip kullanıcı talebi Z" olur.In other words, the question "Can user X perform action Y" ultimately becomes "Does user X have claim Z".

Talep denetlemek için bazı temel düzenlerden aşağıda verilmiştir.Here are some basic patterns for checking claims.

  • Kullanıcının belirli bir değeri ile belirli bir talep olduğunu denetlemek için:To check that the user has a particular claim with a particular value:

    if (User.HasClaim(ClaimTypes.Role, "Admin")) { ... }
    

    Bu kod, kullanıcı bir "Yönetici" değeriyle rol talep olup olmadığını denetler.This code checks whether the user has a Role claim with the value "Admin". Doğru kullanıcının hiçbir rol talep veya birden çok rol talepleri sahip olduğu durumu işler.It correctly handles the case where the user has no Role claim or multiple Role claims.

    ClaimTypes yaygın olarak kullanılan talep türleri için sabitler sınıfı tanımlar.The ClaimTypes class defines constants for commonly used claim types. Ancak, herhangi bir dize değeri için talep türünü kullanabilirsiniz.However, you can use any string value for the claim type.

  • Burada bir değer en fazla olmasını beklediğiniz bir talep türü için tek bir değer almak için:To get a single value for a claim type, when you expect there to be at most one value:

    string email = User.FindFirst(ClaimTypes.Email)?.Value;
    
  • Bir talep türü için tüm değerleri almak için:To get all the values for a claim type:

    IEnumerable<Claim> groups = User.FindAll("groups");
    

Daha fazla bilgi için çok müşterili uygulamalarda rol tabanlı ve kaynak tabanlı yetkilendirme.For more information, see Role-based and resource-based authorization in multitenant applications.

SonrakiNext