取得權杖以使用精靈應用程式呼叫 Web API

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

要求的範圍

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

.NET

以下範例示範如何在設定 appsettings.json 檔案時定義 Web API 的範圍。 此範例取自 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]" ]
    }
}

Java

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

Node.js

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

Python

在 MSAL Python 中，設定檔應類似下列程式碼片段：

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

.NET (低層級)

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

Azure AD (v1.0) 資源

用戶端認證所使用的範圍，應一律為其後接著 /.default 的資源識別碼。

重要

當 MSAL 要求接受 1.0 版存取權杖之資源的存取權杖時，Microsoft Entra ID 會採用最後一個斜線之前的所有內容，並會將其用作為資源識別碼，藉此剖析要求範圍中的所需對象。 因此，以 Azure SQL Database (https://database.windows.net) 為例，若資源預期會有一個以斜線結尾的對象 (對於 Azure SQL Database 而言是 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 或其等同項目 (視平台而定)。

.NET

使用 Microsoft.Identity.Web，您就不需要取得權杖。 如從精靈應用程式呼叫 Web API 中所見，您可以使用較高層級的 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;

Java

此程式碼擷取自 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;
 }

Node.js

以下程式碼片段說明在 MSAL Node 保密用戶端應用程式中取得權杖的方式：

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

Python

# 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.

.NET (低層級)

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 方法，都會運用使用者權杖快取。)請勿在呼叫 AcquireTokenForClient 之前呼叫 AcquireTokenSilent，因為 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} 授與管理員同意] (其中 {Tenant Name} 是您目錄的名稱) 的大按鈕。

標準使用者

針對租用戶的標準使用者，請要求雲端應用程式管理員授與系統管理員同意應用程式。 若要這樣做，請將下列 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 的應用程式註冊。

下一步

.NET

繼續本案例的下一篇文章：呼叫 Web API。

Java

請繼續進入此案例的下一篇文章：呼叫 Web API。

Node.js

請繼續進入此案例的下一篇文章：呼叫 Web API。

Python

請繼續進入此案例的下一篇文章：呼叫 Web API。

.NET 低階

請繼續進入此案例的下一篇文章：呼叫 Web API。