Share via

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

  • Makale

Erişim belirteçleri istemcilerin Azure tarafından korunan web API'lerini güvenli bir şekilde çağırmasını sağlar. 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 belirteci alındıktan sonra ö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.

Belirteçleri alırken kapsamlar

Kapsamlar , bir web API'sinin istemci uygulamalarının erişim isteyebileceği izinlerdir. İ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ı biçiminde <app ID URI>/<scope>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://00001111-aaaa-2222-bbbb-3333cccc4444/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 ile eşler https://graph.microsoft.com/User.Readve 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 eğik çizgi/ (aud) bekler. Bu durumda, kapsamı olarak https://management.core.windows.net//user_impersonationgeçirin ve çift eğik çizgi ()// ekleyin.

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

11111111-1111-1111-1111-111111111111/api.read

İpucu

Aşağı akış kaynağı sizin denetiminizde değilse, erişim belirtecini kaynağa geçirirken hata alırsanız 401 farklı kapsam değeri biçimlerini (örneğin düzen 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. Bu tür dinamik kapsamlar , kullanıcılarınızın kapsamlara artımlı onay sağlamasına olanak sağlar.

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

Belirteçleri sessizce alma (önbellekten)

MSAL bir belirteç önbelleği (veya gizli istemci uygulamaları için iki önbellek) tutar ve alındıktan sonra bir belirteci önbelleğe alır. Çoğu durumda, sessizce belirteç almaya çalışmak, önbellekteki bir belirteci temel alan daha fazla kapsama sahip başka bir belirteç alır. 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 özel durumu döndürüyorsa, başka yollarla belirteç almayı deneyin.

Sessizce belirteç almaya çalışmamanızı istediğiniz iki akış vardır:

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

  • Özelleştirilmiş serileştirme ile belirteç önbelleğiyle gizli bir istemci uygulamasının örneğini oluşturun.
  • Yetkilendirme kodu akışını kullanarak belirteci alma

Belirteç alma

Belirteç alma yöntemi, bir genel istemci mi yoksa gizli istemci uygulaması mı olduğuna bağlıdır.

Genel 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ü uygulaması bir etki alanına veya Azure'a katılmış bir Windows bilgisayarda çalışıyorsa, tümleşik Windows kimlik doğrulamasını (IWA/Kerberos) kullanarak oturum açmış kullanıcı için 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 belirteç alın. Kullanıcıya bir URL ve kod sağlanır. Bu url, daha sonra başka bir cihazdaki bir web tarayıcısına gider ve 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;

  • İstemci kimlik bilgileri akışını kullanarak kullanıcının değil uygulamanın kendisi için 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 api çağırmak için web API'sinin adına (OBO) akışını kullanın. Uygulama, kullanıcı onayını (örneğin SAML veya JWT belirteci) temel alan bir belirteç almak için istemci kimlik bilgileriyle 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 Bağlan uygulaması genellikle kullanıcının OpenID Bağlan 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.

Kimlik doğrulama sonuçları

İ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 aşağıdakileri kullanıma sunar:

  • Kaynaklara erişmek için web API'sinin erişim belirteci. Bu dize genellikle Base64 ile kodlanmış bir JWT'dir, ancak istemci hiçbir zaman erişim belirtecinin içine bakmamalıdır. Biçimin kararlı kalacağı garanti edilmez ve kaynak için şifrelenebilir. Kişiler istemcideki erişim belirteci içeriğine bağlı olarak kod yazmak en yaygın hata kaynaklarından ve istemci mantığı bozulmasından biridir.
  • Kullanıcının kimlik belirteci (JWT).
  • Belirtecin süresinin dolmasına ilişkin tarih/saati belirten belirteç süre sonu.
  • Kiracı kimliği, kullanıcının bulunduğu kiracıyı içerir. Konuk kullanıcılar için (Microsoft Entra B2B senaryoları), kiracı kimliği benzersiz kiracı değil konuk kiracıdır. 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.

Günümüzde çoğu arka plan işlemi, kimlik doğrulaması veya yeniden kimlik doğrulaması için mevcut olmadan kullanıcının verileriyle çalışması gerektiğinde uygulama izinlerini kullanır. 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

Ayrıca bkz.

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