如何在应用程序中使用启用了连续访问评估的 API

2025-09-22

连续访问评估（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.chinacloudapi.cn/common/oauth2/authorize",
  error="insufficient_claims",
  claims="eyJhY2Nlc3NfdG9rZW4iOnsibmJmIjp7ImVzc2VudGlhbCI6dHJ1ZSwgInZhbHVlIjoiMTYwNDEwNjY1MSJ9fX0="

你的应用会检查以下项：

返回 401 状态的 API 调用
存在 WWW-Authenticate 标头，其中包含：
- 具有insufficient_claims值的error参数
- 一个参数 claims

满足这些条件后，应用可以使用 MSAL.NETWwwAuthenticateParameters 类提取和解码声明质询。

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

满足这些条件后，应用可以从 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: ['https://microsoftgraph.chinacloudapi.cn/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);

满足这些条件后，应用可以从 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)

声明对 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

以下代码片段描述以无提示方式获取令牌的流程，对资源提供程序进行 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.partner.microsoftonline.cn/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)
}

捕获与解析 401 及声明质询。

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
}

满足这些条件后，应用可以从 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 时，系统将要求用户重新进行身份验证。

代码示例

持续访问评估概念概述
声明质询、声明请求和客户端功能

通过

如何在应用程序中使用启用了连续访问评估的 API

实现注意事项

在应用程序中处理 CAE

代码示例

相关内容

其他资源