如何在應用程式中使用已啟用持續存取評估的 API

持續存取評估 （CAE） 是 Microsoft Entra 功能，允許根據 重大事件 和 原則評估 來撤銷存取令牌，而不是根據存留期依賴令牌到期。 對於某些資源 API，因為風險和原則會實時評估，這會增加令牌存留期最多 28 小時。 Microsoft 驗證連結庫 （MSAL） 會主動重新整理這些長期令牌，以增加應用程式的復原能力。

本文說明如何在應用程式中使用已啟用 CAE 的 API。 未使用 MSAL 的應用程式可新增對宣告挑戰、宣告要求和用戶端功能的支援，以使用 CAE。

實作考量

若要使用 CAE，您的應用程式和資源 API 都必須啟用 CAE 存取。 不過，準備程式代碼以使用已啟用 CAE 的資源，不會阻止您使用未啟用 CAE 的 API。

如果資源 API 實作 CAE，而您的應用程式宣告它可以處理 CAE，則您的應用程式會收到該資源的 CAE 令牌。 基於這個理由，如果您宣告應用程式 CAE 就緒，您的應用程式必須處理所有接受 Microsoft 身分識別存取令牌的資源 API 的 CAE 宣告挑戰。 如果您未處理這些 API 呼叫中的 CAE 回應，您的應用程式最終可能會以仍在令牌傳回生命週期中的令牌重試 API 呼叫，但由於 CAE 而遭到撤銷。

程序代碼

第一個步驟是新增程序代碼，以處理因 CAE 而拒絕呼叫的資源 API 回應。 使用 CAE 時，API 會在撤銷存取令牌或 API 偵測到使用的 IP 位址變更時，傳回 401 狀態和 WWW-Authenticate 標頭。 WWW-Authenticate 標頭包含宣告挑戰，應用程式可用來取得新的存取令牌。

例如：

// Line breaks for legibility only

HTTP 401; Unauthorized

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

您的應用程式會檢查下列專案：

• 傳回 401 狀態的 API 呼叫
• WWW-Authenticate 標頭是否存在，其中包含：
  • 值為 「insufficient_claims」 的 「error」 參數
  • “claims” 參數

.NET

符合這些條件時，應用程式可以使用 MSAL.NET WwwAuthenticateParameters 類別來擷取和譯碼宣告挑戰。

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

接著，您的應用程式會使用宣告挑戰來取得資源的新存取令牌。

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);
    }
    // ...

一旦您的應用程式準備好處理已啟用 CAE 的資源所傳回的宣告挑戰，您可以告訴 Microsoft 身分識別您的應用程式已準備好 CAE。 若要在 MSAL 應用程式中這樣做，請使用 「cp1」 的用戶端功能來建置您的公用用戶端。

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

您可以藉由登入應用程式來測試應用程式，然後使用 Azure 入口網站 撤銷使用者的工作階段。 下次應用程式呼叫已啟用 CAE 的 API 時，系統會要求使用者重新驗證。

JavaScript

符合這些條件時，應用程式可以從 API 回應標頭擷取宣告挑戰，如下所示：

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;
}

接著，您的應用程式會使用宣告挑戰來取得資源的新存取令牌。

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);
    }
}

一旦您的應用程式準備好處理已啟用 CAE 的資源所傳回的宣告挑戰，您可以藉由在 MSAL 設定中新增 clientCapabilities 屬性，告訴 Microsoft 身分識別您的應用程式已準備好 CAE。

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

const msalInstance = new PublicClientApplication(msalConfig);

您可以藉由登入使用者，然後使用 Azure 入口網站 來撤銷使用者的會話，來測試您的應用程式。 下次應用程式呼叫已啟用 CAE 的 API 時，系統會要求使用者重新驗證。

程式碼範例

• 讓您的 Angular 單頁應用程式能夠登入使用者並呼叫 Microsoft Graph
• 啟用 React 單頁應用程式來登入使用者並呼叫 Microsoft Graph
• 讓您的 ASP.NET Core Web 應用程式登入使用者並呼叫 Microsoft Graph

下一步

• 持續存取評估 概念概觀
• 宣告挑戰、宣告要求和用戶端功能