如何設定呼叫 Web API 的精靈應用程式

瞭解如何為呼叫 Web API 的精靈應用程式設定程式碼。

支援精靈應用程式的 Microsoft 連結庫

下列 Microsoft 連結庫支援精靈應用程式：

語言/ 架構	項目開啟 GitHub	套件	取得 啟動	登入使用者	存取 Web API	正式推出 （GA） 或 公開預覽1
.NET	MSAL.NET	Microsoft.Identity.Client	快速入門			GA
Java	MSAL4J	msal4j	—			GA
節點	MSAL 節點	msal-node	快速入門			GA
Python	MSAL Python	msal-python	快速入門			GA

¹在線服務的通用授權條款適用於公開預覽中的連結庫。

設定授權單位

精靈應用程式會使用應用程式許可權，而不是委派的許可權。 因此，其支持的帳戶類型不能是任何組織目錄中的帳戶或任何個人 Microsoft 帳戶（例如 Skype、Xbox、Outlook.com）。 沒有租用戶系統管理員可授與 Microsoft 個人帳戶精靈應用程式的同意。 您必須選擇 我組織中的 帳戶，或 任何組織中的帳戶。

應用程式組態中指定的授權單位應是租使用者（指定租使用者標識碼或與您組織相關聯的功能變數名稱）。

即使您想要提供多租使用者工具，您也應該使用租使用者標識碼或功能變數名稱，而不是commonorganizations使用此流程，因為服務無法可靠地推斷要使用哪一個租使用者。

設定和具現化應用程式

在 MSAL 連結庫中，客戶端認證（秘密或憑證）會傳遞為機密用戶端應用程式建構的參數。

重要

即使您的應用程式是以服務身分執行的控制台應用程式，如果是精靈應用程式，它必須是機密用戶端應用程式。

組態檔

組態檔會定義：

• 雲端實例和租用戶標識碼，共同組成 授權單位。
• 您從應用程式註冊取得的用戶端識別碼。
• 用戶端密碼或憑證。

.NET

以下是在 appsettings.json 檔案中定義組態的範例。 此範例取自 GitHub 上的 .NET 控制台精靈 程式程式代碼範例。

{
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "[Enter here the tenantID or domain name for your Azure AD tenant]",
        "ClientId": "[Enter here the ClientId for your application]",
        "ClientCredentials": [
            {
                "SourceType": "ClientSecret",
                "ClientSecret": "[Enter here a client secret for your application]"
            }
        ]
    }
}

您提供憑證，而不是客戶端密碼，或 工作負載身分識別同盟 認證。

Java

 private final static String CLIENT_ID = "";
 private final static String AUTHORITY = "https://login.microsoftonline.com/<tenant>/";
 private final static String CLIENT_SECRET = "";
 private final static Set<String> SCOPE = Collections.singleton("https://graph.microsoft.com/.default");

Node.js

Node.js精靈範例的組態參數位於 .env 檔案中：

# Credentials
TENANT_ID=Enter_the_Tenant_Info_Here
CLIENT_ID=Enter_the_Application_Id_Here

// You provide either a ClientSecret or a CertificateConfiguration, or a ClientAssertion. These settings are exclusive
CLIENT_SECRET=Enter_the_Client_Secret_Here
CERTIFICATE_THUMBPRINT=Enter_the_certificate_thumbprint_Here
CERTIFICATE_PRIVATE_KEY=Enter_the_certificate_private_key_Here
CLIENT_ASSERTION=Enter_the_Assertion_String_Here

# Endpoints
// the Azure AD endpoint is the authority endpoint for token issuance
AAD_ENDPOINT=Enter_the_Cloud_Instance_Id_Here // https://login.microsoftonline.com/
// the graph endpoint is the application ID URI of Microsoft Graph
GRAPH_ENDPOINT=Enter_the_Graph_Endpoint_Here // https://graph.microsoft.com/

Python

當您使用用戶端密碼建置機密用戶端時，Python 精靈範例中的parameters.json組態檔如下所示：

{
  "authority": "https://login.microsoftonline.com/<your_tenant_id>",
  "client_id": "your_client_id",
  "scope": [ "https://graph.microsoft.com/.default" ],
  "secret": "The secret generated by Azure AD during your confidential app registration",
  "endpoint": "https://graph.microsoft.com/v1.0/users"
}

當您使用憑證建置機密用戶端時，Python 精靈範例中的parameters.json組態檔如下所示：

{
  "authority": "https://login.microsoftonline.com/<your_tenant_id>",
  "client_id": "your_client_id",
  "scope": [ "https://graph.microsoft.com/.default" ],
  "thumbprint": "790E... The thumbprint generated by Azure AD when you upload your public cert",
  "private_key_file": "server.pem",
  "endpoint": "https://graph.microsoft.com/v1.0/users"
}

.NET （低階）

以下是在 appsettings.json 檔案中定義組態的範例。 此範例取自 GitHub 上的 .NET 控制台精靈 程式程式代碼範例。

{
  "Instance": "https://login.microsoftonline.com/{0}",
  "Tenant": "[Enter here the tenantID or domain name for your Azure AD tenant]",
  "ClientId": "[Enter here the ClientId for your application]",
  "ClientSecret": "[Enter here a client secret for your application]",
  "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]"
}

您提供 ClientSecret 或 CertificateName。 這些設定是獨佔的。

具現化 MSAL 應用程式

若要具現化 MSAL 應用程式，請新增、參考或匯入 MSAL 套件（視語言而定）。

建構不同，取決於您使用的是用戶端密碼或憑證（或作為進階案例，已簽署的判斷提示）。

參考套件

參考應用程式程式代碼中的 MSAL 套件。

.NET

將 Microsoft.Identity.Web.TokenAcquisition NuGet 套件新增至您的應用程式。 或者，如果您想要呼叫 Microsoft Graph，請新增 Microsoft.Identity.Web.GraphServiceClient 套件。 您的專案可能如下所示。 appsettings.json檔案必須複製到輸出目錄。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net7.0</TargetFramework>
    <RootNamespace>daemon_console</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Identity.Web.GraphServiceClient" Version="2.12.2" />
  </ItemGroup>

  <ItemGroup>
    <None Update="appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

在 Program.cs 檔案中，在您的程式代碼中新增 using 指示詞以參考 Microsoft.Identity.Web。

using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

Java

import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.MsalException;
import com.microsoft.aad.msal4j.SilentParameters;

Node.js

在檔案所在的資料夾中package.json執行 npm install ，以安裝套件。 然後，匯入 msal-node 套件：

const msal = require('@azure/msal-node');

Python

import msal
import json
import sys
import logging

.NET （低階）

將 Microsoft.Identity.Client NuGet 套件新增至您的應用程式，然後在程式碼中新增 using 指示詞以參考它。

在 MSAL.NET 中，機密用戶端應用程式是由 IConfidentialClientApplication 介面表示。

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

使用客戶端密碼具現化機密用戶端應用程式

以下是使用用戶端密碼具現化機密用戶端應用程式的程式代碼：

.NET

   class Program
    {
        static async Task Main(string[] _)
        {
            // Get the Token acquirer factory instance. By default it reads an appsettings.json
            // file if it exists in the same folder as the app (make sure that the 
            // "Copy to Output Directory" property of the appsettings.json file is "Copy if newer").
            TokenAcquirerFactory tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();

            // Configure the application options to be read from the configuration
            // and add the services you need (Graph, token cache)
            IServiceCollection services = tokenAcquirerFactory.Services;
            services.AddMicrosoftGraph();
            // By default, you get an in-memory token cache.
            // For more token cache serialization options, see https://aka.ms/msal-net-token-cache-serialization

            // Resolve the dependency injection.
            var serviceProvider = tokenAcquirerFactory.Build();

            // ...
        }
    }

組態會從 appsettings.json讀取：

Java

IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();

Node.js

const msalConfig = {
  auth: {
    clientId: process.env.CLIENT_ID,
    authority: process.env.AAD_ENDPOINT + process.env.TENANT_ID,
    clientSecret: process.env.CLIENT_SECRET,
  }
};

const apiConfig = {
  uri: process.env.GRAPH_ENDPOINT + 'v1.0/users',
};

const tokenRequest = {
  scopes: [process.env.GRAPH_ENDPOINT + '.default'],
};

const cca = new msal.ConfidentialClientApplication(msalConfig);

Python

# Pass the parameters.json file as an argument to this Python script. E.g.: python your_py_file.py parameters.json
config = json.load(open(sys.argv[1]))

# Create a preferably long-lived app instance that maintains a token cache.
app = msal.ConfidentialClientApplication(
    config["client_id"], authority=config["authority"],
    client_credential=config["secret"],
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

.NET （低階）

app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
           .WithClientSecret(config.ClientSecret)
           .WithAuthority(new Uri(config.Authority))
           .Build();

Authority是雲端實例和租使用者標識碼的串連，例如 https://login.microsoftonline.com/contoso.onmicrosoft.com 或 https://login.microsoftonline.com/eb1ed152-0000-0000-0000-32401f3f9abd。 在組態檔區段中顯示的appsettings.json檔案中，實例和租用戶分別以 Instance 和 Tenant 值表示。

在程式代碼範例中，前一個代碼段是從 中擷取的，Authority是 AuthenticationConfig 類別上的 屬性，並定義為：

/// <summary>
/// URL of the authority
/// </summary>
public string Authority
{
    get
    {
        return String.Format(CultureInfo.InvariantCulture, Instance, Tenant);
    }
}

使用客戶端憑證具現化機密用戶端應用程式

以下是使用憑證建置應用程式的程式代碼：

.NET

程序代碼本身完全相同。 憑證會在組態中描述。 有許多方式可以取得憑證。 如需詳細資訊，請參閱 https://aka.ms/ms-id-web-certificates。 以下是從 KeyVault 取得憑證的方式。 Microsoft 身分識別會委派給 Azure 身分識別的 DefaultAzureCredential，並在可用時使用受控識別從 KeyVault 存取憑證。 您可以在本機對應用程式進行偵錯，因為它接著會使用您的開發人員認證。

  "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://yourKeyVaultUrl.vault.azure.net",
        "KeyVaultCertificateName": "NameOfYourCertificate"
      }

Java

在 MSAL Java 中，有兩個建置器可使用憑證具現化機密用戶端應用程式：

InputStream pkcs12Certificate = ... ; /* Containing PCKS12-formatted certificate*/
string certificatePassword = ... ;    /* Contains the password to access the certificate */

IClientCredential credential = ClientCredentialFactory.createFromCertificate(pkcs12Certificate, certificatePassword);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();

或

PrivateKey key = getPrivateKey(); /* RSA private key to sign the assertion */
X509Certificate publicCertificate = getPublicCertificate(); /* x509 public certificate used as a thumbprint */

IClientCredential credential = ClientCredentialFactory.createFromCertificate(key, publicCertificate);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();

Node.js

const config = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + process.env.TENANT_ID,
        clientCertificate: {
            thumbprint:  process.env.CERTIFICATE_THUMBPRINT, // a 40-digit hexadecimal string
            privateKey:  process.env.CERTIFICATE_PRIVATE_KEY,
        }
    }
};

// Create an MSAL application object
const cca = new msal.ConfidentialClientApplication(config);

如需詳細資訊，請參閱 搭配 MSAL 節點使用憑證認證。

Python

# Pass the parameters.json file as an argument to this Python script. E.g.: python your_py_file.py parameters.json
config = json.load(open(sys.argv[1]))

# Create a preferably long-lived app instance that maintains a token cache.
app = msal.ConfidentialClientApplication(
    config["client_id"], authority=config["authority"],
    client_credential={"thumbprint": config["thumbprint"], "private_key": open(config['private_key_file']).read()},
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

.NET

X509Certificate2 certificate = ReadCertificate(config.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
    .WithCertificate(certificate)
    .WithAuthority(new Uri(config.Authority))
    .Build();

進階案例：使用客戶端判斷提示具現化機密用戶端應用程式

.NET

除了使用客戶端密碼或憑證之外，機密用戶端應用程式也可以使用用戶端判斷提示來證明其身分識別。 如需詳細資訊，請參閱 CredentialDescription 。

Java

IClientCredential credential = ClientCredentialFactory.createFromClientAssertion(assertion);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();

Node.js

const clientConfig = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + process.env.TENANT_ID,
        clientAssertion:  process.env.CLIENT_ASSERTION
    }
};
const cca = new msal.ConfidentialClientApplication(clientConfig);

如需詳細資訊，請參閱 初始化 ConfidentialClientApplication 物件。

Python

在 MSAL Python 中，您可以使用此 ConfidentialClientApplication私鑰所簽署的宣告來提供用戶端宣告。

# Pass the parameters.json file as an argument to this Python script. E.g.: python your_py_file.py parameters.json
config = json.load(open(sys.argv[1]))

# Create a preferably long-lived app instance that maintains a token cache.
app = msal.ConfidentialClientApplication(
    config["client_id"], authority=config["authority"],
    client_credential={"thumbprint": config["thumbprint"], "private_key": open(config['private_key_file']).read()},
    client_claims = {"client_ip": "x.x.x.x"}
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

如需詳細資訊，請參閱 ConfidentialClientApplication 的 MSAL Python 參考檔。

.NET （低階）

機密用戶端應用程式也可以使用用戶端判斷提示來證明其身分識別，而不是客戶端密碼或憑證。

MSAL.NET 有兩種方法可將已簽署的判斷提示提供給機密用戶端應用程式：

• .WithClientAssertion()
• .WithClientClaims()

當您使用 WithClientAssertion時，請提供已簽署的 JWT。 此進階案例詳述於 客戶端判斷提示中。

string signedClientAssertion = ComputeAssertion();
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithClientAssertion(signedClientAssertion)
                                          .Build();

當您使用 WithClientClaims時，MSAL.NET 會產生包含 Microsoft Entra ID 預期宣告的已簽署判斷提示，以及您想要傳送的其他用戶端宣告。 此程式代碼示範如何執行此動作：

string ipAddress = "192.168.1.2";
var claims = new Dictionary<string, string> { { "client_ip", ipAddress } };
X509Certificate2 certificate = ReadCertificate(config.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithAuthority(new Uri(config.Authority))
                                          .WithClientClaims(certificate, claims)
                                          .Build();

同樣地，如需詳細資訊，請參閱 客戶端判斷提示。

下一步

.NET

請移至此案例中的下一篇文章， 取得應用程式的令牌。

Java

請移至此案例中的下一篇文章， 取得應用程式的令牌。

Node.js

請移至此案例中的下一篇文章， 取得應用程式的令牌。

Python

請移至此案例中的下一篇文章， 取得應用程式的令牌。

.NET （低階）

請移至此案例中的下一篇文章， 取得應用程式的令牌。