Konfigurace aplikací démonů, které volají webová rozhraní API

Zjistěte, jak nakonfigurovat kód pro aplikaci démona, která volá webová rozhraní API.

Knihovny Microsoftu podporující aplikace démona

Následující knihovny Microsoftu podporují aplikace démona:

Jazyk / architektura	Project on GitHub	Balíček	Dostání z těchto možností	Přihlášení uživatelů	Přístup k webovým rozhraním API	Obecná dostupnost (GA) nebo Public Preview1
.NET	MSAL.NET	Microsoft.Identity.Client	Rychlý start			GA
Java	MSAL4J	msal4j	—			GA
Uzel	Uzel MSAL	msal-node	Rychlý start			GA
Python	MSAL Python	msal-python	Rychlý start			GA

¹ Univerzální licenční podmínky pro online služby se vztahují na knihovny ve verzi Public Preview.

Konfigurace autority

Aplikace démona používají oprávnění aplikace místo delegovaných oprávnění. Podporovaný typ účtu proto nemůže být účtem v žádném organizačním adresáři ani v žádném osobním účtu Microsoft (například Skype, Xbox, Outlook.com). Neexistuje žádný správce tenanta, který by udělil souhlas s aplikací démona pro osobní účet Microsoft. Potřebujete zvolit účty v mé organizaci nebo účtech v libovolné organizaci.

Autorita zadaná v konfiguraci aplikace by měla být tenantována (zadání ID tenanta nebo názvu domény přidruženého k vaší organizaci).

I když chcete poskytnout nástroj pro více tenantů, měli byste použít ID tenanta nebo název domény, a ne common nebo organizations s tímto tokem, protože služba nemůže spolehlivě odvodit, který tenant by se měl použít.

Konfigurace a vytvoření instance aplikace

V knihovnách MSAL se přihlašovací údaje klienta (tajný klíč nebo certifikát) předávají jako parametr výstavby důvěrných klientských aplikací.

Důležité

I když je vaše aplikace konzolovou aplikací, která běží jako služba, pokud se jedná o aplikaci démona, musí to být důvěrná klientská aplikace.

Konfigurační soubor

Konfigurační soubor definuje:

• Cloudová instance a ID tenanta, které společně tvoří autoritu.
• ID klienta, které jste získali z registrace aplikace.
• Tajný klíč klienta nebo certifikát.

.NET

Tady je příklad definování konfigurace v souboru appsettings.json. Tento příklad pochází z ukázky kódu démona konzoly .NET na GitHubu.

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

Místo tajného klíče klienta nebo přihlašovacích údajů federace identit úloh zadáte certifikát.

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

Parametry konfigurace pro ukázku démona Node.js jsou umístěny v souboru .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

Při vytváření důvěrného klienta s tajnými klíči klienta je konfigurační soubor parameters.json v ukázce démon Pythonu následující:

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

Při sestavování důvěrného klienta s certifikáty je konfigurační soubor parameters.json v ukázce démon Pythonu následující:

{
  "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 (nízká úroveň)

Tady je příklad definování konfigurace v souboru appsettings.json. Tento příklad pochází z ukázky kódu démona konzoly .NET na GitHubu.

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

Zadáte buď aClientSecret, nebo .CertificateName Tato nastavení jsou exkluzivní.

Vytvoření instance aplikace MSAL

Vytvoření instance aplikace MSAL, přidání, odkaz nebo import balíčku MSAL (v závislosti na jazyce).

Konstrukce se liší v závislosti na tom, jestli používáte tajné kódy klienta nebo certifikáty (nebo jako pokročilý scénář podepsané kontrolní výrazy).

Odkaz na balíček

Odkazujte na balíček MSAL v kódu aplikace.

.NET

Přidejte do aplikace balíček NuGet Microsoft.Identity.Web.TokenAcquisition . Případně pokud chcete volat Microsoft Graph, přidejte balíček Microsoft.Identity.Web.GraphServiceClient . Projekt může být následující. Soubor appsettings.json je potřeba zkopírovat do výstupního adresáře.

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

Do souboru Program.cs přidejte do kódu direktivu using , která odkazuje na 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

Nainstalujte balíčky spuštěním npm install ve složce, ve které package.json se nachází soubor. Potom balíček naimportujte msal-node :

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

Python

import msal
import json
import sys
import logging

.NET (nízká úroveň)

Přidejte do aplikace balíček NuGet Microsoft.Identity.Client a pak do kódu přidejte direktivu using , na kterou chcete odkazovat.

V MSAL.NET je důvěrná klientská aplikace reprezentována rozhraním IConfidentialClientApplication .

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

Vytvoření instance důvěrné klientské aplikace pomocí tajného klíče klienta

Tady je kód pro vytvoření instance důvěrné klientské aplikace tajným kódem klienta:

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

            // ...
        }
    }

Konfigurace se načte z 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 (nízká úroveň)

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

Jedná Authority se o zřetězení instance cloudu a ID tenanta, například https://login.microsoftonline.com/contoso.onmicrosoft.com https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee. V souboru appsettings.json zobrazeném v části Konfigurační soubor jsou instance a tenant reprezentovány Instance hodnotami a Tenant hodnotami.

V ukázce kódu, ze které byl předchozí fragment kódu převzat, Authority je vlastnost třídy AuthenticationConfig a je definována takto:

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

Vytvoření instance důvěrné klientské aplikace pomocí klientského certifikátu

Tady je kód pro sestavení aplikace s certifikátem:

.NET

Samotný kód je úplně stejný. Certifikát je popsaný v konfiguraci. Certifikát můžete získat mnoha způsoby. Podrobnosti najdete v tématu https://aka.ms/ms-id-web-certificates. Tady je postup, jak získat certifikát ze služby KeyVault. Identita Microsoftu deleguje na defaultAzureCredential služby Azure Identity a používá spravovanou identitu, pokud je k dispozici pro přístup k certifikátu z keyVaultu. Aplikaci můžete ladit místně, protože pak použije vaše přihlašovací údaje pro vývojáře.

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

Java

V MSAL Java existují dva tvůrci pro vytvoření instance důvěrné klientské aplikace s certifikáty:

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

nebo

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

Podrobnosti najdete v tématu Použití přihlašovacích údajů certifikátu s uzlem 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();

Pokročilý scénář: Vytvoření instance důvěrné klientské aplikace pomocí klientských kontrolních výrazů

.NET

Kromě použití tajného klíče klienta nebo certifikátu můžou důvěrné klientské aplikace také prokázat svou identitu pomocí klientských kontrolních výrazů. Podrobnosti najdete v tématu 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);

Podrobnosti najdete v tématu Inicializace objektu ConfidentialClientApplication.

Python

V MSAL Pythonu můžete poskytnout deklarace identity klientů pomocí deklarací identity, které budou podepsány tímto ConfidentialClientApplicationprivátním klíčem.

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

Podrobnosti najdete v referenční dokumentaci jazyka MSAL Python pro ConfidentialClientApplication.

.NET (nízká úroveň)

Místo tajného klíče klienta nebo certifikátu může důvěrná klientská aplikace také prokázat svou identitu pomocí klientských kontrolních výrazů.

MSAL.NET má dvě metody pro poskytnutí podepsaných kontrolních výrazů důvěrné klientské aplikaci:

• .WithClientAssertion()
• .WithClientClaims()

Při použití WithClientAssertionzadejte podepsaný JWT. Tento pokročilý scénář je podrobně popsán v kontrolních výrazech klienta.

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

Při použití WithClientClaimsMSAL.NET vytvoří podepsaný kontrolní výraz, který obsahuje deklarace identity očekávané id Microsoft Entra a další deklarace identity klienta, které chcete odeslat. Tento kód ukazuje, jak to udělat:

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

Podrobnosti najdete v tématu Klientské kontrolní výrazy.

Další kroky

.NET

Přejděte k dalšímu článku v tomto scénáři a získejte token aplikace.

Java

Přejděte k dalšímu článku v tomto scénáři a získejte token aplikace.

Node.js

Přejděte k dalšímu článku v tomto scénáři a získejte token aplikace.

Python

Přejděte k dalšímu článku v tomto scénáři a získejte token aplikace.

.NET (nízká úroveň)

Přejděte k dalšímu článku v tomto scénáři a získejte token aplikace.