Come configurare le app daemon che chiamano le API Web

Articolo
07/02/2024

Informazioni su come configurare il codice per l'applicazione daemon che chiama le API Web.

Librerie Microsoft che supportano le app daemon

Le librerie Microsoft seguenti supportano app daemon:

Linguaggio/framework	Progetto in GitHub	Pacchetto	Recupero avviata	Disponibile a livello generale (GA) o Anteprima pubblica¹
.NET	MSAL.NET	Microsoft.Identity.Client	Guida introduttiva	Disponibilità generale
Java	MSAL4J	msal4j	—	Disponibilità generale
Nodo	MSAL Node	msal-node	Guida introduttiva	Disponibilità generale
Python	MSAL Python	msal-python	Guida introduttiva	Disponibilità generale

^{1 Le} condizioni di licenza universali per i servizi online si applicano alle librerie in anteprima pubblica.

Configurare l'autorità

Le applicazioni daemon usano autorizzazioni dell'applicazione anziché autorizzazioni delegate. Quindi il tipo di account supportato non può essere un account in alcuna directory organizzativa o in qualsiasi account Microsoft personale (ad esempio, Skype, Xbox, Outlook.com). Non è previsto alcun amministratore tenant per concedere il consenso a un'applicazione daemon per un account personale Microsoft. È necessario scegliere gli account nella propria organizzazione o gli account in qualsiasi organizzazione.

L'autorità specificata nella configurazione dell'applicazione deve essere con tenant (è necessario specificare un ID tenant o un nome di dominio associato all'organizzazione).

Anche se si vuole fornire uno strumento multi-tenant, è consigliabile usare un ID tenant o un nome di dominio e non common o organizations con questo flusso, perché il servizio non può dedurre in modo affidabile quale tenant deve essere usato.

Configurare e creare un'istanza dell'applicazione

Nelle librerie MSAL le credenziali client (segreto o certificato) vengono passate come parametro della costruzione di applicazioni client riservate.

Importante

Anche se l'applicazione è un'applicazione console che viene eseguita come servizio, deve essere un’applicazione client riservata se si tratta di un'applicazione daemon.

File di configurazione

Il file di configurazione definisce:

L'istanza cloud e l'ID tenant, che insieme costituiscono l'autorità.
L’ID client ottenuto dalla registrazione dell'applicazione.
Un segreto client o un certificato.

Ecco un esempio di definizione della configurazione in un file appsettings.json. Questo esempio è tratto dall'esempio di codice del daemon della console .NET in 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]"
            }
        ]
    }
}

Specificare un certificato anziché il segreto client, o le credenziali di federazione dell'identità del carico di lavoro.

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

I parametri di configurazione per l'esempio di daemon Node.js si trovano in un file con estensione 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/

Quando si compila un client riservato con segreti client, il file di configurazione parameters.json nell'esempio del daemon Python è il seguente:

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

Quando si compila un client riservato con certificati, il file di configurazione parameters.json nell'esempio del daemon Python è il seguente:

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

Ecco un esempio di definizione della configurazione in un file appsettings.json. Questo esempio è tratto dall'esempio di codice del daemon della console .NET in 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]"
}

Specificare un oggetto ClientSecret o un oggetto CertificateName. Queste impostazioni sono esclusive.

Creare un'istanza dell'applicazione MSAL

Per creare un'istanza dell'applicazione MSAL, aggiungere, fare riferimento o importare il pacchetto MSAL (a seconda della lingua).

La costruzione è diversa, a seconda che si usino segreti client o certificati (o asserzioni firmate in uno scenario avanzato).

Fare riferimento al pacchetto

Fare riferimento al pacchetto MSAL nel codice dell'applicazione.

Aggiungere il pacchetto NuGet Microsoft.Identity.Web.TokenAcquisition all'applicazione. In alternativa, se si vuole chiamare Microsoft Graph, aggiungere il pacchetto Microsoft.Identity.Web.GraphServiceClient. Il progetto potrebbe essere il seguente. Il file appsettings.json deve essere copiato nella directory di 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>

Nel file Program.cs aggiungere una direttiva using nel codice per fare riferimento a 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;

Installare i pacchetti eseguendo npm install nella cartella in cui si trova il file package.json. Quindi, importare il pacchetto msal-node:

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

import msal
import json
import sys
import logging

Aggiungere il pacchetto NuGet Microsoft.Identity.Client all'applicazione e quindi aggiungere una direttiva using nel codice per farvi riferimento.

In MSAL.NET, l'applicazione client riservata è rappresentata dall'interfaccia IConfidentialClientApplication.

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

Creare un'istanza dell'applicazione client riservata con un segreto client

Ecco il codice per creare un'istanza dell'applicazione client riservata con un segreto client:

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

            // ...
        }
    }

La configurazione viene letta da 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 è una concatenazione dell'istanza cloud e dell'ID tenant, ad esempio https://login.microsoftonline.com/contoso.onmicrosoft.com o https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee. Nel file appsettings.json illustrato nella sezione File di configurazione, l'istanza e il tenant sono rappresentati rispettivamente dai valori Instance e Tenant.

Nell'esempio di codice da cui è stato tratto il frammento precedente Authority è una proprietà della classe AuthenticationConfig ed è definita come tale:

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

Creare un'istanza dell'applicazione client riservata con un certificato client

Ecco il codice per compilare un'applicazione con un certificato:

Il codice stesso è esattamente lo stesso. Il certificato è descritto nella configurazione. Esistono molti modi per ottenere il certificato. Per informazioni dettagliate, vedere https://aka.ms/ms-id-web-certificates. Ecco come ottenere il certificato da KeyVault. L’identità di Microsoft delega DefaultAzureCredential dell'identità di Azure e usa l'identità gestita, se disponibile, per accedere al certificato da KeyVault. È possibile eseguire il debug dell'applicazione in locale, perché usa le credenziali per sviluppatore.

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

In MSAL Java sono disponibili due generatori per creare un'istanza dell'applicazione client riservata con certificati:


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


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

Per informazioni dettagliate, vedere Usare le credenziali del certificato con il nodo 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();

Scenario avanzato: Creare un'istanza dell'applicazione client riservata con asserzioni client

Oltre a usare un segreto client o un certificato, le applicazioni client riservate possono dimostrare la loro identità anche con le asserzioni client. Per informazioni dettagliate, vedere CredentialDescription.

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

Per informazioni dettagliate, vedere Inizializzare l'oggetto ConfidentialClientApplication.

In MSAL Python è possibile fornire attestazioni client usando le attestazioni che verranno firmate dalla chiave privata di 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
    )

Per informazioni dettagliate, vedere la documentazione di riferimento di MSAL Python per ConfidentialClientApplication.

Anziché usare un segreto client o un certificato, l'applicazione client riservata può anche dimostrare la propria identità usando asserzioni client.

MSAL.NET include due metodi per fornire asserzioni firmate all'app client riservata:

.WithClientAssertion()
.WithClientClaims()

Quando si usa WithClientAssertion, specificare un token JWT firmato. Questo scenario avanzato è dettagliato in Asserzioni client.

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

Quando si usa WithClientClaims, MSAL.NET produce un'asserzione firmata che contiene le attestazioni previste da Microsoft Entra ID, oltre alle attestazioni client aggiuntive che si vuole inviare. Questo codice illustra come eseguire questa operazione:

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

Anche in questo caso, per informazioni dettagliate, vedere Asserzioni client.

Passaggi successivi

Passare all'articolo successivo in questo scenario, Acquisire un token per l'app.

Condividi tramite