App desktop che chiama le API Web: acquisire un token in modo interattivo

Nell'esempio seguente viene illustrato il codice minimo per ottenere un token in modo interattivo per la lettura del profilo dell'utente con Microsoft Graph.

.NET

Codice in MSAL.NET

string[] scopes = new string[] { "user.read" };

var app = PublicClientApplicationBuilder.Create("YOUR_CLIENT_ID")
    .WithDefaultRedirectUri()
    .Build();

var accounts = await app.GetAccountsAsync();

AuthenticationResult result;
try
{
    result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
      .ExecuteAsync();
}
catch (MsalUiRequiredException)
{
    result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();
}

Parametri obbligatori

AcquireTokenInteractive ha un solo parametro obbligatorio, scopes. Contiene un'enumerazione di stringhe che definiscono gli ambiti per i quali è necessario un token. Se il token è per Microsoft Graph, è possibile trovare gli ambiti necessari nel riferimento API di ogni API Microsoft Graph nella sezione denominata "Autorizzazioni". Ad esempio, per elencare i contatti dell'utente, è necessario usare sia User.Read che Contacts.Read come ambito. Per altre informazioni, vedere le Informazioni di riferimento per le autorizzazioni dell'API Microsoft Graph.

Nelle applicazioni desktop e per dispositivi mobili è importante specificare l'elemento padre usando .WithParentActivityOrWindow. In molti casi, si tratta di un requisito e MSAL genererà eccezioni.

Per le applicazioni desktop, vedere Handle di finestra padre.

Per le applicazioni per dispositivi mobili, fornire Activity (Android) o UIViewController (iOS).

Parametri facoltativi in MSAL.NET

WithParentActivityOrWindow

L'interfaccia utente è importante perché è interattiva. AcquireTokenInteractive ha un parametro facoltativo specifico che può specificare (per le piattaforme che lo supportano) l'interfaccia utente padre. Quando si usa .WithParentActivityOrWindow in un'applicazione desktop, ha un tipo diverso che dipende dalla piattaforma.

In alternativa, è possibile omettere il parametro facoltativo della finestra padre per creare una finestra, se non si vuole controllare dove viene visualizzata la finestra di dialogo di accesso. Questa opzione è applicabile alle applicazioni basate su una riga di comando, vengono usate per passare chiamate a qualsiasi altro servizio back-end e non richiedono finestre per l'interazione dell'utente.

// net45
WithParentActivityOrWindow(IntPtr windowPtr)
WithParentActivityOrWindow(IWin32Window window)

// Mac
WithParentActivityOrWindow(NSWindow window)

// .NET Standard (this will be on all platforms at runtime, but only on .NET Standard platforms at build time)
WithParentActivityOrWindow(object parent).

Note:

• In .NET Standard il valore previsto object è Activity in Android, UIViewController in iOS, NSWindow in Mac e IWin32Window o IntPr in Windows.

• In Windows è necessario chiamare AcquireTokenInteractive dal thread di interfaccia utente in modo che il browser incorporato ottenga il contesto di sincronizzazione dell'interfaccia utente appropriato. La mancata chiamata dal thread dell'interfaccia utente potrebbe causare il mancato pompare correttamente i messaggi e causare scenari di deadlock con l'interfaccia utente. Un modo per chiamare Microsoft Authentication Library (MSAL) dal thread dell'interfaccia utente se non si è già presenti nel thread dell'interfaccia utente consiste nell'usare Dispatcher in Windows Presentation Foundation (WPF).

• Se si usa WPF, per ottenere una finestra da un controllo WPF, è possibile usare la classe WindowInteropHelper.Handle. La chiamata proviene quindi da un controllo WPF (this):

  result = await app.AcquireTokenInteractive(scopes)
                    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
                    .ExecuteAsync();
  

WithPrompt

WithPrompt() Usare per controllare l'interattività con l'utente specificando una richiesta. È possibile controllare il comportamento esatto usando la struttura Microsoft.Identity.Client.Prompt .

La struttura definisce le costanti seguenti:

• SelectAccount forza il servizio token di sicurezza (STS) a presentare la finestra di dialogo di selezione dell'account contenente gli account per i quali l'utente dispone di una sessione. Questa opzione è quella predefinita. È utile quando si vuole consentire agli utenti di scegliere tra identità diverse.

  Questa opzione consente a MSAL di inviare prompt=select_account al provider di identità. Offre la migliore esperienza possibile in base alle informazioni disponibili, ad esempio l'account e la presenza di una sessione per l'utente. Non modificarlo a meno che tu non abbia un buon motivo.

• Consent consente di forzare l'immissione del consenso dell'utente, anche se l'applicazione ha concesso il consenso prima. In questo caso, MSAL invia prompt=consent al provider di identità. È possibile usare questa opzione in alcune applicazioni incentrate sulla sicurezza in cui la governance dell'organizzazione richiede che la finestra di dialogo di consenso venga visualizzata ogni volta che l'utente apre l'applicazione.

• ForceLogin consente all'applicazione di richiedere le credenziali all'utente, anche se potrebbe non essere necessario questo prompt utente. Questa opzione può essere utile per consentire all'utente di accedere di nuovo se l'acquisizione del token ha esito negativo. In questo caso, MSAL invia prompt=login al provider di identità. Le organizzazioni usano talvolta questa opzione nelle applicazioni incentrate sulla sicurezza in cui la governance richiede agli utenti di accedere ogni volta che accedono a parti specifiche di un'applicazione.

• Create attiva un'esperienza di iscrizione per le identità esterne inviando prompt=create al provider di identità. Le app di Azure Active Directory B2C (Azure AD B2C) non devono inviare questa richiesta. Per altre informazioni, vedere Aggiungere un flusso utente di iscrizione self-service a un'app.

• Never (solo per .NET 4.5 e Windows Runtime) non richiede l'utente. Tenta invece di usare il cookie archiviato nella visualizzazione Web incorporata nascosta.

  L'uso di questa opzione potrebbe non riuscire. In tal caso, AcquireTokenInteractive genera un'eccezione per notificare che è necessaria un'interazione dell'interfaccia utente. Usare quindi un altro Prompt parametro.

• NoPrompt non invia alcuna richiesta al provider di identità. Il provider di identità decide quale esperienza di accesso è migliore per l'utente (Single Sign-On o selezionare l'account).

  Questa opzione è obbligatoria per la modifica dei criteri dei profili in Azure AD B2C. Per altre informazioni, vedere Specifiche di Azure AD B2C.

WithUseEmbeddedWebView

Questo metodo consente di specificare se si desidera forzare l'utilizzo di un controllo WebView incorporato o webView di sistema (se disponibile). Per altre informazioni, vedere Utilizzo dei Web browser.

var result = await app.AcquireTokenInteractive(scopes)
                    .WithUseEmbeddedWebView(true)
                    .ExecuteAsync();

WithExtraScopeToConsent

Questo modificatore è destinato agli scenari avanzati in cui si vuole consentire all'utente di fornire il consenso a diverse risorse in anticipo e non si vuole usare il consenso incrementale. Gli sviluppatori usano in genere il consenso incrementale con MSAL.NET e Microsoft Identity Platform.

var result = await app.AcquireTokenInteractive(scopesForCustomerApi)
                     .WithExtraScopeToConsent(scopesForVendorApi)
                     .ExecuteAsync();

WithCustomWebUi

Un'interfaccia utente Web è un meccanismo per richiamare un browser. Questo meccanismo può essere un controllo WebBrowser dell'interfaccia utente dedicato o un modo per delegare l'apertura del browser. MSAL fornisce implementazioni dell'interfaccia utente Web per la maggior parte delle piattaforme, ma potrebbe essere necessario ospitare manualmente il browser in questi casi:

• Sono disponibili piattaforme che MSAL non copre in modo esplicito, ad esempio Blazor, Unity e Mono nei desktop.
• Quando si vuole testare l'interfaccia utente dell'applicazione e usare un browser automatizzato che può essere utilizzato con Selenium.
• Quando il browser e l'app che eseguono MSAL risiedono in processi separati.

A tale scopo, si assegna a MSAL start Url, che deve essere visualizzato in un browser in modo che gli utenti possano immettere elementi come il nome utente. Al termine dell'autenticazione, l'app deve tornare a MSAL end Url, che contiene un codice fornito da Microsoft Entra ID. L'host di end Url è sempre redirectUri. Per intercettare end Url, eseguire una di queste operazioni:

• Monitorare i reindirizzamenti del browser fino a quando non viene raggiunto redirect Url.
• Fare in modo che il browser esegua il reindirizzamento a un URL monitorato.

WithCustomWebUi è un punto di estendibilità che è possibile usare per fornire una propria interfaccia utente in applicazioni client pubbliche. È anche possibile consentire agli utenti di passare attraverso l'endpoint /Authorize del provider di identità e consentire loro di accedere e fornire il consenso. MSAL.NET può quindi riscattare il codice di autenticazione e ottenere un token.

Ad esempio, è possibile usare WithCustomWebUi in Visual Studio per fare in modo che le applicazioni Electron (ad esempio, Commenti e suggerimenti di Visual Studio) forniscano l'interazione Web, ma lasciare MSAL.NET per eseguire la maggior parte del lavoro. È anche possibile usare WithCustomWebUi se si vuole fornire l'automazione dell'interfaccia utente.

Nelle applicazioni client pubbliche MSAL.NET usa lo standard PKCE (Proof Key for Code Exchange) per garantire il rispetto della sicurezza. Solo MSAL.NET può riscattare il codice. Per altre informazioni, vedere il memo RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (RFC 7636 - Chiave di prova per lo scambio di codice dei client pubblici OAuth).

using Microsoft.Identity.Client.Extensions;

Usare WithCustomWebUI

Per usare WithCustomWebUI, seguire questa procedura:

1. Implementare l'interfaccia ICustomWebUi. Per altre informazioni, vedere questa pagina di GitHub.

2. Implementare un AcquireAuthorizationCodeAsyncmetodo e accettare l'URL del codice di autorizzazione che MSAL.NET calcola.

3. Consentire all'utente di eseguire l'interazione con il provider di identità e restituire l'URL usato dal provider di identità per richiamare l'implementazione, insieme al codice di autorizzazione. In caso di problemi, l'implementazione deve generare un'eccezione MsalExtensionException per collaborare con MSAL.

4. AcquireTokenInteractive Nella chiamata usare il .WithCustomUI() modificatore passando l'istanza dell'interfaccia utente Web personalizzata:

   result = await app.AcquireTokenInteractive(scopes)
                     .WithCustomWebUi(yourCustomWebUI)
                     .ExecuteAsync();
   

Il team di MSAL.NET ha riscritto i test dell'interfaccia utente per usare questo meccanismo di estendibilità. Se si è interessati, visualizzare la classe SeleniumWebUI nel codice sorgente MSAL.NET.

Offrire un'esperienza ottimale con SystemWebViewOptions

Da SystemWebViewOptions in MSAL.NET 4.1 è possibile specificare:

• URI da passare a (BrowserRedirectError) o al frammento HTML da visualizzare (HtmlMessageError) se vengono visualizzati errori di accesso o consenso nel Web browser di sistema.
• URI da passare a (BrowserRedirectSuccess) o al frammento HTML da visualizzare (HtmlMessageSuccess) se l'accesso o il consenso ha esito positivo.
• Azione da eseguire per avviare il browser del sistema. È possibile fornire un'implementazione personalizzata impostando il delegato OpenBrowserAsync. La classe fornisce anche un'implementazione predefinita per due browser: OpenWithEdgeBrowserAsync per Microsoft Edge e OpenWithChromeEdgeBrowserAsync per Microsoft Edge su Chromium.

Per usare questa struttura, scrivere un codice simile all'esempio seguente:

IPublicClientApplication app;
...

options = new SystemWebViewOptions
{
 HtmlMessageError = "<b>Sign-in failed. You can close this tab ...</b>",
 BrowserRedirectSuccess = "https://contoso.com/help-for-my-awesome-commandline-tool.html"
};

var result = app.AcquireTokenInteractive(scopes)
                .WithEmbeddedWebView(false)       // The default in .NET
                .WithSystemWebViewOptions(options)
                .Build();

Altri parametri facoltativi

Per informazioni sugli altri parametri facoltativi per AcquireTokenInteractive, vedere AcquireTokenInteractiveParameterBuilder.

Java

private static IAuthenticationResult acquireTokenInteractive() throws Exception {

    // Load the token cache from the file and initialize the token cache aspect. The token cache will have
    // dummy data, so the acquireTokenSilently call will fail.
    TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

    PublicClientApplication pca = PublicClientApplication.builder(CLIENT_ID)
            .authority(AUTHORITY)
            .setTokenCacheAccessAspect(tokenCacheAspect)
            .build();

    Set<IAccount> accountsInCache = pca.getAccounts().join();
    // Take the first account in the cache. In a production application, you would filter
    // accountsInCache to get the right account for the user who is authenticating.
    IAccount account = accountsInCache.iterator().next();

    IAuthenticationResult result;
    try {
        SilentParameters silentParameters =
                SilentParameters
                        .builder(SCOPE, account)
                        .build();

        // try to acquire the token silently. This call will fail because the token cache
        // does not have any data for the user you're trying to acquire a token for
        result = pca.acquireTokenSilently(silentParameters).join();
    } catch (Exception ex) {
        if (ex.getCause() instanceof MsalException) {

            InteractiveRequestParameters parameters = InteractiveRequestParameters
                    .builder(new URI("http://localhost"))
                    .scopes(SCOPE)
                    .build();

            // Try to acquire a token interactively with the system browser. If successful, you should see
            // the token and account information printed out to the console
            result = pca.acquireToken(parameters).join();
        } else {
            // Handle other exceptions accordingly
            throw ex;
        }
    }
    return result;
}

macOS

Codice in MSAL per iOS e macOS

MSALInteractiveTokenParameters *interactiveParams = [[MSALInteractiveTokenParameters alloc] initWithScopes:scopes webviewParameters:[MSALWebviewParameters new]];
[application acquireTokenWithParameters:interactiveParams completionBlock:^(MSALResult *result, NSError *error) {
    if (!error)
    {
        // You'll want to get the account identifier to retrieve and reuse the account
        // for later acquireToken calls
        NSString *accountIdentifier = result.account.identifier;

        NSString *accessToken = result.accessToken;
    }
}];

let interactiveParameters = MSALInteractiveTokenParameters(scopes: scopes, webviewParameters: MSALWebviewParameters())
application.acquireToken(with: interactiveParameters, completionBlock: { (result, error) in

    guard let authResult = result, error == nil else {
        print(error!.localizedDescription)
        return
    }

    // Get the access token from the result
    let accessToken = authResult.accessToken
})

Node.js

In MSAL Node si acquisiscono i token tramite il flusso del codice di autorizzazione con la chiave di prova per lo scambio di codice (PKCE). Il processo prevede due passaggi:

1. L'applicazione ottiene un URL che può essere usato per generare un codice di autorizzazione. Gli utenti possono aprire l'URL in un browser e immettere le credenziali. Vengono quindi reindirizzati a redirectUri (registrati durante la registrazione dell'app) con un codice di autorizzazione.
2. L'applicazione passa il codice di autorizzazione ricevuto al acquireTokenByCode() metodo , che lo scambia per un token di accesso.

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

const msalConfig = {
    auth: {
        clientId: "your_client_id_here",
        authority: "your_authority_here",
    }
};

const pca = new msal.PublicClientApplication(msalConfig);

const {verifier, challenge} = await msal.cryptoProvider.generatePkceCodes();

const authCodeUrlParameters = {
    scopes: ["User.Read"],
    redirectUri: "your_redirect_uri",
    codeChallenge: challenge, // PKCE code challenge
    codeChallengeMethod: "S256" // PKCE code challenge method 
};

// Get the URL to sign in the user and consent to scopes needed for the application
pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => {
    console.log(response);

    const tokenRequest = {
        code: response["authorization_code"],
        codeVerifier: verifier // PKCE code verifier 
        redirectUri: "your_redirect_uri",
        scopes: ["User.Read"],
    };

    // Acquire a token by exchanging the code
    pca.acquireTokenByCode(tokenRequest).then((response) => {
        console.log("\nResponse: \n:", response);
    }).catch((error) => {
        console.log(error);
    });
}).catch((error) => console.log(JSON.stringify(error)));

Python

MSAL Python 1.7+ fornisce un metodo interattivo per l'acquisizione di un token:

result = None

# Check the cache to see if this user has signed in before
accounts = app.get_accounts(username=config["username"])
if accounts:
    result = app.acquire_token_silent(config["scope"], account=accounts[0])

if not result:
    result = app.acquire_token_interactive(  # It automatically provides PKCE protection
         scopes=config["scope"])

Passaggi successivi

• Per ulteriori informazioni, creare un'applicazione a pagina singola (SPA) che effettua l'accesso degli utenti nella seguente serie di esercitazioni in più parti.

• Esplorare gli esempi di codice desktop di Microsoft Identity Platform