Web API'lerini çağıran daemon uygulamalarını yapılandırma

Şunlar için geçerlidir: İş gücü kiracıları (daha fazla bilgi edinin)

Web API'lerini çağıran daemon uygulamanızın kodunu yapılandırmayı öğrenin.

Daemon uygulamalarını destekleyen Microsoft kitaplıkları

Aşağıdaki Microsoft kitaplıkları daemon uygulamalarını destekler:

Dil / çerçeve	Proje açık GitHub (İngilizce)	Paket	Alma Başladı	Oturum açma kullanıcıları	Web API'lerine erişme	Genel kullanıma açık (GA) veya Genel önizleme1
.NET	MSAL.NET	Microsoft.Identity.Client	Hızlı Başlangıç			Georgia
Java	MSAL4J	msal4j	—			Georgia
Düğüm	MSAL Düğümü	msal-node	Hızlı Başlangıç			Georgia
Piton	MSAL Python	msal-python	Hızlı Başlangıç			Georgia

¹Çevrimiçi Hizmetler için Evrensel Lisans Koşulları, Genel önizlemedeki kitaplıklar için geçerlidir.

Yetkiliyi yapılandırma

Daemon uygulamaları, temsilci izinleri yerine uygulama izinlerini kullanır. Bu nedenle, desteklenen hesap türü herhangi bir kuruluş dizininde veya kişisel Microsoft hesabında (örneğin, Skype, Xbox, Outlook.com) bir hesap olamaz. Microsoft kişisel hesabı için bir daemon uygulamasına onay verebilecek bir kiracı yöneticisi yoktur. Kuruluşumdaki hesapları veya herhangi bir kuruluştaki hesapları seçmeniz gerekiyor.

Uygulama yapılandırmasında belirtilen yetki, kiracı kimliğinizi veya kuruluşunuzla ilişkilendirilmiş bir etki alanı adını içermelidir.

Çok kiracılı bir araç sağlamak isteseniz bile, bu akışta değilcommon veya organizations, bir kiracı kimliği ya da etki alanı adı kullanmalısınız; çünkü hizmet hangi kiracının kullanılması gerektiğini güvenilir biçimde belirleyemez.

Uygulamayı yapılandırın ve örneğini oluşturun

Microsoft Kimlik Doğrulama Kitaplıkları'nda (MSAL), istemci kimlik bilgileri (gizli veya sertifika), gizli istemci uygulaması oluşturma işleminin parametresi olarak geçirilir.

Önemli

Uygulamanız hizmet olarak çalışan bir konsol uygulaması olsa bile, bu bir daemon uygulamasıysa gizli bir istemci uygulaması olmalıdır.

Yapılandırma dosyası

Yapılandırma dosyası şunları tanımlar:

• Birlikte otoriteyi oluşturan bulut örneği ve kiracı kimliği.
• Uygulama kaydından edindiğiniz istemci kimliği.
• Ya istemci gizli anahtarı ya da sertifika.

.NET

Aşağıda, appsettings.json örnek yapılandırma dosyasında yapılandırmayı tanımlama örneği verilmiştır. Bu örnek GitHub'da .NET konsol daemon kodu örneğinden alınmıştır.

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

İstemci sırrı veya iş yükü kimliği federasyonu kimlik bilgileri yerine bir sertifika sunarsınız.

Java

Aşağıdaki örnekte, bir daemon uygulamasının Java yapılandırma sabitleri gösterilmektedir:

 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 daemon örneğinin yapılandırma parametreleri bir .env dosyasında bulunur:

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

Piton

İstemci gizli anahtarları kullanan bir gizli istemci oluşturduğunuzda, istemci gizli anahtarı akışına yönelik parameters.json örneği, Python daemon örneğindeki yapılandırma dosyasında aşağıdaki gibidir:

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

Sertifikalarla gizli bir istemci oluşturduğunuzda, Python daemon örneğindeki sertifika akışı yapılandırma dosyasınınparameters.json örneği aşağıdaki gibidir:

{
  "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 (düşük düzey)

Aşağıda, birappsettings.json daemon konsol yapılandırma dosyasında yapılandırmayı tanımlama örneği verilmiştir. Bu örnek GitHub'da .NET konsol daemon kodu örneğinden alınmıştır.

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

Ya ClientSecret ya da CertificateName sağlarsınız. Bu ayarlar özeldir.

MSAL uygulamasının örneğini oluşturun

MSAL uygulamasının örneğini açmak için MSAL paketini ekleyin, başvurun veya içeri aktarın (dile bağlı olarak).

Yapılandırma, istemci parolaları veya sertifikaları (ya da gelişmiş bir senaryoda imzalı beyanlar) kullanmanıza bağlı olarak farklılık gösterir.

Pakete başvurun

Uygulama kodunuza MSAL paketini ekleyin.

.NET

Uygulamanıza Microsoft.Identity.Web.TokenAcquisition NuGet paketini ekleyin. Alternatif olarak, Microsoft Graph'ı çağırmak istiyorsanız Microsoft.Identity.Web.GraphServiceClient paketini ekleyin. Projeniz aşağıdaki gibi olabilir. appsettings.json dosyasının çıkış dizinine kopyalanması gerekir.

<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 dosyasında, Microsoft.Identity.Web'e başvurmak için kodunuza bir using yönerge ekleyin.

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

Dosyasının bulunduğu npm install klasörde komutunu çalıştırarak package.json paketleri yükleyin. Ardından paketi içeri aktarın msal-node :

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

Piton

gerekli MSAL ve yardımcı modülleri Python uygulamanıza aktarın:

import msal
import json
import sys
import logging

.NET (düşük düzey)

Uygulamanıza Microsoft.Identity.Client NuGet paketini ekleyin ve ardından buna başvurmak için kodunuza bir using yönerge ekleyin.

MSAL.NET'te gizli istemci uygulaması, IConfidentialClientApplication arabirimiyle temsil edilir.

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

Gizli istemci uygulamasını bir istemci parolasıyla örnekleyin

İstemci parolasıyla gizli istemci uygulamasının örneğini oluşturmak için gereken kod aşağıdadır:

.NET

Aşağıdaki örnek, Microsoft.Identity.Web kullanarak bir istemci gizli anahtarıyla gizli istemci uygulamasını oluşturur:

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

            // ...
        }
    }

Yapılandırma, appsettings.json dosyasından okunur:

Java

İstemci parolasıyla gizli istemci uygulaması oluşturmak için aşağıdaki Java kodunu kullanın:

IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);

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

Node.js

İstemci parolasıyla gizli bir istemci uygulaması oluşturmak için aşağıdaki Node.js yapılandırmasını kullanın:

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

Piton

# 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 (düşük düzey)

Aşağıdaki MSAL.NET örneği, yapılandırılmış istemci gizli anahtarını kullanarak gizli istemci uygulaması oluşturur:

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

Authority, bulut örneğinin ve kiracı kimliğinin birleştirilmiş bir sonucudur, örneğin https://login.microsoftonline.com/contoso.onmicrosoft.com veya https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee. Yapılandırma dosyası bölümünde gösterilen appsettings.json dosyasında, örnek ve kiracı sırasıyla Instance ve Tenant değerleriyle temsil edilir.

Önceki kod parçacığının alındığı kod örneğinde AuthenticationConfig Authority sınıfındaki bir özelliktir ve şöyle tanımlanır:

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

Gizli istemci uygulamasının örneğini bir istemci sertifikasıyla oluşturun

Sertifikayla uygulama derleme kodu aşağıdadır:

.NET

Uygulama oluşturma kodu, istemci parolası örneğindekiyle aynıdır. Tek fark, sertifikanın bir gizli bilgi yerine yapılandırmada tanımlanmasıdır. Sertifikayı almanın birçok yolu vardır. Ayrıntılar için bkz. Microsoft Identity Web ile sertifikaları kullanma. Aşağıdaki yapılandırma örneği, sertifikanızı Azure Key Vault’tan nasıl alacağınızı gösterir. Microsoft identity, Azure Identity'in DefaultAzureCredential'ını temsil eder ve KeyVault'tan sertifikaya erişmek için kullanılabilir olduğunda Yönetilen kimliği kullanır. DefaultAzureCredential daha sonra geliştirici kimlik bilgilerinizi kullandığından uygulamanızın hatalarını yerel olarak ayıklayabilirsiniz.

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

Java

MSAL Java'da, gizli istemci uygulamasının örneğini sertifikalarla oluşturmak için iki oluşturucu vardır:

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

veya

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

Aşağıdaki Node.js örnek, gizli bir istemci uygulamasını sertifika kullanacak şekilde yapılandırıyor:

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

Ayrıntılar için MSAL Node ile sertifika kimlik bilgilerini kullanma bölümüne bakın.

Piton

# 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

Sertifika yüklemek ve gizli istemci uygulamasını oluşturmak için aşağıdaki MSAL.NET kodunu kullanın:

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

Gelişmiş senaryo: Gizli istemci uygulamasını istemci onaylarıyla oluşturma

.NET

Gizli istemci uygulamaları, istemci gizli dizisini veya sertifikayı kullanmanın yanı sıra, istemci beyanlarını kullanarak da kimliklerini kanıtlayabilir. Ayrıntılar için bkz . CredentialDescription .

Java

Aşağıdaki Java örnek, istemci onayı kullanarak gizli bir istemci uygulaması oluşturur:

IClientCredential credential = ClientCredentialFactory.createFromClientAssertion(assertion);

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

Node.js

Gizli bir istemci uygulamasını istemci onayıyla başlatmak için aşağıdaki Node.js yapılandırmasını kullanın:

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

Ayrıntılar için bkz . ConfidentialClientApplication nesnesini başlatma.

Piton

MSAL Python'da, bu ConfidentialClientApplication'nin özel anahtarıyla imzalanacak talepleri kullanarak istemci taleplerini belirtebilirsiniz.

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

Ayrıntılar için ConfidentialClientApplication için MSAL Python başvuru belgelerine bakın.

.NET (düşük düzey)

Gizli istemci uygulaması, istemci gizli anahtarı veya sertifika yerine istemci beyanlarını kullanarak kimliğini de kanıtlayabilir.

MSAL.NET gizli istemci uygulamasına imzalı onaylar sağlamak için iki yöntemi vardır:

• .WithClientAssertion()
• .WithClientClaims()

WithClientAssertion kullanırken imzalı bir JWT sağlayın. Bu gelişmiş senaryo, İstemci onaylarında ayrıntılı olarak anlatılır.

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

kullandığınızda WithClientClaims, MSAL.NET Microsoft Entra Id tarafından beklenen talepleri ve göndermek istediğiniz ek istemci taleplerini içeren imzalı bir onay oluşturur. Bu kod bunun nasıl yapılacağını gösterir:

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

Ayrıntılar için bkz. İstemci onayları.

Sonraki adımlar

.NET

Bu senaryoda uygulama için belirteç alma adlı sonraki makaleye geçin.

Java

Bu senaryoda sıradaki makale olan Uygulama için belirteç alma bölümüne geçin.

Node.js

Bu senaryoda uygulama için belirteç alma adlı sonraki makaleye geçin.

Piton

Bu senaryodaki bir sonraki makaleye, Uygulama için belirteç edinme, geçin.

.NET (düşük düzey)

Bu senaryoda sonraki makale olan Uygulama için bir belirteç edinme bölümüne geçin.