Aracılığıyla paylaş

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. Genel olarak, belirteç almak için kullanılan yöntem, uygulamanın masaüstü veya mobil uygulama gibi genel bir istemci uygulaması mı yoksa web uygulaması, web API'si veya daemon uygulaması gibi gizli bir istemci uygulaması mı olduğuna 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.

Ayrıca, hesapları önbellekten kaldırarak elde edilen 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, geliştiriciler için Azure AD'ye (v1.0) ve Microsoft kimlik platformu API'lerine erişmek için belirteçler almanıza olanak tanır. 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.

MSAL'de v1.0 kaynaklarına erişmek de mümkündür. Daha fazla bilgi için bkz . v1.0 uygulamasının kapsamları.

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://11111111-1111-1111-1111-111111111111/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.

Bununla birlikte, sessizce belirteç almaya çalışmamanızı sağlayan iki akış vardır:

  • Kullanıcı belirteci önbelleğini değil uygulama belirteci önbelleğini kullanan istemci kimlik bilgileri akışı. Bu yöntem, güvenlik belirteci hizmetine (STS) istek göndermeden önce uygulama belirteci önbelleğini doğrulamayı üstlenir.
  • Kullanıcının oturumunu açıp daha fazla kapsama onay vermelerini sağlayarak uygulamanın aldığı bir kodu kullandığından, web uygulamalarında yetkilendirme kodu akışı. Bir hesap değil kod parametre olarak geçirildiğinden yöntemi, hizmete bir çağrı çağıran kodu kullanmadan önce önbelleğe bakamaz.

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

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

Genel istemci uygulamaları

Masaüstü ve mobil uygulamalar gibi genel istemci uygulamalarında ş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. Ardından Azure AD, 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.
  • 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 bu mekanizmayı kullanır. Bu mekanizma, kullanıcının Open ID bağlantısı kullanarak oturum açmasına ve ardından kullanıcı adına web API'lerine erişmesine olanak tanır.

Kimlik doğrulama sonuçları

İstemciniz erişim belirteci istediğinde Azure AD, erişim belirteci hakkındaki 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 (Azure AD 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.