Uygulamalarınızda Sürekli Erişim Değerlendirmesi özellikli API'leri kullanma

Sürekli Erişim Değerlendirmesi (CAE), erişim belirteçlerinin yaşam süresine bağlı olarak belirteç süre sonunu kullanmak yerine kritik olaylara ve ilke değerlendirmesine göre iptal edilmesini sağlayan bir Microsoft Entra özelliğidir. Bazı kaynak API'leri için risk ve ilke gerçek zamanlı olarak değerlendirildiğinden belirteç ömrünü 28 saate kadar artırabilir. Bu uzun ömürlü belirteçler Microsoft Kimlik Doğrulama Kitaplığı (MSAL) tarafından proaktif olarak yenilenerek uygulamalarınızın dayanıklılığı artırılır.

Bu makalede, uygulamalarınızda CAE özellikli API'lerin nasıl kullanılacağı gösterilmektedir. MSAL kullanmayan uygulamalar CAE kullanmak üzere beyan sınamaları, beyan istekleri ve istemci özellikleri için destek ekleyebilir.

Uygulama ile ilgili hususlar

CAE'yi kullanmak için hem uygulamanızın hem de eriştiği kaynak API'sinin CAE etkin olması gerekir. Ancak kodunuzu CAE özellikli bir kaynak kullanacak şekilde hazırlamak, CAE etkin olmayan API'leri kullanmanızı engellemez.

Bir kaynak API'si CAE uygularsa ve uygulamanız CAE'yi işleyebileceğini bildirirse, uygulamanız bu kaynak için CAE belirteçleri alır. Bu nedenle, uygulamanızı CAE'nin hazır olduğunu bildirirseniz, uygulamanızın Microsoft Identity erişim belirteçlerini kabul eden tüm kaynak API'leri için CAE talep sınamasını işlemesi gerekir. Bu API çağrılarında CAE yanıtlarını işlemezseniz, uygulamanız hala belirtecin döndürülen kullanım ömründe olan ancak CAE nedeniyle iptal edilen bir belirteçle API çağrısını yeniden deneyen bir döngüye sahip olabilir.

Kod

İlk adım, CAE nedeniyle çağrıyı reddeden kaynak API'sinden gelen bir yanıtı işlemek için kod eklemektir. CAE ile, erişim belirteci iptal edildiğinde veya API kullanılan IP adresinde bir değişiklik algıladığında API'ler 401 durumunu ve WWW-Authenticate üst bilgisini döndürür. WWW-Authenticate üst bilgisi, uygulamanın yeni erişim belirteci almak için kullanabileceği bir Talep Sınaması içerir.

Örneğin:

// Line breaks for legibility only

HTTP 401; Unauthorized

Bearer authorization_uri="https://login.windows.net/common/oauth2/authorize",
  error="insufficient_claims",
  claims="eyJhY2Nlc3NfdG9rZW4iOnsibmJmIjp7ImVzc2VudGlhbCI6dHJ1ZSwgInZhbHVlIjoiMTYwNDEwNjY1MSJ9fX0="

Uygulamanız aşağıdakileri denetler:

• 401 durumunu döndüren API çağrısı
• www-authenticate üst bilgisinin varlığı:
  • "insufficient_claims" değerine sahip bir "error" parametresi
  • "claims" parametresi

.NET

Bu koşullar karşılandığında uygulama, MSAL.NET WwwAuthenticateParameters sınıfını kullanarak talep sınamasını ayıklayabilir ve kodunu çözebilir.

if (APIresponse.IsSuccessStatusCode)
{
    // ...
}
else
{
    if (APIresponse.StatusCode == System.Net.HttpStatusCode.Unauthorized
        && APIresponse.Headers.WwwAuthenticate.Any())
    {
        string claimChallenge = WwwAuthenticateParameters.GetClaimChallengeFromResponseHeaders(APIresponse.Headers);

Ardından uygulamanız, kaynak için yeni bir erişim belirteci almak için talep sınamasını kullanır.

try
{
    authResult = await _clientApp.AcquireTokenSilent(scopes, firstAccount)
        .WithClaims(claimChallenge)
        .ExecuteAsync()
        .ConfigureAwait(false);
}
catch (MsalUiRequiredException)
{
    try
    {
        authResult = await _clientApp.AcquireTokenInteractive(scopes)
            .WithClaims(claimChallenge)
            .WithAccount(firstAccount)
            .ExecuteAsync()
            .ConfigureAwait(false);
    }
    // ...

Uygulamanız CAE özellikli bir kaynak tarafından döndürülen talep sınamasını işlemeye hazır olduğunda, Microsoft Identity'e uygulamanızın CAE'ye hazır olduğunu söyleyebilirsiniz. Bunu MSAL uygulamanızda yapmak için "cp1" İstemci Özellikleri'ni kullanarak Genel İstemcinizi oluşturun.

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

Uygulamada bir kullanıcıda oturum açıp azure portalını kullanarak kullanıcının oturumlarını iptal ederek uygulamanızı test edebilirsiniz. Uygulama CAE özellikli API'yi bir sonraki çağırışında kullanıcıdan yeniden kimlik doğrulaması istenir.

JavaScript

Bu koşullar karşılandığında uygulama, talep sınamasını API yanıt üst bilgisinden aşağıdaki gibi ayıklayabilir:

try {
  const response = await fetch(apiEndpoint, options);

  if (response.status === 401 && response.headers.get('www-authenticate')) {
    const authenticateHeader = response.headers.get('www-authenticate');
    const claimsChallenge = parseChallenges(authenticateHeader).claims;
    
    // use the claims challenge to acquire a new access token...
  }
} catch(error) {
  // ...
}

// helper function to parse the www-authenticate header
function parseChallenges(header) {
    const schemeSeparator = header.indexOf(' ');
    const challenges = header.substring(schemeSeparator + 1).split(',');
    const challengeMap = {};

    challenges.forEach((challenge) => {
        const [key, value] = challenge.split('=');
        challengeMap[key.trim()] = window.decodeURI(value.replace(/['"]+/g, ''));
    });

    return challengeMap;
}

Ardından uygulamanız, kaynak için yeni bir erişim belirteci almak için talep sınamasını kullanır.

const tokenRequest = {
    claims: window.atob(claimsChallenge), // decode the base64 string
    scopes: ['User.Read'],
    account: msalInstance.getActiveAccount()
};

let tokenResponse;

try {
    tokenResponse = await msalInstance.acquireTokenSilent(tokenRequest);
} catch (error) {
     if (error instanceof InteractionRequiredAuthError) {
        tokenResponse = await msalInstance.acquireTokenPopup(tokenRequest);
    }
}

Uygulamanız CAE özellikli bir kaynak tarafından döndürülen talep sınamasını işlemeye hazır olduğunda, MSAL yapılandırmasına bir clientCapabilities özellik ekleyerek Microsoft Identity'e uygulamanızın CAE'ye hazır olduğunu bildirebilirsiniz.

const msalConfig = {
    auth: {
        clientId: 'Enter_the_Application_Id_Here', 
        clientCapabilities: ["CP1"]
        // remaining settings...
    }
}

const msalInstance = new PublicClientApplication(msalConfig);

Bir kullanıcıda oturum açıp azure portalını kullanarak kullanıcının oturumunu iptal ederek uygulamanızı test edebilirsiniz. Uygulama CAE özellikli API'yi bir sonraki çağırışında kullanıcıdan yeniden kimlik doğrulaması istenir.

Kod örnekleri

• Angular tek sayfalı uygulamanızın kullanıcılarla oturum açmasını ve Microsoft Graph'ı çağırmasını sağlama
• React tek sayfalı uygulamanızın kullanıcılarla oturum açmasını ve Microsoft Graph'ı çağırmasını sağlama
• ASP.NET Core web uygulamanızın kullanıcılarla oturum açmasını ve Microsoft Graph'ı aramasını sağlama

Sonraki adımlar

• Sürekli erişim değerlendirmesi kavramsal genel bakış
• Beyan sınamaları, beyan istekleri ve istemci özellikleri