Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanarak belirteçleri alma ve önbelleğe alma

Access tokens enable clients to securely call web APIs protected by Azure. Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanarak belirteç almanın çeşitli yolları vardır. Bazıları bir web tarayıcısı üzerinden kullanıcı etkileşimi gerektirirken, bazıları kullanıcı etkileşimi gerektirmez. Genellikle belirteç almak için kullanılan yöntem, uygulamanın bir genel istemci uygulaması (masaüstü veya mobil) veya gizli bir istemci uygulaması (web uygulaması, web API'si veya daemon uygulaması) olmasına bağlıdır.

MSAL, bir belirteç alındıktan sonra onu önbelleğe alır. Uygulama kodunuz, başka yollarla belirteç almayı denemeden önce önbellekten sessizce belirteç almayı denemelidir.

Hesapları önbellekten kaldırarak belirteç önbelleğini de temizleyebilirsiniz. Ancak bu, tarayıcıda bulunan oturum tanımlama bilgisini kaldırmaz.

Jetonlar alındığında kapsamlar

Scopes are the permissions that a web API exposes that client applications can request access to. İstemci uygulamaları, web API'lerine erişmek üzere belirteçler almak üzere kimlik doğrulama isteklerinde bulunurken bu kapsamlar için kullanıcının onayını istemektedir. MSAL, Microsoft kimlik platformu API'lere erişmek için belirteçler almanızı sağlar. v2.0 protokolü, isteklerde kaynak yerine kapsamları kullanır. Web API'sinin kabul edilen belirteç sürümünü yapılandırmasına bağlı olarak, v2.0 uç noktası erişim belirtecini MSAL'ye döndürür.

MSAL'nin belirteç alma yöntemlerinden birkaçı bir scopes parametre gerektirir. scopes parametresi, istenen izinleri ve istenen kaynakları bildiren dizelerin listesidir. İyi bilinen kapsamlar Microsoft Graph izinleridir.

Web API'si için istek kapsamları

Uygulamanızın bir kaynak API'si için belirli izinlere sahip bir erişim belirteci istemesi gerektiğinde, API'nin uygulama kimliği URI'sini içeren kapsamları, <app ID URI>/<scope> biçiminde geçirin.

Farklı kaynaklar için bazı örnek kapsam değerleri:

  • Microsoft Graph API'si: https://graph.microsoft.com/User.Read
  • Özel web API'si: api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api.read

Kapsam değerinin biçimi, erişim belirtecini alan kaynağa (API) ve kabul edilen talep değerlerine aud bağlı olarak değişir.

Yalnızca Microsoft Graph için, user.read kapsamı https://graph.microsoft.com/User.Read ile eşleşir ve her iki kapsam biçimi de birbirinin yerine kullanılabilir.

Azure Resource Manager API'si (https://management.core.windows.net/) gibi bazı web API'leri, erişim belirtecinin hedef kitle talebinde sonda bir eğik çizgi (/) bekler. Bu durumda, kapsamı https://management.core.windows.net//user_impersonation olarak geçirin ve çift eğik çizgiyi (//) ekleyin.

Diğer API'ler, kapsam değerine bir düzen veya ana bilgisayar dahil edilmemesini gerektirebilir ve yalnızca uygulama kimliği (GUID) ve kapsam adını bekleyebilir, örneğin:

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Tip

Aşağı akış kaynağı sizin denetiminizde değilse ve erişim belirtecini kaynağa geçirirken 401 veya başka hatalar alırsanız, farklı kapsam değeri biçimlerini (örneğin şema ve konak ile/konak olmadan) denemeniz gerekebilir.

Uygulamanız veya gereksinimleri tarafından sağlanan özellikler değiştikçe, kapsam parametresini kullanarak gerektiğinde ek izinler isteyebilirsiniz. Such dynamic scopes allow your users to provide incremental consent to scopes.

Örneğin, kullanıcıda oturum açabilirsiniz ancak başlangıçta herhangi bir kaynağa erişimini reddedebilirsiniz. Daha sonra, jeton edinme yönteminde takvim kapsamını isteyerek ve kullanıcının onayını alarak takvimlerini görüntüleme olanağı sağlayabilirsiniz. Örneğin, https://graph.microsoft.com/User.Read ve https://graph.microsoft.com/Calendar.Read kapsamlarını isteyerek.

Jetonları sessizce alma (önbellekten)

MSAL, bir belirteç önbelleği (veya gizli istemci uygulamaları için iki önbellek) tutar ve elde edildiğinde bu belirteci önbellekte saklar. Çoğu durumda, sessizce bir belirteç elde etmeye çalışmak, önbellekteki bir belirtece dayanarak daha geniş kapsamlı başka bir belirteç edinmeye yol açar. Ayrıca, süresi dolmaya yaklaştığında (belirteç önbelleği de yenileme belirteci içerdiğinden) belirteci yenileyebilir.

Uygulama kaynak kodu önce önbellekten sessizce bir belirteç almayı denemelidir. Yöntem çağrısı "UI gerekli" hatası veya istisnası döndürüyorsa, başka yöntemlerle bir belirteç elde etmeyi deneyin.

There are two flows where you should not attempt to silently acquire a token:

OpenID Connect yetkilendirme kodu akışını kullanan web uygulamaları için, denetleyicilerde önerilen desen şu şekildedir:

  • Özelleştirilmiş serileştirme işlemi ile bir belirteç önbelleğine sahip gizli bir istemci uygulaması örneği oluşturun.
  • Yetkilendirme kodu akışını kullanarak belirteci elde etme

Acquiring tokens

Belirteç alma yöntemi, genel istemci veya özel istemci uygulaması olup olmamasına bağlıdır.

Herkese açık istemci uygulamaları

Genel istemci uygulamalarında (masaüstü ve mobil), şunları yapabilirsiniz:

  • Kullanıcının bir kullanıcı arabirimi veya açılır pencere aracılığıyla oturum açmasını sağlayarak belirteçleri etkileşimli olarak alın.
  • Masaüstü uygulamanız bir etki alanına veya Azure'a katılmış bir Windows bilgisayarda çalışıyorsa, oturum açmış kullanıcı için tümleşik Windows kimlik doğrulaması (IWA/Kerberos) kullanarak sessizce bir belirteç alın.
  • .NET Framework masaüstü istemci uygulamalarında kullanıcı adı ve parola içeren bir belirteç alın (önerilmez). Gizli istemci uygulamalarında kullanıcı adı/parola kullanmayın.
  • Web tarayıcısı olmayan cihazlarda çalışan uygulamalarda cihaz kodu akışı üzerinden bir belirteç alın. Kullanıcıya bir URL ve kod verilir. Daha sonra, kullanıcı başka bir cihazdaki bir web tarayıcısına giderek bu kodu girer ve oturum açar. Microsoft Entra Id daha sonra tarayıcısız cihaza bir belirteç gönderir.

Gizli istemci uygulamaları

Gizli istemci uygulamaları (web uygulaması, web API'si veya Windows hizmeti gibi bir daemon uygulaması) için;

  • Uygulamanın kendisi için, kullanıcı için değil, istemci kimlik bilgileri akışını kullanarak belirteçler alın. Bu teknik, belirli bir kullanıcıyı değil, genel olarak kullanıcıları işleyen araçları veya araçları eşitlemek için kullanılabilir.
  • Kullanıcı adına bir API çağırmak için web API'si üzerinde (OBO) akışını kullanın. Kullanıcı onayına (örneğin SAML veya JWT belirteci) dayanarak bir belirteç almak için uygulama, istemci kimlik bilgileri kullanılarak tanımlanır. Bu akış, hizmet-hizmet çağrılarında belirli bir kullanıcının kaynaklarına erişmesi gereken uygulamalar tarafından kullanılır. Belirteçler kullanıcı bazında değil oturum temelinde önbelleğe alınmalıdır.
  • Kullanıcı yetkilendirme isteği URL'si aracılığıyla oturum açtığında web uygulamalarında yetkilendirme kodu akışını kullanarak belirteçleri alın. OpenID Connect uygulaması genellikle kullanıcının OpenID Connect kullanarak oturum açmasını ve ardından kullanıcı adına web API'lerine erişmesini sağlayan bu mekanizmayı kullanır. Belirteçler bir kullanıcı veya oturum temelinde önbelleğe alınabilir. Belirteçleri kullanıcı bazında önbelleğe alırsanız, Microsoft Entra Id'nin Koşullu Erişim ilkelerinin durumunu sık sık denetleyebilmesi için oturum ömrünü sınırlamanızı öneririz.

Authentication results

İstemciniz bir erişim belirteci istediğinde Microsoft Entra Id, erişim belirteciyle ilgili meta verileri içeren bir kimlik doğrulama sonucu da döndürür. Bu bilgiler, erişim belirtecinin süre sonu süresini ve geçerli olduğu kapsamları içerir. Bu veriler, uygulamanızın erişim belirtecinin kendisini ayrıştırmak zorunda kalmadan erişim belirteçlerinin akıllı önbelleğe alınmasını sağlar. Kimlik doğrulama sonucu şunu gösterir:

  • The access token for the web API to access resources. This string is usually a Base64-encoded JWT, but the client should never look inside the access token. Biçimin kararlı kalacağı garanti edilmez ve kaynak için şifrelenebilir. İstemcideki erişim belirteci içeriğine bağlı olarak kod yazan kişiler en yaygın hata kaynaklarından ve istemci mantığı bozulmasından biridir.
  • The ID token for the user (a JWT).
  • Belirtecin sona erme tarihi/saati, belirtecin ne zaman sona ereceğini gösterir.
  • Kiracı kimliği, kullanıcının bulunduğu kiracıyı içerir. Konuk kullanıcılar için (Microsoft Entra B2B senaryolarında), kiracı kimliği benzersiz kiracı yerine konuk kiracıyı ifade eder. Belirteç bir kullanıcı adına teslim edildiğinde, kimlik doğrulama sonucu bu kullanıcı hakkındaki bilgileri de içerir. Belirteçlerin kullanıcı olmadan istendiği gizli istemci akışları için (uygulama için), bu kullanıcı bilgileri null değeridir.
  • Belirtecin verildiği kapsamlar.
  • Kullanıcının benzersiz kimliği.

(Gelişmiş) Arka plan uygulamaları ve hizmetlerinde kullanıcının önbelleğe alınmış belirteçlerine erişme

Arka plan uygulamalarının, API'lerinin ve hizmetlerinin yokluklarında kullanıcılar adına işlem yapmaya devam etmek için erişim belirteci önbelleğini kullanmasına izin vermek için MSAL'nin belirteç önbelleği uygulamasını kullanabilirsiniz. Bunu yapmak özellikle arka plan uygulamalarının ve hizmetlerinin, kullanıcı ön uç web uygulamasından çıktıktan sonra kullanıcı adına çalışmaya devam etmesi gerekiyorsa yararlıdır.

Today, most background processes use application permissions when they need to work with a user's data without them being present to authenticate or reauthenticate. Uygulama izinleri genellikle ayrıcalıkların yükseltilmesini gerektiren yönetici onayı gerektirdiğinden, geliştirici kullanıcının uygulaması için başlangıçta onayladığı izinlerin ötesinde bir izin almayı amaçlamadığı için gereksiz uyuşmalarla karşılaşılır.

GitHub'da bu kod örneği, MSAL'nin belirteç önbelleğine arka plan uygulamalarından erişerek bu gereksiz sürtüşmelerin nasıl önlendiğini gösterir:

Arka plan uygulamalarından, API'lerden ve hizmetlerden oturum açmış kullanıcının belirteç önbelleğine erişme

See also

MSAL tarafından desteklenen platformların bazılarında, söz konusu platformun kitaplığının belgelerinde belirteç önbelleğiyle ilgili ek bilgiler bulunur. For example:

  • Last updated on