Inizializzare le applicazioni client

  • 3 minuti

Con MSAL.NET 3.x, il modo consigliato per creare un'istanza di un'applicazione è usare i generatori di applicazioni: PublicClientApplicationBuilder e ConfidentialClientApplicationBuilder. che offrono un meccanismo potente per configurare l'applicazione dal codice o da un file di configurazione o persino con entrambi gli approcci.

Prima di inizializzare un'applicazione, è necessario registrarla in modo che l'app possa essere integrata con Microsoft Identity Platform. Dopo la registrazione, potrebbero essere necessarie le informazioni seguenti (disponibili nel portale di Azure):

  • ID applicazione (client): stringa che rappresenta un GUID.
  • ID directory (tenant): e fornisce funzionalità di gestione delle identità e degli accessi alle applicazioni e alle risorse usate dall'organizzazione. Può specificare se si sta scrivendo un'applicazione line-of-business esclusivamente per l'organizzazione (chiamata anche applicazione a singolo tenant).
  • URL del provider di identità (denominato istanza) e destinatari dell'accesso per l'applicazione. Questi due parametri sono noti con il nome collettivo di autorità.
  • Credenziali client, che può assumere la forma di un segreto dell'applicazione (stringa privata client) o di un certificato (di tipo X509Certificate2) se si tratta di un'app client riservata.
  • Per le app Web e talvolta per le app client pubbliche (in particolare quando l'app deve usare un broker), è necessario impostare anche l'URI di reindirizzamento al quale il provider di identità contatterà l'applicazione con i token di sicurezza.

Inizializzazione di applicazioni client pubbliche e riservate dal codice

Il codice seguente crea un'istanza di un'applicazione client pubblica, che consente agli utenti di accedere al cloud pubblico Microsoft Azure, con account aziendali e dell'istituto di istruzione o account Microsoft personali.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId).Build();

Allo stesso modo, il codice seguente crea un'istanza di un'applicazione riservata (un'app Web che si trova all'indirizzo https://myapp.azurewebsites.net) che gestisce i token degli utenti nel cloud pubblico Microsoft Azure, con account aziendali e dell'istituto di istruzione o account Microsoft personali. L'applicazione viene identificata con il provider di identità condividendo un segreto client:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

Modificatori per generatori

Nei frammenti di codice che usano i generatori di applicazioni, è possibile applicare metodi .With come modificatori (ad esempio, .WithAuthority e .WithRedirectUri).

  • Modificatore .WithAuthority: Il modificatore .WithAuthority imposta l'autorità predefinita dell'applicazione su un'autorità di Microsoft Entra, con la possibilità di scegliere il cloud di Azure, i destinatari, il tenant (ID tenant o nome di dominio) o di specificare direttamente l'URI dell'autorità.

    IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
    .Build();

  • Modificatore .WithRedirectUri: il modificatore .WithRedirectUri esegue l'override dell'URI di reindirizzamento predefinito.

    IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(client_id)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenant_id)
    .WithRedirectUri("http://localhost")
    .Build();

Modificatori comuni ad applicazioni client pubbliche e riservate

La tabella seguente elenca alcuni dei modificatori che è possibile impostare su un client pubblico o riservato.

Modificatore Descrizione
.WithAuthority() Imposta l'autorità predefinita dell'applicazione su un'autorità di Microsoft Entra, con la possibilità di scegliere il cloud di Azure, i destinatari, il tenant (ID tenant o nome di dominio) o di specificare direttamente l'URI dell'autorità.
.WithTenantId(string tenantId) Esegue l'override dell'ID tenant o della descrizione del tenant.
.WithClientId(string) Esegue l'override dell'ID client.
.WithRedirectUri(string redirectUri) Esegue l'override dell'URI di reindirizzamento predefinito. Questo è utile per gli scenari che richiedono un broker.
.WithComponent(string) Imposta il nome della libreria usando MSAL.NET (per motivi di telemetria).
.WithDebugLoggingCallback() Se chiamato, l'applicazione chiama Debug.Write abilitando semplicemente le tracce di debug.
.WithLogging() Se chiamato, l'applicazione chiama un callback con le tracce di debug.
.WithTelemetry(TelemetryCallback telemetryCallback) Imposta il delegato usato per inviare i dati di telemetria.

Modificatori specifici delle applicazioni client riservate

I modificatori specifici di un generatore di applicazioni client riservato sono disponibili nella classe ConfidentialClientApplicationBuilder. I diversi metodi sono disponibili nella documentazione di Azure SDK per .NET.

I modificatori come .WithCertificate(X509Certificate2 certificate) e .WithClientSecret(string clientSecret) si escludono a vicenda. Se si specificano entrambi, MSAL genera un'eccezione significativa.