API's met continue toegangsevaluatie gebruiken in uw toepassingen

Continuous Access Evaluation (CAE) is een Microsoft Entra-functie waarmee toegangstokens kunnen worden ingetrokken op basis van kritieke gebeurtenissen en beleidsevaluatie in plaats van te vertrouwen op het verlopen van tokens op basis van de levensduur. Voor sommige resource-API's, omdat risico's en beleid in realtime worden geëvalueerd, kan dit de levensduur van tokens tot 28 uur verhogen. Deze langlopende tokens worden proactief vernieuwd door de Microsoft Authentication Library (MSAL), waardoor de tolerantie van uw toepassingen wordt verhoogd.

In dit artikel wordt beschreven hoe u API's met CAE kunt gebruiken in uw toepassingen. Toepassingen die geen gebruikmaken van MSAL, kunnen ondersteuning toevoegen voor problemen met claims, aanvragen van claims en clientmogelijkheden voor gebruik van CAE.

Implementatieoverwegingen

Als u CAE wilt gebruiken, moeten zowel uw app als de resource-API die toegang heeft, CAE zijn ingeschakeld. Het voorbereiden van uw code voor het gebruik van een resource waarvoor CAE is ingeschakeld, voorkomt echter niet dat u API's gebruikt die niet zijn ingeschakeld voor CAE.

Als een resource-API CAE implementeert en uw toepassing declareert dat deze CAE kan verwerken, ontvangt uw app CAE-tokens voor die resource. Als u daarom uw app CAE gereed declareert, moet uw toepassing de CAE-claimvraag afhandelen voor alle resource-API's die toegangstokens van Microsoft Identity accepteren. Als u CAE-antwoorden in deze API-aanroepen niet verwerkt, kan uw app terechtkomen in een lus die een API-aanroep opnieuw probeert uit te voeren met een token dat nog steeds de geretourneerde levensduur van het token heeft, maar is ingetrokken vanwege CAE.

De code

De eerste stap is het toevoegen van code voor het afhandelen van een reactie van de resource-API die de aanroep weigert vanwege CAE. Met CAE retourneren API's een 401-status en een WWW-Authenticate-header wanneer het toegangstoken is ingetrokken of detecteert de API een wijziging in het GEBRUIKTE IP-adres. De HEADER WWW-Authenticate bevat een Claims Challenge die de toepassing kan gebruiken om een nieuw toegangstoken te verkrijgen.

Voorbeeld:

// Line breaks for legibility only

HTTP 401; Unauthorized

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

Uw app controleert op:

• de API-aanroep die de 401-status retourneert
• het bestaan van een WWW-Authenticate-header met:
  • een 'error'-parameter met de waarde 'insufficient_claims'
  • een parameter 'claims'

.NET

Wanneer aan deze voorwaarden wordt voldaan, kan de app de claimvraag extraheren en decoderen met behulp van MSAL.NET WwwAuthenticateParameters klasse.

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

Uw app gebruikt vervolgens de claimvraag om een nieuw toegangstoken voor de resource te verkrijgen.

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

Zodra uw toepassing klaar is om de claimvraag af te handelen die wordt geretourneerd door een RESOURCE met CAE, kunt u aan Microsoft Identity zien dat uw app gereed is voor CAE. U doet dit in uw MSAL-toepassing door uw openbare client te bouwen met behulp van de clientmogelijkheden van cp1.

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

U kunt uw toepassing testen door u aan te melden bij een gebruiker bij de toepassing en vervolgens de Azure-portal te gebruiken om de sessies van de gebruiker in te trekken. De volgende keer dat de app de CAE-API aanroept, wordt de gebruiker gevraagd om opnieuw te verifiëren.

JavaScript

Wanneer aan deze voorwaarden wordt voldaan, kan de app de claimuitdaging als volgt extraheren uit de API-antwoordheader:

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

Uw app gebruikt vervolgens de claimvraag om een nieuw toegangstoken voor de resource te verkrijgen.

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

Zodra uw toepassing klaar is om de claimvraag af te handelen die wordt geretourneerd door een resource met CAE-functionaliteit, kunt u aan Microsoft Identity zien dat uw app gereed is voor CAE door een clientCapabilities eigenschap toe te voegen in de MSAL-configuratie.

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

const msalInstance = new PublicClientApplication(msalConfig);

U kunt uw toepassing testen door u aan te melden bij een gebruiker en vervolgens de Azure-portal te gebruiken om de sessie van de gebruiker in te trekken. De volgende keer dat de app de API met CAE aanroept, wordt de gebruiker gevraagd om opnieuw te verifiëren.

Codevoorbeelden

• Uw Angular-toepassing met één pagina inschakelen om gebruikers aan te melden en Microsoft Graph aan te roepen
• Uw React-toepassing met één pagina inschakelen om gebruikers aan te melden en Microsoft Graph aan te roepen
• Uw ASP.NET Core-web-app inschakelen om gebruikers aan te melden en Microsoft Graph aan te roepen

Volgende stappen

• Conceptueel overzicht van continue toegangsevaluatie
• Problemen met claims, aanvragen van claims en clientmogelijkheden