如何在应用程序中使用启用了连续访问评估的 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 响应，它可能会使用技术上有效但因 CAE 而被撤销的令牌重复重试 API 调用。

在应用程序中处理 CAE

首先添加代码来处理由于 CAE 而拒绝调用的资源 API 的响应。 启用 CAE 后，当访问令牌已被撤销或者 API 检测到所使用的 IP 地址发生变化时，API 将返回 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();

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

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 客户端功能的支持

在应用程序配置中，必须通过包含 CP1 客户端功能来声明应用程序支持 CAE。 这是使用 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 客户端功能的支持

在应用程序配置中，必须通过包含 CP1 客户端功能来声明应用程序支持 CAE。 这是通过使用 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)
}

捕获和分析 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
}

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

相关内容

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