Cara mengonfigurasi aplikasi daemon yang memanggil API web

2025-06-26

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih. Penyewa Karyawan Lingkaran putih dengan simbol X abu-abu. Penyewa Eksternal (pelajari lebih lanjut)

Pelajari cara mengonfigurasi kode untuk aplikasi daemon Anda yang memanggil API web.

Pustaka Microsoft yang mendukung aplikasi daemon

Pustaka Microsoft berikut mendukung aplikasi daemon:

Bahasa pemrogram/kerangka kerja	Proyek tentang GitHub	Paket	Mendapatkan memulai	Tersedia secara umum (GA) atau Pratinjau umum¹
.NET	MSAL.NET	Microsoft.Identity.Client	Mulai Cepat	Majelis Umum
Jawa	MSAL4J	msal4j	—	Majelis Umum
Simpul	MSAL Node	msal-node	Mulai Cepat	Majelis Umum
Phyton	MSAL Python	msal-python	Mulai Cepat	Majelis Umum

¹Ketentuan Lisensi Universal untuk Layanan Online berlaku untuk pustaka di pratinjau publik.

Mengonfigurasi wewenang

Aplikasi Daemon menggunakan izin aplikasi alih-alih terdelegasi. Sehingga jenis akun mereka yang didukung tidak dapat menjadi akun di direktori organisasi atau akun Microsoft pribadi mana pun (contohnya, Skype, Xbox, Outlook.com). Tidak ada administrator penyewa untuk memberikan persetujuan kepada aplikasi daemon untuk akun personal Microsoft. Anda perlu memilih akun di organisasi saya atau akun di organisasi mana pun.

Otoritas yang ditentukan dalam konfigurasi aplikasi harus menyertakan ID penyewa ypur atau nama domain yang terkait dengan organisasi Anda.

Bahkan jika Anda ingin menyediakan alat multipenyewa, Anda harus menggunakan ID penyewa atau nama domain, dan jangan menggunakan common atau organizations dengan alur ini, karena layanan tidak dapat menyimpulkan penyewa mana yang harus digunakan.

Mengonfigurasi dan membuat instans aplikasi

Di Microsoft Authentication Libraries (MSAL), kredensial klien (rahasia atau sertifikat) diteruskan sebagai parameter konstruksi aplikasi klien rahasia.

Penting

Bahkan jika aplikasi Anda adalah aplikasi konsol yang dijalankan sebagai layanan, jika merupakan aplikasi daemon, maka perlu menjadi aplikasi klien rahasia.

File konfigurasi

File konfigurasi mendefinisikan:

Instans cloud dan ID penyewa, yang bersama-sama membentuk otoritas.
ID klien yang didapatkan dari pendaftaran aplikasi.
Sertifikat atau rahasia klien.

Berikut adalah contoh mendefinisikan konfigurasi dalam file appsettings.json. Contoh ini diambil dari sampel kode daemon konsol .NET di GitHub.

{
    "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]"
            }
        ]
    }
}

Anda memberikan sertifikat alih-alih rahasia klien, atau kredensial federasi identitas beban kerja.

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

Parameter konfigurasi untuk sampel daemon Node.js terletak dalam file .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/

Ketika Anda membangun klien rahasia dengan rahasia klien, file konfigurasi parameters.json dalam sampel daemon Python adalah sebagai berikut:

{
  "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"
}

Ketika Anda membangun klien rahasia dengan sertifikat, file konfigurasi parameters.json dalam sampel daemon Python adalah sebagai berikut:

{
  "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"
}

Berikut adalah contoh mendefinisikan konfigurasi dalam file appsettings.json. Contoh ini diambil dari sampel kode daemon konsol .NET di GitHub.

{
  "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]"
}

Anda menyediakan antara ClientSecret atau CertificateName. Pengaturan berikut bersifat eksklusif.

Menginisialisasi aplikasi MSAL

Untuk membuat instans aplikasi MSAL, tambahkan, rujuk, atau impor paket MSAL (tergantung pada bahasanya).

Konstruksinya berbeda, tergantung jika Anda menggunakan rahasia klien atau sertifikat (atau, sebagai skenario tingkat lanjut, pernyataan yang ditandatangani).

Merujuk ke paket

Rujuk paket MSAL dalam kode aplikasi Anda.

Tambahkan paket NuGet Microsoft.Identity.Web.TokenAcquisition ke aplikasi Anda. Atau, jika Anda ingin memanggil Microsoft Graph, tambahkan paket Microsoft.Identity.Web.GraphServiceClient . Proyek Anda bisa sebagai berikut. File appsettings.json perlu disalin ke direktori output.

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

Dalam file Program.cs, tambahkan using direktif dalam kode Anda untuk mereferensikan Microsoft.Identity.Web.

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

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;

Instal paket dengan menjalankan npm install di folder tempat package.json file berada. Kemudian, impor msal-node paket:

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

import msal
import json
import sys
import logging

Tambahkan paket NuGet Microsoft.Identity.Client ke aplikasi Anda, lalu tambahkan direktif using dalam kode Anda untuk merujukkannya.

Di MSAL.NET, aplikasi klien rahasia diwakili oleh antarmuka IConfidentialClientApplication.

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

Menginstansiasi aplikasi klien rahasia dengan rahasia klien

Ini adalah kode untuk membuat instans aplikasi klien rahasia dengan rahasia klien:

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

            // ...
        }
    }

Konfigurasi dibaca dari appsettings.json:

IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);

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


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

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

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

Authority adalah perangkaian instans cloud dan ID penyewa, contohnya https://login.microsoftonline.com/contoso.onmicrosoft.com atau https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee. Dalam file appsettings.json yang ditampilkan di bagian File konfigurasi, instans dan penyewa masing-masing diwakili oleh nilai Instance dan Tenant.

Dalam sampel kode tempat cuplikan sebelumnya diambil, Authority adalah properti pada kelas AuthenticationConfig, dan didefinisikan sebagai berikut:

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

Menginstansiasi aplikasi rahasia klien dengan sertifikat klien

Ini adalah kode untuk membangun aplikasi dengan sertifikat:

Kode itu sendiri persis sama. Sertifikat dijabarkan dalam konfigurasi. Ada banyak cara untuk mendapatkan sertifikat. Untuk detailnya lihat https://aka.ms/ms-id-web-certificates. Berikut adalah cara yang akan Anda lakukan untuk mendapatkan sertifikat Anda dari KeyVault. Identitas Microsoft mendelegasikan ke DefaultAzureCredential Azure Identity, dan menggunakan Identitas terkelola saat tersedia untuk mengakses sertifikat dari KeyVault. Anda dapat men-debug aplikasi Anda secara lokal karena kemudian menggunakan kredensial pengembang Anda.

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

Di MSAL Java, ada dua pembangun untuk menginisialisasi aplikasi klien rahasia dengan sertifikat.


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

atau

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


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

Untuk detailnya, lihat Menggunakan mandat sertifikat dengan Node MSAL.

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

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

Skenario tingkat lanjut: Menginisialisasi aplikasi klien rahasia dengan asersi klien

Selain menggunakan rahasia atau sertifikat klien, aplikasi klien rahasia juga dapat membuktikan identitas mereka dengan menggunakan pernyataan klien. Lihat CredentialDescription untuk detailnya.

IClientCredential credential = ClientCredentialFactory.createFromClientAssertion(assertion);

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

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

Untuk detailnya, lihat Menginisialisasi objek ConfidentialClientApplication.

Di Python MSAL, Anda dapat memberikan klaim klien dengan menggunakan klaim yang akan ditandatangani oleh kunci privat ConfidentialClientApplication ini.

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

Untuk detailnya, lihat dokumentasi referensi MSAL Python untuk ConfidentialClientApplication.

Alih-alih rahasia klien atau sertifikat, aplikasi klien rahasia juga dapat membuktikan identitasnya menggunakan asersi klien.

MSAL.NET memiliki dua metode untuk memberikan pernyataan tertandatangani ke aplikasi klien rahasia:

.WithClientAssertion()
.WithClientClaims()

Saat Anda menggunakan WithClientAssertion, berikan JWT yang tertandatangani. Skenario tingkat lanjut ini diperinci dalam Pernyataan klien.

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

Saat Anda menggunakan WithClientClaims, MSAL.NET menghasilkan pernyataan yang ditandatangani yang berisi klaim yang diharapkan oleh ID Microsoft Entra, ditambah klaim klien tambahan yang ingin Anda kirim. Kode ini menunjukkan cara melakukannya:

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

Sekali lagi, untuk detailnya, lihat Pernyataan klien.

Langkah berikutnya

Beralih ke artikel berikutnya dalam skenario ini, Peroleh token untuk aplikasi.