Verwenden von APIs mit aktivierter fortlaufender Zugriffsevaluierung in Ihren Anwendungen

Die fortlaufende Zugriffsevaluierung (Continuous Access Evaluation, CAE) ist ein Microsoft Entra-Feature, mit dem Zugriffstoken basierend auf kritischen Ereignissen und Richtlinienauswertungen widerrufen werden können, anstatt dass sich auf den auf der Lebensdauer basierenden Tokenablauf zu verlassen. Dies kann bei einigen Ressourcen-APIs die Lebensdauer eines Tokens um bis zu 28 Stunden verlängern, weil Risiken und Richtlinien in Echtzeit ausgewertet werden. Diese langlebigen Token werden von der Microsoft Authentication Library (MSAL) proaktiv aktualisiert, wodurch die Resilienz Ihrer Anwendungen steigt.

In diesem Artikel erfahren Sie, wie Sie APIs mit aktivierter fortlaufender Zugriffsevaluierung in Ihren Anwendungen verwenden. Anwendungen, die MSAL nicht verwenden, können Unterstützung für Anspruchsherausforderungen, Anspruchsanforderungen und Clientfunktionen zur Verwendung von CAE hinzufügen.

Überlegungen zur Implementierung

Damit die fortlaufende Zugriffsevaluierung (Continuous Access Evaluation, CAE) genutzt werden kann, muss dieses Feature sowohl für Ihre App als auch für die Ressourcen-API aktiviert werden, die auf die App zugreift. Auch wenn Sie Ihren Code für die Nutzung einer Ressource mit aktivierter CAE vorbereiten, bedeutet das nicht, dass Sie keine APIs verwenden können, für die dieses Feature nicht aktiviert wurde.

Wenn eine Ressourcen-API CAE implementiert und in Ihrer App deklariert wurde, dass sie das Feature verarbeiten kann, erhält die App CAE-Token für diese Ressource. Aus diesem Grund gilt Folgendes: Wenn Sie Ihre App als CAE-fähig deklarieren, muss die App die CAE-Anspruchsabfrage für alle Ressourcen-APIs verarbeiten, die Microsoft Identity-Zugriffstoken akzeptieren. Wenn Sie CAE-Antworten in diesen API-Aufrufen nicht verarbeiten, könnte Ihre App in einer Schleife enden, in der sie einen API-Aufruf mit einem Token wiederholt, das sich noch in der zurückgegebenen Lebensdauer des Tokens befindet, aber aufgrund von CAE widerrufen wurde.

Der Code

Als Erstes müssen Sie Code hinzufügen, um eine Antwort von der Ressourcen-API zu verarbeiten, die den Aufruf aufgrund von CAE ablehnt. Mit CAE geben APIs einen 401-Statuscode sowie einen WWW-Authenticate-Header zurück, wenn das Zugriffstoken widerrufen wurde oder die API eine Änderung in der verwendeten IP-Adresse erkennt. Der WWW-Authenticate-Header enthält eine Anspruchsabfrage, mit der die Anwendung ein neues Zugriffstoken abrufen kann.

Zum Beispiel:

// Line breaks for legibility only

HTTP 401; Unauthorized

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

Ihre App überprüft Folgendes:

• den API-Aufruf, der den 401-Status zurückgibt
• das Vorhandensein eines WWW-Authenticate-Headers mit folgendem Inhalt:
  • ein error-Parameter mit dem Wert „insufficient_claims“
  • ein claims-Parameter

.NET

Wenn diese Bedingungen erfüllt sind, kann die App die Anspruchsabfrage unter Verwendung der MSAL.NET-Klasse WwwAuthenticateParameters extrahieren und decodieren.

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

Dann verwendet Ihre App die Anspruchsabfrage, um ein neues Zugriffstoken für die Ressource abzurufen.

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

Sobald Ihre Anwendung dazu bereit ist, die von einer für CAE aktivierten Ressource zurückgegebene Anspruchsabfrage zu verarbeiten, können Sie Microsoft Identity mitteilen, dass Ihre Anwendung CAE-fähig ist. Um dies in Ihrer MSAL-Anwendung umzusetzen, erstellen Sie Ihren öffentlichen Client mit den Clientfunktionen von „cp1“.

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

Sie können Ihre App testen, indem einen Benutzer bei der App anmelden und dann das Azure-Portal verwenden, um die Sitzungen dieses Benutzers zu widerrufen. Wenn die App das nächste Mal die API mit aktivierter CAE aufruft, wird der Benutzer aufgefordert, sich erneut zu authentifizieren.

JavaScript

Wenn diese Bedingungen erfüllt sind, kann die App die Anspruchsabfrage aus dem API-Antwortheader wie folgt extrahieren:

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

Dann verwendet Ihre App die Anspruchsabfrage, um ein neues Zugriffstoken für die Ressource abzurufen.

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

Sobald Ihre Anwendung dazu bereit ist, die von einer für CAE aktivierten Ressource zurückgegebene Anspruchsabfrage zu verarbeiten, können Sie Microsoft Identity mitteilen, dass Ihre Anwendung CAE-fähig ist, indem Sie eine clientCapabilities-Eigenschaft in der MSAL-Konfiguration hinzufügen.

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

const msalInstance = new PublicClientApplication(msalConfig);

Sie können Ihre Anwendung testen, indem Sie einen Benutzer anmelden und dann das Azure-Portal verwenden, um die Sitzungen des Benutzers zu widerrufen. Wenn die App das nächste Mal die API mit aktivierter CAE aufruft, wird der Benutzer aufgefordert, sich erneut zu authentifizieren.

Codebeispiele

• Aktivieren Ihrer Angular-Single-Page-Anwendung zum Anmelden von Benutzern und zum Aufrufen von Microsoft Graph
• Aktivieren Ihrer React-Single-Page-Anwendung zum Anmelden von Benutzern und zum Aufrufen von Microsoft Graph
• Aktivieren Ihrer ASP-NET Core-Web-App zum Anmelden von Benutzern und zum Aufrufen von Microsoft Graph

Nächste Schritte

• Konzeptionelle Übersicht über diekontinuierliche Zugriffsevaluierung
• Anspruchsherausforderungen, Anspruchsanforderungen und Clientfunktionen