Application de bureau appelant des API web : acquérir un jeton de manière interactive

L’exemple suivant montre le code minimal permettant d’obtenir un jeton de manière interactive pour lire le profil de l’utilisateur avec Microsoft Graph.

.NET

Code dans 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();
}

Paramètres obligatoires

AcquireTokenInteractive n’a qu’un seul paramètre obligatoire : scopes. il énumère les chaînes qui définissent les étendues pour lesquelles un jeton est requis. Si le jeton est destiné à Microsoft Graph, vous pouvez trouver les étendues nécessaires dans les informations de référence d’API de chaque API Microsoft Graph, dans la section intitulée « Autorisations ». Par exemple, pour répertorier les contacts de l’utilisateur, Les étendues User.Read et Contacts.Read doivent être utilisées. Pour plus d’informations, consultez la documentation de référence sur les autorisations Microsoft Graph.

Sur les applications de bureau et mobiles, il est important de spécifier le parent à l’aide de .WithParentActivityOrWindow. Dans de nombreux cas, il s’agit d’une exigence et MSAL lève des exceptions.

Pour les applications de bureau, consultez Handles de fenêtre parent.

Pour les applications mobiles, fournissez Activity (Android) ou UIViewController (iOS).

Paramètres facultatifs dans MSAL.NET

WithParentActivityOrWindow

L’interface utilisateur est importante, car elle est interactive. AcquireTokenInteractive présente un paramètre facultatif spécifique pouvant préciser, pour les plateformes qui le prennent en charge, l’interface utilisateur parente. Lorsqu’il est utilisé dans une application de bureau, .WithParentActivityOrWindow présente un type différent qui dépend la plateforme.

Vous pouvez également omettre le paramètre facultatif de fenêtre parente pour créer une fenêtre, si vous ne souhaitez pas contrôler l’emplacement où la boîte de dialogue de connexion s’affiche à l’écran. Cette option s’applique aux applications basées sur une ligne de commande, utilisées pour passer des appels à un autre service principal et qui n’ont besoin d’aucune fenêtre pour l’interaction utilisateur.

// 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).

Remarques :

• Sur .NET Standard, l’élément object attendu est Activity sur Android, UIViewController sur iOS, NSWindow sur Mac et IWin32Window ou IntPr sur Windows.

• Sur Windows, vous devez appeler AcquireTokenInteractive à partir du thread d’interface utilisateur, afin que le navigateur intégré obtienne le contexte de synchronisation de l’interface utilisateur approprié. Ne pas appeler depuis le thread d’interface utilisateur peut occasionner des messages qui ne pompent pas correctement, et des scénarios de blocage avec l’interface utilisateur. Pour appeler la bibliothèque d’authentification Microsoft (MSAL) à partir du thread d’interface utilisateur, si vous n’êtes pas déjà sur le thread, vous pouvez par exemple utiliser Dispatcher sur Windows Presentation Foundation (WPF).

• Si vous utilisez WPF, vous pouvez vous servir de la classe WindowInteropHelper.Handle pour obtenir une fenêtre à partir d’un contrôle WPF. L’appel est alors le suivant, à partir d’un contrôle WPF (this) :

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

WithPrompt

WithPrompt() permet de contrôler l’interactivité avec l’utilisateur en spécifiant une invite. Vous pouvez contrôler le comportement exact à l’aide de la structure Microsoft.Identity.Client.Prompt.

La structure définit les constantes suivantes :

• SelectAccount force le service d’émission de jeton de sécurité (STS) à présenter la boîte de dialogue de sélection de compte qui contient les comptes pour lesquels l’utilisateur dispose d’une session. Cette option est celle par défaut. Elle est utile lorsque vous souhaitez permettre aux utilisateurs de choisir entre différentes identités.

  Cette option oblige MSAL à envoyer prompt=select_account au fournisseur d’identité. Elle remplit bien sa mission en fournissant la meilleure expérience possible en fonction des informations disponibles, comme le compte et la présence d’une session pour l’utilisateur. Ne la remplacez pas, à moins d’avoir une excellente raison de le faire.

• Consent vous permet de forcer l’affichage d’une invite demandant à l’utilisateur son consentement, et même si celui-ci a été accordé auparavant. Dans ce cas, MSAL envoie prompt=consent au fournisseur d’identité. Cette option peut être utilisée dans certaines applications axées sur la sécurité, dans lesquelles la gouvernance de l’organisation exige que l’utilisateur voie s’afficher la boîte de dialogue de consentement chaque fois que l’application est utilisée.

• ForceLogin vous permet de faire afficher par le service une invite demandant à l’utilisateur d’entrer des informations d’identification, et même si cette invite utilisateur n’est peut-être pas nécessaire. Cette option peut s’avérer utile pour permettre à l’utilisateur de se reconnecter si l’acquisition d’un jeton échoue. Dans ce cas, MSAL envoie prompt=login au fournisseur d’identité. Les organisations l’utilisent parfois dans les applications axées sur la sécurité, pour lesquelles la gouvernance exige que les utilisateurs se reconnectent chaque fois qu’ils accèdent à des parties spécifiques d’une application.

• Create déclenche une expérience d’inscription, qui est utilisée pour les identités externes, en envoyant prompt=create au fournisseur d’identité. Les applications Azure Active Directory B2C (Azure AD B2C) ne doivent pas envoyer cette invite. Pour plus d’informations, consultez Ajouter un flux d’utilisateurs d’inscription en libre-service à une application.

• Never(pour .NET 4.5 et Windows Runtime uniquement) n’envoie pas d’invite à l’utilisateur. À la place, elle tente d’utiliser les cookies stockés dans la vue web incorporée, qui est masquée.

  L’utilisation de cette option peut échouer. Dans ce cas, AcquireTokenInteractive lève une exception pour vous notifier qu’il est nécessaire d’interagir avec l’interface utilisateur. Utilisez ensuite un autre paramètre Prompt.

• NoPrompt n’envoie pas d’invite au fournisseur d’identité. Le fournisseur d’identité détermine l’expérience de connexion la plus adaptée à l’utilisateur (authentification unique ou compte sélectionné).

  Cette option est obligatoire pour la modification des stratégies de profil dans Azure AD B2C. Pour plus d’informations, consultez Spécificités d’Azure Active Directory B2C.

WithUseEmbeddedWebView

Cette méthode vous permet de spécifier si vous souhaitez forcer l’utilisation d’une vue web intégrée ou de la vue web du système (si disponible). Pour plus d’informations, consultez Utilisation de navigateurs Web.

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

WithExtraScopeToConsent

Ce modificateur est destiné aux scénarios avancés où vous souhaitez que l’utilisateur consente à plusieurs ressources à l’avance et que vous ne souhaitez pas utiliser le consentement incrémentiel. Les développeurs utilisent normalement le consentement incrémentiel avec MSAL.NET et le Plateforme d’identités Microsoft. Pour plus d’informations, consultez Guide pratique pour obtenir le consentement préalable de l’utilisateur sur plusieurs ressources.

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

WithCustomWebUi

Une interface utilisateur web est un mécanisme pour appeler un navigateur. Ce mécanisme peut être un contrôle WebBrowser dédié avec interface utilisateur ou un moyen de déléguer l’ouverture du navigateur. MSAL fournit des implémentations d’interface utilisateur Web pour la plupart des plateformes, mais il existe des cas où vous pourriez préférer héberger vous-même le navigateur :

• Certaines plateformes ne sont pas couvertes explicitement par MSAL, comme Blazor, Unity et Mono sur les ordinateurs de bureau.
• Si vous souhaitez tester l’interface utilisateur de votre application et vous servir d’un navigateur automatisé qui peut être utilisé avec Selenium
• Si le navigateur et l’application qui exécutent MSAL se trouvent dans des processus distincts

Pour y parvenir, vous devez fournir start Url à MSAL : il doit s’afficher dans le navigateur de votre choix, afin que les utilisateurs finaux puissent entrer des informations, comme leur nom d’utilisateur. Une fois l'authentification terminée, votre application doit être renvoyée à MSAL end Url, qui contient un code fourni par Microsoft Entra ID. L’hôte de end Url est toujours redirectUri. Pour intercepter end Url, effectuez l’une des opérations suivantes :

• Superviser les redirections du navigateur jusqu’à atteindre redirect Url
• Demandez au navigateur de rediriger vers une URL que vous supervisez.

WithCustomWebUi est un point d’extensibilité que vous pouvez utiliser pour fournir votre propre interface utilisateur dans les applications clientes publiques. Vous pouvez également laisser les utilisateurs passer par le point de terminaison /Authorize du fournisseur d’identité et les autoriser à se connecter et à donner leur consentement. MSAL.NET peut alors échanger le code d’authentification pour obtenir un jeton.

Par exemple, WithCustomWebUi est utilisé dans Visual Studio, pour que des applications Electron (comme les commentaires Visual Studio) fournissent l’interaction Web tout en laissant MSAL.NET faire le gros du travail. Vous pouvez également utiliser WithCustomWebUi si vous voulez fournir l’automatisation de l’interface utilisateur.

Dans les applications clientes publiques, MSAL.NET utilise la norme PKCE (Proof Key for Code Exchange) pour garantir le respect de la sécurité. seul MSAL.NET peut échanger le code. Pour plus d’informations, consultez RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (RFC 7636 - Clé de preuve pour l’échange de clé par les clients publics OAuth).

using Microsoft.Identity.Client.Extensions;

Utiliser WithCustomWebUI

Pour utiliser WithCustomWebUI, suivez ces étapes :

1. Implémentez l'interface ICustomWebUi. Pour plus d’informations, consultez cet article GitHub.

2. Implémentez une méthode AcquireAuthorizationCodeAsync et acceptez l’URL de code d’autorisation calculée par MSAL.NET.

3. Permettez à l’utilisateur de parcourir l’interaction avec le fournisseur d’identité et de retourner l’URL par laquelle le fournisseur d’identité rappelait votre implémentation avec le code d’autorisation. Si vous rencontrez des problèmes, votre implémentation doit lever une exception MsalExtensionException afin de pouvoir coopérer avec MSAL.

4. Dans votre appel AcquireTokenInteractive, utilisez le modificateur .WithCustomUI() en passant l’instance de votre interface utilisateur Web personnalisée :

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

L’équipe de MSAL.NET a réécrit les tests d’interface utilisateur pour utiliser ce mécanisme d’extensibilité. Si vous êtes intéressé, examinez de plus près la classe SeleniumWebUI dans le code source MSAL.NET.

Fournir une bonne expérience avec SystemWebViewOptions

À partir de MSAL.NET 4.1 SystemWebViewOptions, vous pouvez spécifier :

• L’URI vers laquelle naviguer (BrowserRedirectError) ou le fragment HTML à afficher (HtmlMessageError) en cas d’erreurs de connexion ou de consentement dans le navigateur Web système.
• L’URI vers laquelle naviguer (BrowserRedirectSuccess) ou le fragment HTML à afficher (HtmlMessageSuccess) en cas de réussite de la connexion ou du consentement.
• L’action à exécuter pour démarrer le navigateur système. Vous pouvez fournir votre propre implémentation en définissant le délégué OpenBrowserAsync. La classe fournit également une implémentation par défaut pour deux navigateurs : OpenWithEdgeBrowserAsync et OpenWithChromeEdgeBrowserAsync, pour Microsoft Edge et Microsoft Edge sur Chromium, respectivement.

Pour utiliser cette structure, écrivez quelque chose de similaire à l’exemple suivant :

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

Autres paramètres facultatifs

Pour en savoir plus sur tous les autres paramètres facultatifs de AcquireTokenInteractive, consultez 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

Dans MSAL pour iOS et 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

Dans MSAL Node, vous acquérez des jetons par le biais d’un flux de code d’autorisation avec une clé de preuve pour la norme PKCE (Proof Key for Code Exchange). Le processus comporte deux étapes :

1. tout d’abord, l’application obtient une URL qui peut être utilisée pour générer un code d’autorisation. Les utilisateurs peuvent ouvrir l’URL dans un navigateur et entrer leurs informations d’identification. Ils sont ensuite redirigés vers redirectUri (inscrits lors de l’inscription de l’application) avec un code d’autorisation.
2. Ensuite, l’application transmet le code d’autorisation reçu à la méthode acquireTokenByCode() qui l’échange contre un jeton d’accès.

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+ fournit une méthode interactive pour l’acquisition d’un jeton :

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

Étapes suivantes

Passez à l’article suivant de ce scénario, Appeler une API web à partir de l’appareil de bureau.