Så här använder du API:er för kontinuerlig åtkomstutvärdering i dina program

Kontinuerlig åtkomstutvärdering (CAE) är en Microsoft Entra-funktion som gör att åtkomsttoken kan återkallas baserat på kritiska händelser och principutvärdering i stället för att förlita sig på tokens giltighetstid baserat på livslängd. För vissa resurs-API:er kan detta öka tokenlivslängden upp till 28 timmar eftersom risker och principer utvärderas i realtid. Dessa långlivade token uppdateras proaktivt av Microsoft Authentication Library (MSAL), vilket ökar återhämtningstiden för dina program.

Den här artikeln visar hur du använder CAE-aktiverade API:er i dina program. Program som inte använder MSAL kan lägga till stöd för anspråksutmaningar, anspråksbegäranden och klientfunktioner så att de kan använda utvärdering av kontinuerlig åtkomst.

Implementeringöverväganden

Om du vill använda CAE måste både appen och resurs-API:et som den har åtkomst till vara CAE-aktiverade. Men att förbereda koden för att använda en CAE-aktiverad resurs hindrar dig inte från att använda API:er som inte är CAE-aktiverade.

Om ett resurs-API implementerar CAE och ditt program deklarerar att det kan hantera CAE tar appen emot CAE-token för den resursen. Om du därför deklarerar din app CAE redo måste ditt program hantera CAE-anspråksutmaningen för alla resurs-API:er som accepterar Åtkomsttoken för Microsoft Identity. Om du inte hanterar CAE-svar i dessa API-anrop kan din app hamna i en loop som försöker utföra ett API-anrop igen med en token som fortfarande finns i tokens returnerade livslängd men som har återkallats på grund av CAE.

Koden

Det första steget är att lägga till kod för att hantera ett svar från resurs-API:et som avvisar anropet på grund av CAE. Med CAE returnerar API:er en 401-status och ett WWW-Authenticate-huvud när åtkomsttoken har återkallats eller API:et identifierar en ändring i IP-adressen som används. RUBRIKEN WWW-Authenticate innehåller en anspråksutmaning som programmet kan använda för att hämta en ny åtkomsttoken.

Till exempel:

// Line breaks for legibility only

HTTP 401; Unauthorized

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

Din app skulle söka efter:

• API-anropet som returnerar statusen 401
• förekomsten av en WWW-Authenticate-rubrik som innehåller:
  • en "fel"-parameter med värdet "insufficient_claims"
  • en "anspråksparameter"

.NET

När dessa villkor uppfylls kan appen extrahera och avkoda anspråksutmaningen med hjälp av MSAL.NET-klass WwwAuthenticateParameters .

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

Din app använder sedan anspråksutmaningen för att hämta en ny åtkomsttoken för resursen.

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

När ditt program är redo att hantera anspråksutmaningen som returneras av en CAE-aktiverad resurs kan du se till att Microsoft Identity som din app är CAE redo för. Om du vill göra detta i ditt MSAL-program skapar du den offentliga klienten med hjälp av klientfunktionerna i "cp1".

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

Du kan testa ditt program genom att logga in en användare i programmet och sedan använda Azure-portalen för att återkalla användarens sessioner. Nästa gång appen anropar DET CAE-aktiverade API:et uppmanas användaren att autentisera igen.

JavaScript

När dessa villkor uppfylls kan appen extrahera anspråksutmaningen från API-svarshuvudet på följande sätt:

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

Din app använder sedan anspråksutmaningen för att hämta en ny åtkomsttoken för resursen.

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

När ditt program är redo att hantera anspråksutmaningen som returneras av en CAE-aktiverad resurs kan du berätta för Microsoft Identity att din app är CAE-redo genom att lägga till en clientCapabilities egenskap i MSAL-konfigurationen.

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

const msalInstance = new PublicClientApplication(msalConfig);

Du kan testa ditt program genom att logga in en användare och sedan använda Azure-portalen för att återkalla användarens session. Nästa gång appen anropar DET CAE-aktiverade API:et uppmanas användaren att autentisera igen.

Kodexempel

• Aktivera angular-ensidesprogrammet för att logga in användare och anropa Microsoft Graph
• Aktivera ditt React-ensidesprogram för att logga in användare och anropa Microsoft Graph
• Aktivera din ASP.NET Core-webbapp för att logga in användare och anropa Microsoft Graph

Nästa steg

• Översikt över utvärdering av kontinuerlig åtkomst
• Anspråksutmaningar, anspråksbegäranden och klientfunktioner