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

持續存取評估 （CAE） 是一項Microsoft Entra 功能，允許根據 重大事件 和 原則評估來撤銷存取令牌，而不是依賴以存留期為基礎的令牌到期。

因為風險和原則會即時評估，因此某些資源 API 令牌存留期最多可以增加 28 小時。 這些長期令牌會由 Microsoft 驗證連結庫 （MSAL） 主動重新整理，以增加應用程式的復原能力。

未使用 MSAL 的應用程式可新增對宣告挑戰、宣告要求和用戶端功能的支援，以使用 CAE。

實作考量

若要使用 CAE，您的應用程式和其所存取的資源 API 都必須啟用 CAE。 如果資源 API 會實作 CAE，而您的應用程式宣告它可以處理 CAE，則您的應用程式會接收該資源的 CAE 權杖。 基於這個理由，如果您宣告應用程式 CAE 就緒，您的應用程式必須針對接受Microsoft身分識別存取令牌的所有資源 API 處理 CAE 宣告挑戰。

不過，準備程式代碼以支援已啟用 CAE 的資源並不會限制其使用不支援 CAE 的 API 的能力。 如果您的應用程式未正確處理 CAE 回應，可能會使用技術上有效的令牌重複重試 API 呼叫，但因 CAE 而遭到撤銷。

在應用程式中處理 CAE

首先，新增程式代碼來處理因 CAE 而拒絕呼叫的資源 API 回應。 使用CAE時，API會在撤銷存取令牌時傳回401狀態和 WWW-Authenticate 標頭，或API偵測到所使用的IP位址變更。 標頭 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 ，其中包含：
  • error具有 值的參數insufficient_claims
  • 參數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();

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

MSAL-Python

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

import msal  # pip install msal
import requests  # pip install requests
import www_authenticate  # pip install www-authenticate==0.9.2

# Once your application is ready to handle the claim challenge returned by a CAE-enabled resource, you can tell Microsoft Identity your app is CAE-ready. To do this in your MSAL application, build your Public Client using the Client Capabilities of "cp1".
app = msal.PublicClientApplication("your_client_id", client_capabilities=["cp1"])

...

# When these conditions are met, the app can extract the claims challenge from the API response header as follows:
response = requests.get("<your_resource_uri_here>")
if response.status_code == 401 and response.headers.get('WWW-Authenticate'):
    parsed = www_authenticate.parse(response.headers['WWW-Authenticate'])
    claims = parsed.get("bearer", {}).get("claims")

    # Your app would then use the claims challenge to acquire a new access token for the resource.
    if claims:
        auth_result = app.acquire_token_interactive(["scope"], claims_challenge=claims)

MSAL-Android

宣告 CP1 用戶端功能的支援

在應用程式組態中，您必須宣告您的應用程式支援 CAE，方法是包含 CP1 用戶端功能。 這是使用 client_capabilities JSON 屬性所指定。

{
  "client_id" : "<your_client_id>",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "msauth://<pkg>/<cert_hash>",
  "multiple_clouds_supported":true,
  "broker_redirect_uri_registered": true,
  "account_mode": "MULTIPLE",
  "client_capabilities": "CP1",
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      }
    }
  ]
}

回應運行時間的 CAE 挑戰

對資源提出要求，如果回應包含宣告挑戰，請加以擷取，並將其饋送回 MSAL，以供下一個要求使用。

final HttpURLConnection connection = ...;
final int responseCode = connection.getResponseCode();

// Check the response code...
if (200 == responseCode) {
    // ...
} else if (401 == responseCode) {
    final String authHeader = connection.getHeaderField("WWW-Authenticate");

    if (null != authHeader) {
        final ClaimsRequest claimsRequest = WWWAuthenticateHeader
                                                .getClaimsRequestFromWWWAuthenticateHeaderValue(authHeader);

        // Feed the challenge back into MSAL, first silently, then interactively if required
        final AcquireTokenSilentParameters silentParameters = new AcquireTokenSilentParameters.Builder()
            .fromAuthority(authority)
            .forAccount(account)
            .withScopes(scope)
            .withClaims(claimsRequest)
            .build();
        
        try {
            final IAuthenticationResult silentRequestResult = mPublicClientApplication.acquireTokenSilent(silentParameters);
            // If successful - your business logic goes here...

        } catch (final Exception e) {
            if (e instanceof MsalUiRequiredException) {
                // Retry the request interactively, passing in any claims challenge...
            }
        }
    }
} else {
    // ...
}

// Don't forget to close your connection

MSAL-ObjC

下列代碼段描述以無訊息方式取得令牌的流程，對資源提供者進行 HTTP 呼叫，然後處理 CAE 案例。 如果無訊息呼叫因宣告失敗，可能需要額外的互動呼叫。

宣告 CP1 用戶端功能的支援

在應用程式組態中，您必須宣告您的應用程式支援 CAE，方法是包含 CP1 用戶端功能。 這是使用 clientCapabilities 屬性所指定。

let clientConfigurations = MSALPublicClientApplicationConfig(clientId: "contoso-app-ABCDE-12345",
                                                            redirectUri: "msauth.com.contoso.appbundle://auth",
                                                            authority: try MSALAuthority(url: URL(string: "https://login.microsoftonline.com/organizations")!))
clientConfigurations.clientApplicationCapabilities = ["CP1"]
let applicationContext = try MSALPublicClientApplication(configuration: clientConfigurations)

實作協助程式函式來剖析宣告挑戰。

func parsewwwAuthenticateHeader(headers:Dictionary<AnyHashable, Any>) -> String? {
    // !! This is a sample code and is not validated, please provide your own implementation or fully test the sample code provided here.
    // Can also refer here for our internal implementation: https://github.com/AzureAD/microsoft-authentication-library-common-for-objc/blob/dev/IdentityCore/src/webview/embeddedWebview/challangeHandlers/MSIDPKeyAuthHandler.m#L112
    guard let wwwAuthenticateHeader = headers["WWW-Authenticate"] as? String else {
        // did not find the header, handle gracefully
        return nil
    }
    
    var parameters = [String: String]()
    // regex mapping
    let regex = try! NSRegularExpression(pattern: #"(\w+)="([^"]*)""#)
    let matches = regex.matches(in: wwwAuthenticateHeader, range: NSRange(wwwAuthenticateHeader.startIndex..., in: wwwAuthenticateHeader))
    
    for match in matches {
        if let keyRange = Range(match.range(at: 1), in: wwwAuthenticateHeader),
           let valueRange = Range(match.range(at: 2), in: wwwAuthenticateHeader) {
            let key = String(wwwAuthenticateHeader[keyRange])
            let value = String(wwwAuthenticateHeader[valueRange])
            parameters[key] = value
        }
    }
    
    guard let jsonData = try? JSONSerialization.data(withJSONObject: parameters, options: .prettyPrinted) else {
        // cannot convert params into json date, end gracefully
        return nil
    }
    return String(data: jsonData, encoding: .utf8)
}

Catch & parse 401 / claims challenges.

let response = .... // HTTPURLResponse object from 401'd service response

switch response.statusCode {
case 200:
    // ...succeeded!
    break
case 401:
    let headers = response.allHeaderFields

    // Parse header fields
    guard let wwwAuthenticateHeaderString = self.parsewwwAuthenticateHeader(headers: headers) else {
        // 3.7 no valid wwwAuthenticateHeaderString is returned from header, end gracefully
        return
    }
    
    let claimsRequest = MSALClaimsRequest(jsonString: wwwAuthenticateHeaderString, error: nil)
    // Create claims request
    let parameters = MSALSilentTokenParameters(scopes: "Enter_the_Protected_API_Scopes_Here", account: account)
    parameters.claimsRequest = claimsRequest
    // Acquire token silently again with the claims challenge
    applicationContext.acquireTokenSilent(with: parameters) { (result, error) in
        
        if let error = error {
            // error happened end flow gracefully, and handle error. (e.g. interaction required)
            return
        }
        
        guard let result = result else {
            
            // no result end flow gracefully
            return
        }                    
        // Success - You got a token!
    }
    
    break
default:
    break
}

MSAL-Go

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

公告用戶端功能。

client, err := New("client-id", WithAuthority(authority), WithClientCapabilities([]string{"cp1"}))

剖析標頭， WWW-Authenticate 並將產生的挑戰傳遞至 MSAL-Go。

// No snippet provided at this time

嘗試使用宣告挑戰以無訊息方式取得令牌。

var ar AuthResult;
ar, err := client.AcquireTokenSilent(ctx, tokenScope, public.WithClaims(claims))

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

程式碼範例

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

相關內容

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