継続的アクセス評価が有効になった API をアプリケーションで使用する方法

継続的アクセス評価 (CAE) は、トークンの有効期間ではなく重要なイベントとポリシー評価に基づいてアクセス トークンを取り消すことができる、Microsoft Entra の機能です。 一部のリソース API については、リスクとポリシーがリアルタイムで評価されるため、トークンの有効期間を最大 28 時間まで延長することができます。 このような有効期間が長いトークンは Microsoft Authentication Library (MSAL) によって事前に更新されるため、アプリケーションの復元性が向上します。

この記事では、CAE 対応 API をアプリケーションで使用する方法について説明します。 MSAL を使用していないアプリケーションでは、CAE を使用するための 要求のチャレンジ、要求要求、およびクライアント機能 のサポートを追加できます。

実装時の注意事項

CAE を使用するには、アプリもそれがアクセスするリソース API も CAE 対応であることが必要です。 ただし、CAE 対応のリソースを使用するようにコードを準備しても、CAE 対応でない API を使用できなくなるわけではありません。

リソース API によって CAE が実装されていて、CAE を処理できることがご利用のアプリケーションで宣言されている場合、アプリは、そのリソースに対する CAE トークンを受信します。 このため、CAE に対応する準備がアプリでできていることを宣言する場合、アプリケーションは、Microsoft Identity アクセス トークンを受け入れるすべてのリソース API の CAE 要求チャレンジを処理する必要があります。 これらの API 呼び出し内で CAE 応答を処理しない場合、返された有効期間内にまだあるが CAE のために取り消されているトークンにより、アプリで API 呼び出しを再試行するループが発生する可能性があります。

コード

最初の手順として、CAE のために呼び出しを拒否したリソース API からの応答を処理するコードを追加します。 CAE を使用すると、アクセス トークンが取り消されたとき、または使用している IP アドレスの変更が API で検出されたときに、401 状態と WWW-Authenticate ヘッダーが API から返されます。 この WWW-Authenticate には、アプリケーションが新しいアクセス トークンを取得するために使用できる要求チャレンジが含まれています。

次に例を示します。

// Line breaks for legibility only

HTTP 401; Unauthorized

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

アプリによって次のことが生じていないか確認されます。

• 401 状態を返す API 呼び出し
• 次の内容を含む WWW-Authenticate ヘッダーが存在すること
  • "insufficient_claims" という値を含む "error" パラメーター
  • "claims" パラメーター

.NET

これらの条件が満たされると、アプリは MSAL.NET WwwAuthenticateParameters クラスを使用してクレーム チャレンジを抽出およびデコードできます。

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

そして、アプリでは要求チャレンジを使用して、リソースに対する新しいアクセス トークンを取得します。

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

CAE 対応のリソースから返された要求チャレンジを処理する準備がアプリケーションでできたら、そのアプリが CAE に対応可能な状態にあることを Microsoft Identity に伝えることができます。 これをお使いの MSAL アプリケーションで行うには、"cp1" のクライアント機能を使用してパブリック クライアントを構築します。

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

ユーザーをアプリケーションにサインインさせてから、Azure portal を使用してユーザーのセッションを取り消すことで、アプリケーションをテストできます。 CAE 対応の API が次にアプリで呼び出されたとき、ユーザーは再認証を行うように求められます。

JavaScript

これらの条件が満たされると、アプリは API 応答ヘッダーから次のように要求チャレンジを抽出できます。

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

そして、アプリでは要求チャレンジを使用して、リソースに対する新しいアクセス トークンを取得します。

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

アプリケーションで CAE 対応のリソースから返された要求チャレンジを処理する準備ができたら、MSAL 構成に clientCapabilities プロパティを追加することで、そのアプリが CAE に対応可能な状態にあることを Microsoft Identity に伝えることができます。

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

const msalInstance = new PublicClientApplication(msalConfig);

ユーザーをサインインさせてから、Azure portal を使用してユーザーのセッションを取り消すことで、アプリケーションをテストできます。 CAE 対応の API が次にアプリで呼び出されたとき、ユーザーは再認証を行うように求められます。

コード サンプル

• ユーザーをサインインさせ、Microsoft Graph を呼び出すことを Angular シングルページ アプリケーションで可能にする
• ユーザーをサインインさせ、Microsoft Graph を呼び出すことを React シングルページ アプリケーションで可能にする
• ユーザーをサインインさせ、Microsoft Graph を呼び出すことを ASP.NET Core Web アプリで可能にする

次の手順

• 継続的アクセス評価の概念の概要
• 要求のチャレンジ、クレーム要求、およびクライアントの能力