Jak ve svých aplikacích používat rozhraní API s podporou průběžného vyhodnocování přístupu

Průběžné vyhodnocování přístupu (CAE) je funkce Microsoft Entra, která umožňuje odvolání přístupových tokenů na základě kritických událostí a vyhodnocení zásad, a nespoléhat se na vypršení platnosti tokenu na základě životnosti. U některých rozhraní API prostředků, protože rizika a zásady se vyhodnocují v reálném čase, může to prodloužit životnost tokenu až o 28 hodin. Tyto dlouhodobé tokeny jsou proaktivně aktualizovány knihovnou MICROSOFT Authentication Library (MSAL), což zvyšuje odolnost vašich aplikací.

V tomto článku se dozvíte, jak používat rozhraní API s podporou caE ve vašich aplikacích. Aplikace, které nepoužívají MSAL, můžou navíc využívat podporu pro výzvy při nedostatečných deklaracích identity, žádosti o deklarace identity a schopnosti klientů, aby mohly používat CAE.

Na co myslet při implementaci

Pokud chcete používat CAE, musí být vaše aplikace i rozhraní API prostředků, ke které přistupuje, povolenou službou CAE. Příprava kódu na použití prostředku s povoleným caE vám ale nebrání v používání rozhraní API, která nejsou povolená službou CAE.

Pokud rozhraní API prostředků implementuje CAE a vaše aplikace deklaruje, že dokáže zpracovat CAE, vaše aplikace obdrží tokeny CAE pro tento prostředek. Z tohoto důvodu platí, že pokud deklarujete připravenost cae vaší aplikace, musí vaše aplikace zpracovat výzvu deklarace identity CAE pro všechna rozhraní API prostředků, která přijímají přístupové tokeny Microsoft Identity. Pokud v těchto voláních rozhraní API nezpracujete odpovědi CAE, může vaše aplikace skončit ve smyčce opakování volání rozhraní API s tokenem, který je stále ve vrácené životnosti tokenu, ale byl odvolán kvůli caE.

Kód

Prvním krokem je přidání kódu pro zpracování odpovědi z rozhraní API prostředku, který volání odmítne kvůli CAE. V případě cae vrátí rozhraní API stav 401 a hlavičku WWW-Authenticate, když byl přístupový token odvolán nebo rozhraní API zjistí změnu použité IP adresy. Hlavička WWW-Authenticate obsahuje výzvu deklarací identity, kterou může aplikace použít k získání nového přístupového tokenu.

Příklad:

// Line breaks for legibility only

HTTP 401; Unauthorized

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

Aplikace by zkontrolovala:

• Volání rozhraní API vracející stav 401
• existence hlavičky WWW-Authenticate obsahující:
  • parametr "error" s hodnotou "insufficient_claims"
  • parametr deklarací identity

.NET

Po splnění těchto podmínek může aplikace extrahovat a dekódovat výzvu deklarací pomocí třídy MSAL.NET WwwAuthenticateParameters .

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

Aplikace pak pomocí výzvy deklarací identity získá nový přístupový token prostředku.

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

Jakmile je vaše aplikace připravená na zpracování výzvy deklarace identity vrácené prostředkem s povolenou službou CAE, můžete říct, že je vaše aplikace identita Microsoftu připravená. Chcete-li to provést ve vaší aplikaci MSAL, sestavte veřejný klient pomocí možností klienta "cp1".

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

Aplikaci můžete otestovat tak, že se přihlásíte k aplikaci a pak pomocí webu Azure Portal odvoláte relace uživatele. Při příštím volání rozhraní API s povolenou certifikační autoritou se uživateli zobrazí výzva k opětovnému ověření.

JavaScript

Po splnění těchto podmínek může aplikace extrahovat výzvu deklarací identity z hlavičky odpovědi rozhraní API následujícím způsobem:

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

Aplikace pak pomocí výzvy deklarací identity získá nový přístupový token prostředku.

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

Jakmile je vaše aplikace připravená na zpracování výzvy deklarace identity vrácené prostředkem s povoleným caE, můžete zjistit, že je vaše aplikace připravená službou CAE, a to tak, že do konfigurace MSAL přidáte clientCapabilities vlastnost.

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

const msalInstance = new PublicClientApplication(msalConfig);

Aplikaci můžete otestovat přihlášením uživatele a následným použitím webu Azure Portal k odvolání relace uživatele. Při příštím volání rozhraní API s podporou CAE se uživateli zobrazí výzva k opětovnému ověření.

Ukázky kódu

• Povolení jednostránkakové aplikace Angular pro přihlášení uživatelů a volání Microsoft Graphu
• Povolení jednostránka aplikace React pro přihlášení uživatelů a volání Microsoft Graphu
• Povolení webové aplikace ASP.NET Core pro přihlášení uživatelů a volání Microsoft Graphu

Další kroky

• Koncepční přehled vyhodnocení průběžného přístupu
• Výzvy při nedostatečných deklaracích identity, žádosti o deklarace identity a schopnosti klienta