如何在您的應用程式中使用已啟用持續性存取評估的 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 的資源所傳回的宣告挑戰後，您就可以告知 Microsoft 身分識別您的應用程式已做好 CAE 的準備，方法是在 MSAL 設定中新增 clientCapabilities 屬性。

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 (英文)

下一步

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