取得令牌以使用精靈應用程式呼叫 Web API

發行項
04/09/2024

建構機密用戶端應用程式之後，您可以呼叫 AcquireTokenForClient、傳遞範圍，並選擇性地強制重新整理令牌，以取得應用程式的令牌。

要求的範圍

要求客戶端認證流程的範圍是資源的名稱， /.default後面接著。此表示法會告知 Microsoft Entra ID 在 應用程式註冊期間以靜態方式宣告的應用程式層級許可權 。此外，租用戶系統管理員必須授與這些 API 許可權。

以下是將 Web API 範圍定義為appsettings.json檔案中組態的一部分的範例。此範例取自 GitHub 上的 .NET 控制台精靈程式程式代碼範例。

{
    "AzureAd": {
        // Same AzureAd section as before.
    },

    "MyWebApi": {
        "BaseUrl": "https://localhost:44372/",
        "RelativePath": "api/TodoList",
        "RequestAppToken": true,
        "Scopes": [ "[Enter here the scopes for your web API]" ]
    }
}

final static String GRAPH_DEFAULT_SCOPE = "https://graph.microsoft.com/.default";

const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '.default'], // e.g. 'https://graph.microsoft.com/.default'
};

在 MSAL Python 中，組態檔看起來像下列代碼段：

{
    "scope": ["https://graph.microsoft.com/.default"],
}

ResourceId = "someAppIDURI";
var scopes = new [] {  ResourceId+"/.default"};

Azure AD （v1.0）資源

客戶端認證所使用的範圍應該一律是資源標識符， /.default後面接著。

重要

當 MSAL 要求接受 1.0 版存取令牌之資源的存取令牌時，Microsoft Entra ID 會藉由在最後一個斜線之前取得所有專案，並將其作為資源標識符，從要求的範圍剖析所需的物件。因此，如果如同 Azure SQL 資料庫（https://database.windows.net），資源預期物件會以斜線結尾（針對 Azure SQL 資料庫，https://database.windows.net/），您必須要求範圍https://database.windows.net//.default。（請注意雙斜線。另請參閱 MSAL.NET 問題 #747： Resource url's trailing slash is omitted, which caused sql auth failure。

AcquireTokenForClient API

若要取得應用程式的令牌，請使用 AcquireTokenForClient 或其對等項目，視平臺而定。

使用 Microsoft.Identity.Web 時，您不需要取得令牌。您可以使用較高層級的 API，如從精靈應用程式呼叫 Web API 中所見。不過，如果您使用需要令牌的 SDK，下列代碼段會示範如何取得此令牌。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

// In the Program.cs, acquire a token for your downstream API

var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
ITokenAcquirer acquirer = tokenAcquirerFactory.GetTokenAcquirer();
AcquireTokenResult tokenResult = await acquirer.GetTokenForUserAsync(new[] { "https://graph.microsoft.com/.default" });
string accessToken = tokenResult.AccessToken;

此程式代碼是從 MSAL Java 開發範例擷取。

private static IAuthenticationResult acquireToken() throws Exception {

     // Load token cache from file and initialize token cache aspect. The token cache will have
     // dummy data, so the acquireTokenSilently call will fail.
     TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

     IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
     ConfidentialClientApplication cca =
             ConfidentialClientApplication
                     .builder(CLIENT_ID, credential)
                     .authority(AUTHORITY)
                     .setTokenCacheAccessAspect(tokenCacheAspect)
                     .build();

     IAuthenticationResult result;
     try {
         SilentParameters silentParameters =
                 SilentParameters
                         .builder(SCOPE)
                         .build();

         // try to acquire token silently. This call will fail since the token cache does not
         // have a token for the application you are requesting an access token for
         result = cca.acquireTokenSilently(silentParameters).join();
     } catch (Exception ex) {
         if (ex.getCause() instanceof MsalException) {

             ClientCredentialParameters parameters =
                     ClientCredentialParameters
                             .builder(SCOPE)
                             .build();

             // Try to acquire a token. If successful, you should see
             // the token information printed out to console
             result = cca.acquireToken(parameters).join();
         } else {
             // Handle other exceptions accordingly
             throw ex;
         }
     }
     return result;
 }

下列代碼段說明 MSAL 節點機密用戶端應用程式中的權杖取得：

try {
    const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
    console.log(authResponse.accessToken) // display access token
} catch (error) {
    console.log(error);
}

# The pattern to acquire a token looks like this.
result = None

# First, the code looks up a token from the cache.
# Because we're looking for a token for the current app, not for a user,
# use None for the account parameter.
result = app.acquire_token_silent(config["scope"], account=None)

if not result:
    logging.info("No suitable token exists in cache. Let's get a new one from Azure AD.")
    result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    # Call a protected API with the access token.
    print(result["token_type"])
else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You might need this when reporting a bug.

using Microsoft.Identity.Client;

// With client credentials flows, the scope is always of the shape "resource/.default" because the
// application permissions need to be set statically (in the portal or by PowerShell), and then granted by
// a tenant administrator.
string[] scopes = new string[] { "https://graph.microsoft.com/.default" };

AuthenticationResult result = null;
try
{
 result = await app.AcquireTokenForClient(scopes)
                  .ExecuteAsync();
}
catch (MsalUiRequiredException ex)
{
    // The application doesn't have sufficient permissions.
    // - Did you declare enough app permissions during app creation?
    // - Did the tenant admin grant permissions to the application?
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
    // Invalid scope. The scope has to be in the form "https://resourceurl/.default"
    // Mitigation: Change the scope to be as expected.
}

AcquireTokenForClient 會使用應用程式令牌快取

在 MSAL.NET 中， AcquireTokenForClient 使用應用程式令牌快取。（所有其他 AcquireTokenXX 方法會使用使用者令牌快取。）請勿在呼叫之前呼叫 AcquireTokenSilentAcquireTokenForClient，因為 AcquireTokenSilent 會使用 使用者 令牌快取。 AcquireTokenForClient會檢查應用程式令牌快取本身並加以更新。

通訊協定

如果您還沒有所選語言的連結庫，您可能想要直接使用通訊協定：

第一個案例：使用共享密碼存取令牌要求

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=A1b-C2d_E3f.H4i,J5k?L6m!N7o-P8q_R9s.T0u
&grant_type=client_credentials

第二種情況：使用憑證存取令牌要求

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=aaaaaaaa-0b0b-...
&grant_type=client_credentials

如需詳細資訊，請參閱通訊協議檔：Microsoft 身分識別平台和 OAuth 2.0 用戶端認證流程。

疑難排解

您是否使用 resource/.default 範圍？

如果您收到錯誤訊息，告知您使用了無效的範圍，您可能未使用 resource/.default 範圍。

如果您在呼叫 API 時收到 許可權不足而無法完成作業 錯誤，租用戶系統管理員必須授與應用程式的許可權。

如果您未將系統管理員同意授與應用程式，您將遇到下列錯誤：

Failed to call the web API: Forbidden
Content: {
  "error": {
    "code": "Authorization_RequestDenied",
    "message": "Insufficient privileges to complete the operation.",
    "innerError": {
      "request-id": "<guid>",
      "date": "<date>"
    }
  }
}

視角色而定，選取下列其中一個選項。

全域租使用者管理員

針對全域租用戶系統管理員，請移至 Microsoft Entra 系統管理中心的企業應用程式 。選取應用程式註冊，然後從左窗格的 [安全性] 區段中選取 [許可權]。然後選取標示 為 [授與 {租用戶名稱} 管理員同意] 的大型按鈕（其中 {Tenant Name} 是目錄的名稱）。

標準使用者

針對租用戶的標準使用者，請要求 Global 管理員 istrator 授與系統管理員對應用程式的同意。若要這樣做，請提供下列URL給系統管理員：

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

在 URL 中：

Enter_the_Tenant_Id_Here取代為租使用者識別碼或租使用者名稱（例如，。 contoso.microsoft.com
Enter_the_Application_Id_Here 是已註冊應用程式的應用程式（用戶端）識別碼。

當您使用上述 URL 授與同意應用程式之後，可能會顯示此錯誤 AADSTS50011: No reply address is registered for the application 。之所以發生此錯誤，是因為應用程式和 URL 沒有重新導向 URI。請不用理會這一則訊息。

您要呼叫自己的 API 嗎？

如果您的精靈應用程式呼叫自己的 Web API，且您無法將應用程式許可權新增至精靈的應用程式註冊，您必須將應用程式角色新增至 Web API 的應用程式註冊。

下一步

請移至此案例中的下一篇文章，呼叫 Web API。