Share via

Talep sınamaları, talep istekleri ve istemci özellikleri

  • Makale

Talep sınaması , bir istemci uygulaması tarafından gönderilen erişim belirtecinin talepleri yetersiz olduğunu belirten bir API'den gönderilen yanıttır. Bunun nedeni belirtecin söz konusu API için ayarlanan Koşullu Erişim ilkelerini karşılamaması veya erişim belirtecinin iptal edilmiş olması olabilir.

İstemci uygulaması tarafından kullanıcıyı kimlik sağlayıcısına geri yönlendirerek karşılanmamış diğer gereksinimleri karşılayan taleplere sahip yeni bir belirteç almak için bir talep isteği yapılır.

Sürekli Erişim Değerlendirmesi (CAE) ve Koşullu Erişim kimlik doğrulaması bağlamı gibi gelişmiş güvenlik özellikleri kullanan uygulamaların talep sınamalarını ele almak için hazırlanması gerekir.

Uygulamanız, microsoft graph gibi popüler hizmetlerden talep güçlükleri alır ancak hizmete yaptığı çağrılarda istemci özelliklerini bildirir.

Talep sınaması üst bilgi biçimi

Talep sınaması, api'ye sunulan erişim www-authenticate belirteci yetkili olmadığında api tarafından döndürülen üst bilgi olarak bir yönergedir ve bunun yerine doğru özelliklere sahip yeni bir erişim belirteci gerekir. Talep sınaması birden çok bölümden oluşur: yanıtın HTTP durum kodu ve www-authenticate kendisinin birden çok parçası olan ve bir talep yönergesi içermesi gereken üst bilgi.

Bir örnek aşağıda verilmiştir:

HTTP 401; Unauthorized

www-authenticate =Bearer realm="", authorization_uri="https://login.microsoftonline.com/common/oauth2/authorize", error="insufficient_claims", claims="eyJhY2Nlc3NfdG9rZW4iOnsiYWNycyI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlIjoiY3AxIn19fQ=="

HTTP Durum Kodu: 401 Yetkisiz olmalıdır.

www-authenticate yanıt üst bilgisi :

Parametre Gerekli/isteğe bağlı Açıklama
Authentication type Zorunlu Taşıyıcı olmalı .
Bölge İsteğe bağlı Erişilmekte olan kiracı kimliği veya kiracı etki alanı adı (örneğin, microsoft.com). Kimlik doğrulamasının ortak uç nokta üzerinden geçmesi durumunda boş bir dize olmalıdır.
authorization_uri Zorunlu Gerekirse etkileşimli kimlik doğrulamasının gerçekleştirilebileceği uç noktanın authorize URI'sini. Bölge içinde belirtilirse, kiracı bilgileri authorization_uri dahil edilmelidir. Bölge boş bir dizeyse, authorization_uri ortak uç noktaya karşı olmalıdır.
error Zorunlu Talep sınaması oluşturulması gerektiğinde "insufficient_claims" olmalıdır.
claims Hata "insufficient_claims" olduğunda gereklidir. Temel 64 kodlanmış talep isteğini içeren tırnak içine alınmış bir dize. Talep isteği, JSON nesnesinin en üst düzeyinde "access_token" için talep istemelidir. Değer (istenen talepler) bağlama bağımlı olacak ve bu belgenin ilerleyen bölümlerinde belirtilecektir. Boyut nedenleriyle, bağlı olan taraf uygulamalar temel 64 kodlamadan önce JSON'ı küçültmeLIDIR. Yukarıdaki örneğin ham JSON değeridir {"access_token":{"acrs":{"essential":true,"value":"cp1"}}}.

401 yanıtı birden www-authenticate fazla üst bilgi içerebilir. Önceki tablodaki tüm alanlar aynı www-authenticate üst bilgi içinde yer almalıdır. Talep www-authenticate sınamasını içeren üst bilgi başka alanlar içerebilir . Üst bilgideki alanlar sıralanmamış. RFC 7235'e göre, her parametre adı kimlik doğrulama düzeni sınaması başına yalnızca bir kez gerçekleşmelidir.

Talep isteği

Bir uygulama talep sınaması aldığında, önceki erişim belirtecinin artık geçerli kabul edilmediğini gösterir. Bu senaryoda, uygulamanın belirteci herhangi bir yerel önbellekten veya kullanıcı oturumundan temizlemesi gerekir. Ardından, OAuth 2.0 yetkilendirme kodu akışını, karşılanmamış diğer gereksinimleri karşılayacak bir talep parametresiyle kullanarak yeni bir belirteç almak için oturum açmış kullanıcıyı Microsoft Entra Id'ye yeniden yönlendirmesi gerekir.

Bir örnek aşağıda verilmiştir:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22acrs%22%3A%7B%22essential%22%3Atrue%2C%22value%22%3A%22c1%22%7D%7D%7D

Talep sınaması, bir belirteç başarıyla alınana kadar bir Microsoft Entra /authorize uç noktasına yapılan tüm çağrıların bir parçası olarak geçirilmelidir. Belirteç alındıktan sonra artık gerekli değildir.

Claims parametresini doldurmak için geliştirici şunları yapmak zorunda:

  1. Daha önce alınan base64 dizesinin kodunu çözme.
  2. URL ile dizeyi kodlayıp claims parametresine yeniden ekleyin.

Bu akışı tamamlayan uygulama, kullanıcının gerekli koşulları karşıladığını kanıtlayan diğer talepleri içeren bir erişim belirteci alır.

İstemci özellikleri

İstemci özellikleri, Web API'si gibi bir kaynak sağlayıcısının çağıran istemci uygulamasının talep sınamasını anlayıp anlayamayacağını algılamasına ve ardından yanıtını buna göre özelleştirebilmesine yardımcı olur. Bu özellik, tüm API istemcileri talep zorluklarını işleyemediğinde ve önceki bazı sürümlerde farklı bir yanıt beklenmediği durumlarda yararlı olabilir.

Microsoft Graph gibi bazı popüler uygulamalar talep sınamalarını yalnızca çağıran istemci uygulamasının istemci özelliklerini kullanarak bunları işleyebilen bir uygulama olduğunu bildirmesi durumunda gönderir.

Ek trafik veya kullanıcı deneyimi üzerindeki etkilerden kaçınmak için Microsoft Entra ID, açıkça kabul etmediğiniz sürece uygulamanızın talep edilen talepleri işleyebileceğini varsaymaz. Bir uygulama, "cp1" özelliğiyle işlemeye hazır olduğunu bildirmediği sürece talep sınamaları almaz (ve CAE belirteçleri gibi ilgili özellikleri kullanamaz).

İstemci özelliklerini Microsoft Entra Id'ye iletme

Aşağıdaki örnek talep parametresi, bir istemci uygulamasının OAuth 2.0 yetkilendirme kodu akışında microsoft entra kimliğine özelliğini nasıl ilettığını gösterir.

Claims: {"access_token":{"xms_cc":{"values":["cp1"]}}}

MSAL kitaplığını kullanıyorsanız aşağıdaki kodu kullanın:

_clientApp = PublicClientApplicationBuilder.Create(App.ClientId)
 .WithDefaultRedirectUri()
 .WithAuthority(authority)
 .WithClientCapabilities(new [] {"cp1"})
 .Build();

Microsoft.Identity.Web kullananlar yapılandırma dosyasına aşağıdaki kodu ekleyebilir:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": 'Enter_the_Application_Id_Here' 
    "ClientCapabilities": [ "cp1" ],
    // remaining settings...
},

Microsoft Entra Id'ye örnek bir istek görmek için aşağıdaki kod parçacığına bakın:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22xms_cc%22%3A%7B%22values%22%3A%5B%22cp1%22%5D%7D%7D%7D

Talepler için zaten bir yükünüz varsa, bunu mevcut kümeye eklersiniz.

Örneğin, bir Koşul Erişimi kimlik doğrulaması bağlam işleminden aşağıdaki yanıta zaten sahipseniz;

{"access_token":{"acrs":{"essential":true,"value":"c25"}}}

İstemci özelliğini mevcut talep yüküne eklersiniz.

{"access_token":{"xms_cc":{"values":["cp1"]},"acrs":{"essential":true,"value":"c25"}}}

Erişim belirtecinde xms_cc talebi alma

İstemci uygulamalarının talep sınamalarını işleyip işleyemeyeceği hakkında bilgi almak için API uygulayıcısı, uygulama bildiriminde isteğe bağlı talep olarak xms_cc istemelidir.

Erişim belirtecinde "cp1" değerine sahip xms_cc talep, bir istemci uygulamasının talep sınamasını işleyebilen yetkili bir yöntemdir. xms_cc, istemci "xms_cc" ile bir talep isteği gönderse bile erişim belirtecinde her zaman verilmeyen isteğe bağlı bir taleptir. Erişim belirtecinin xms_cc talebi içermesi için kaynak uygulamasının (api uygulayıcısı) uygulama bildiriminde isteğe bağlı talep olarak xms_cc istemesi gerekir. İsteğe bağlı talep olarak istendiğinde, erişim belirtecine yalnızca istemci uygulaması talep isteğinde xms_cc gönderdiğinde xms_cc eklenir. xms_cc talep isteğinin değeri, bilinen bir değerse erişim belirtecindeki xms_cc talebinin değeri olarak eklenir. Şu anda bilinen tek değer cp1'dir.

Değerler büyük/küçük harfe duyarlı ve sıralanmamış değildir. xms_cc talep isteğinde birden fazla değer belirtilirse, bu değerler xms_cc talebin değeri olarak çok değerli bir koleksiyon olur.

Örnek olarak aşağıdaki isteği alın:

{ "access_token": { "xms_cc":{"values":["cp1","foo", "bar"] } }}

Bu, cp1, foo ve çubuk bilinen özelliklerse erişim belirtecinde aşağıdaki kod parçacığının talebine neden olur.

"xms_cc": ["cp1", "foo", "bar"]

İsteğe bağlı xms_cctalep istendikten sonra uygulamanın bildirimi aşağıdaki gibi görünecek şekilde değişir:

"optionalClaims":
{
    "accessToken": [
    {
        "additionalProperties": [],
        "essential": false,
        "name": "xms_cc",
        "source": null
    }],
    "idToken": [],
    "saml2Token": []
}

Ardından API, istemcinin talep sınamasını işleyip işleyemeyeceğine bağlı olarak yanıtlarını özelleştirebilir.

Claim ccClaim = context.User.FindAll(clientCapabilitiesClaim).FirstOrDefault(x => x.Type == "xms_cc");
if (ccClaim != null && ccClaim.Value == "cp1")
{
    // Return formatted claims challenge as this client understands this
}
else
{
    // Throw generic exception
    throw new UnauthorizedAccessException("The caller does not meet the authentication bar to carry our this operation. The service cannot allow this operation");
}

Kod örnekleri

Sonraki adımlar