Jak używać interfejsów API z obsługą ciągłego dostępu w aplikacjach

Continuous Access Evaluation (CAE) to funkcja firmy Microsoft Entra, która umożliwia odwoływanie tokenów dostępu na podstawie krytycznych zdarzeń i oceny zasad, a nie polegania na wygaśnięciu tokenu na podstawie okresu istnienia. W przypadku niektórych interfejsów API zasobów, ponieważ ryzyko i zasady są oceniane w czasie rzeczywistym, może to zwiększyć okres istnienia tokenu do 28 godzin. Te długotrwałe tokeny są aktywnie odświeżane przez bibliotekę Microsoft Authentication Library (MSAL), zwiększając odporność aplikacji.

W tym artykule pokazano, jak używać interfejsów API z obsługą caE w aplikacjach. W aplikacjach, które nie korzystają z biblioteki MSAL, można dodać obsługę wyzwań z oświadczeniami, żądań oświadczeń i możliwości klienta na potrzeby korzystania z ciągłej weryfikacji dostępu.

Uwagi dotyczące implementacji

Aby korzystać ze środowiska CAE, zarówno aplikacja, jak i interfejs API zasobów, do których uzyskuje dostęp, musi być włączona funkcja CAE. Jednak przygotowanie kodu do korzystania z zasobu z włączoną usługą CAE nie uniemożliwi korzystania z interfejsów API, które nie są włączone w trybie CAE.

Jeśli interfejs API zasobów implementuje interfejs CAE, a aplikacja deklaruje, że może obsługiwać interfejs CAE, aplikacja otrzymuje tokeny CAE dla tego zasobu. Z tego powodu, jeśli zadeklarowasz gotowość caE aplikacji, aplikacja musi obsługiwać wyzwanie oświadczenia CAE dla wszystkich interfejsów API zasobów, które akceptują tokeny dostępu tożsamości Microsoft. Jeśli nie obsługujesz odpowiedzi CAE w tych wywołaniach interfejsu API, twoja aplikacja może zakończyć się ponowić próbę wywołania interfejsu API za pomocą tokenu, który jest nadal w zwracanej cyklu życia tokenu, ale został odwołany ze względu na caE.

Kod

Pierwszym krokiem jest dodanie kodu do obsługi odpowiedzi z interfejsu API zasobów odrzucającego wywołanie z powodu caE. W przypadku interfejsu CAE interfejsy API zwracają stan 401 i nagłówek WWW-Authenticate po odwołaniu tokenu dostępu lub interfejs API wykryje zmianę używanego adresu IP. Nagłówek WWW-Authenticate zawiera wyzwanie oświadczeń, którego aplikacja może użyć do uzyskania nowego tokenu dostępu.

Na przykład:

// Line breaks for legibility only

HTTP 401; Unauthorized

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

Aplikacja sprawdzi, czy:

• wywołanie interfejsu API zwracające stan 401
• istnienie nagłówka WWW-Authenticate zawierającego:
  • parametr "error" z wartością "insufficient_claims"
  • parametr "claims"

.NET

Po spełnieniu tych warunków aplikacja może wyodrębnić i zdekodować wyzwanie dotyczące oświadczeń przy użyciu klasy MSAL.NET WwwAuthenticateParameters .

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

Następnie aplikacja użyje wyzwania dotyczącego oświadczeń, aby uzyskać nowy token dostępu dla zasobu.

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

Gdy aplikacja będzie gotowa do obsługi żądania zwróconego przez zasób z włączoną usługą CAE, możesz poinformować, że usługa Microsoft Identity twoja aplikacja jest gotowa do użycia w usłudze CAE. Aby to zrobić w aplikacji MSAL, skompiluj klienta publicznego przy użyciu funkcji klienta "cp1".

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

Aplikację można przetestować, logując użytkownika do aplikacji, a następnie używając witryny Azure Portal, aby odwołać sesje użytkownika. Przy następnym wywołaniu interfejsu API z włączoną obsługą caE użytkownik zostanie poproszony o ponowne uwierzytelnienie.

JavaScript

Po spełnieniu tych warunków aplikacja może wyodrębnić żądanie oświadczeń z nagłówka odpowiedzi interfejsu API w następujący sposób:

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

Następnie aplikacja użyje wyzwania dotyczącego oświadczeń, aby uzyskać nowy token dostępu dla zasobu.

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

Gdy aplikacja będzie gotowa do obsługi żądania zgłoszonego przez zasób z obsługą caE, możesz poinformować, że tożsamość firmy Microsoft aplikacja jest gotowa do użycia przez dodanie clientCapabilities właściwości w konfiguracji biblioteki MSAL.

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

const msalInstance = new PublicClientApplication(msalConfig);

Aplikację można przetestować, logując się do użytkownika, a następnie używając witryny Azure Portal, aby odwołać sesję użytkownika. Przy następnym wywołaniu interfejsu API z obsługą caE użytkownik zostanie poproszony o ponowne uwierzytelnienie.

Przykłady kodu

• Włączanie jednostronicowej aplikacji Angular w celu logowania użytkowników i wywoływania programu Microsoft Graph
• Włączanie aplikacji jednostronicowej React w celu logowania użytkowników i wywoływania programu Microsoft Graph
• Włączanie aplikacji internetowej ASP.NET Core w celu logowania użytkowników i wywoływania programu Microsoft Graph

Następne kroki

• Omówienie koncepcji oceny ciągłego dostępu
• Wyzwania z oświadczeniami, żądania oświadczeń i możliwości klienta