Bureaublad-app die web-API's aanroept: een token interactief verkrijgen

In het volgende voorbeeld ziet u minimale code om een token interactief op te halen voor het lezen van het gebruikersprofiel met Microsoft Graph.

.NET

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

Verplichte parameters

AcquireTokenInteractive heeft slechts één verplichte parameter, scopes. Het bevat een opsomming van tekenreeksen waarmee de bereiken worden gedefinieerd waarvoor een token is vereist. Als het token voor Microsoft Graph is, kunt u de vereiste bereiken vinden in de API-verwijzing van elke Microsoft Graph API in de sectie 'Machtigingen'. Als u bijvoorbeeld de contactpersonen van de gebruiker wilt weergeven, moet u zowel User.Read als Contacts.Read als het bereik gebruiken. Raadpleeg Microsoft Graph-machtigingen voor meer informatie.

In zowel desktoptoepassingen als mobiele toepassingen is het belangrijk om het bovenliggende item op te geven met behulp van .WithParentActivityOrWindow. In veel gevallen is het een vereiste en MSAL genereert uitzonderingen.

Zie Voor bureaubladtoepassingen de bovenliggende venstergrepen.

Geef Activity voor mobiele toepassingen (Android) of (iOS) op UIViewController .

Optionele parameters in MSAL.NET

WithParentActivityOrWindow

De gebruikersinterface is belangrijk omdat deze interactief is. AcquireTokenInteractive heeft één specifieke optionele parameter die (voor platforms die deze ondersteunen) de bovenliggende gebruikersinterface kan opgeven. Wanneer u in een bureaubladtoepassing gebruikt .WithParentActivityOrWindow , heeft deze een ander type dat afhankelijk is van het platform.

U kunt ook de optionele bovenliggende vensterparameter weglaten om een venster te maken als u niet wilt bepalen waar het aanmeldingsdialoogvenster op het scherm wordt weergegeven. Deze optie is van toepassing op toepassingen die zijn gebaseerd op een opdrachtregel, worden gebruikt om aanroepen door te geven aan een andere back-endservice en hebben geen vensters nodig voor gebruikersinteractie.

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

Opmerkingen:

• In .NET Standard bevindt de verwachte object waarde zich Activity op Android, UIViewController in iOS, NSWindow op Mac en IWin32Window windows IntPr .

• In Windows moet u aanroepen AcquireTokenInteractive vanuit de UI-thread, zodat de ingesloten browser de juiste context voor ui-synchronisatie krijgt. Het niet aanroepen van de UI-thread kan ertoe leiden dat berichten niet goed worden gepompt en impassescenario's met de gebruikersinterface veroorzaken. Een manier om de Microsoft Authentication Library (MSAL) aan te roepen vanuit de UI-thread als u zich nog niet in de UI-thread bevindt, is om te gebruiken Dispatcher op Windows Presentation Foundation (WPF).

• Als u WPF gebruikt, kunt u de WindowInteropHelper.Handle klasse gebruiken om een venster op te halen van een WPF-besturingselement. Vervolgens is de aanroep afkomstig van een WPF-besturingselement (this):

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

WithPrompt

U gebruikt WithPrompt() om de interactiviteit met de gebruiker te beheren door een prompt op te geven. U kunt het exacte gedrag bepalen met behulp van de structuur Microsoft.Identity.Client.Prompt .

De structuur definieert de volgende constanten:

• SelectAccount dwingt de beveiligingstokenservice (STS) om het dialoogvenster accountselectie weer te geven dat accounts bevat waarvoor de gebruiker een sessie heeft. Dit is de standaardoptie. Het is handig als u gebruikers wilt laten kiezen uit verschillende identiteiten.

  Met deze optie stuurt MSAL prompt=select_account naar de id-provider. Het biedt de best mogelijke ervaring op basis van beschikbare informatie, zoals het account en de aanwezigheid van een sessie voor de gebruiker. Wijzig het alleen als u een goede reden hebt.

• Consent hiermee kunt u afdwingen dat de gebruiker om toestemming wordt gevraagd, zelfs als de toepassing daarvoor toestemming heeft verleend. In dit geval verzendt MSAL prompt=consent naar de id-provider. U kunt deze optie gebruiken in sommige toepassingen die zijn gericht op beveiliging, waarbij het governancevenster van de organisatie vereist dat het toestemmingsdialoogvenster telkens wordt weergegeven wanneer de gebruiker de toepassing opent.

• ForceLogin hiermee kunt u de gebruiker vragen om referenties, zelfs als deze gebruikersprompt mogelijk niet nodig is. Deze optie kan handig zijn om de gebruiker opnieuw aan te melden als het ophalen van tokens mislukt. In dit geval verzendt MSAL prompt=login naar de id-provider. Organisaties gebruiken deze optie soms in op beveiliging gerichte toepassingen waarbij governance vereist dat gebruikers zich telkens aanmelden wanneer ze toegang hebben tot specifieke onderdelen van een toepassing.

• Create activeert een registratie-ervaring voor externe identiteiten door deze naar de id-provider te verzenden prompt=create . Azure Active Directory B2C-apps (Azure AD B2C) mogen deze prompt niet verzenden. Zie Een selfservicegebruikersstroom voor registratie toevoegen aan een app voor meer informatie.

• Never (Alleen voor .NET 4.5 en Windows Runtime) wordt de gebruiker niet gevraagd. In plaats daarvan wordt geprobeerd de cookie te gebruiken die is opgeslagen in de verborgen ingesloten webweergave.

  Het gebruik van deze optie kan mislukken. In dat geval AcquireTokenInteractive genereert u een uitzondering om u op de hoogte te stellen dat u een interactie met de gebruikersinterface nodig hebt. Gebruik vervolgens een andere Prompt parameter.

• NoPrompt stuurt geen prompt naar de id-provider. De id-provider bepaalt welke aanmeldingservaring het beste is voor de gebruiker (eenmalige aanmelding of selecteer account).

  Deze optie is verplicht voor het bewerken van profielbeleid in Azure AD B2C. Zie Azure AD B2C-specifieke informatie voor meer informatie.

WithUseEmbeddedWebView

Met deze methode kunt u opgeven of u het gebruik van een ingesloten webweergave of de systeemwebweergave wilt afdwingen (indien beschikbaar). Zie Usage of web browsers (Gebruik van webbrowsers) voor meer informatie.

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

WithExtraScopeToConsent

Deze wijzigingsfunctie is bedoeld voor geavanceerde scenario's waarin u wilt dat de gebruiker toestemming geeft voor verschillende resources en u geen incrementele toestemming wilt gebruiken. Ontwikkelaars gebruiken normaal gesproken incrementele toestemming met MSAL.NET en het Microsoft Identity Platform. Zie De toestemming van de gebruiker vooraf hebben voor verschillende resources voor meer informatie.

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

WithCustomWebUi

Een webgebruikersinterface is een mechanisme om een browser aan te roepen. Dit mechanisme kan een toegewezen webbrowserbesturingselement voor de gebruikersinterface zijn of een manier om het openen van de browser te delegeren. MSAL biedt implementaties van webgebruikersinterfaces voor de meeste platforms, maar in deze gevallen wilt u de browser mogelijk zelf hosten:

• U hebt platforms die MSAL niet expliciet beslaat, zoals Blazor, Unity en Mono op desktops.
• U wilt uw toepassing testen en een geautomatiseerde browser gebruiken die kan worden gebruikt met Selenium.
• De browser en de app waarop MSAL wordt uitgevoerd, bevinden zich in afzonderlijke processen.

Om dit te bereiken, geeft u MSAL start Url, die moet worden weergegeven in een browser, zodat gebruikers items zoals hun gebruikersnaam kunnen invoeren. Nadat de verificatie is voltooid, moet uw app terugkeren naar MSAL end Url, dat een code bevat die microsoft Entra-id biedt. De host is end Url altijd redirectUri. Als u wilt onderscheppen end Url, voert u een van de volgende handelingen uit:

• Controleer browseromleidingen totdat redirect Url deze is bereikt.
• Laat de browser omleiden naar een URL die u bewaakt.

WithCustomWebUi is een uitbreidbaarheidspunt dat u kunt gebruiken om uw eigen gebruikersinterface in openbare clienttoepassingen te bieden. U kunt gebruikers ook het eindpunt van de id-provider laten doorlopen /Authorize en hen zich laten aanmelden en toestemming geven. MSAL.NET kunt vervolgens de verificatiecode inwisselen en een token ophalen.

U kunt bijvoorbeeld in Visual Studio electron-toepassingen (bijvoorbeeld Visual Studio Feedback) gebruiken WithCustomWebUi om de webinteractie te bieden, maar laat het aan MSAL.NET om het meeste werk uit te voeren. U kunt ook gebruiken WithCustomWebUi als u ui-automatisering wilt bieden.

In openbare clienttoepassingen gebruikt MSAL.NET de PKCE-standaard (Proof Key for Code Exchange) om ervoor te zorgen dat de beveiliging wordt gerespecteerd. Alleen MSAL.NET kan de code inwisselen. Zie RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients voor meer informatie.

using Microsoft.Identity.Client.Extensions;

Gebruiken metCustomWebUI

Voer de volgende stappen uit om te gebruiken WithCustomWebUI:

1. Implementeer de ICustomWebUi-interface. Zie deze GitHub-pagina voor meer informatie.

2. Implementeer één AcquireAuthorizationCodeAsyncmethode en accepteer de URL van de autorisatiecode die MSAL.NET berekeningen.

3. Laat de gebruiker de interactie met de id-provider doorlopen en de URL retourneren die de id-provider heeft gebruikt om uw implementatie terug te roepen, samen met de autorisatiecode. Als u problemen ondervindt, moet uw implementatie een MsalExtensionException uitzondering genereren om samen te werken met MSAL.

4. Gebruik in uw AcquireTokenInteractive aanroep de .WithCustomUI() wijzigingsfunctie door het exemplaar van uw aangepaste webgebruikersinterface door te geven:

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

Het MSAL.NET team heeft de UI-tests herschreven om dit uitbreidbaarheidsmechanisme te gebruiken. Als u geïnteresseerd bent, bekijkt u de SeleniumWebUI-klasse in de MSAL.NET broncode.

Een geweldige ervaring bieden met SystemWebViewOptions

Vanuit MSAL.NET 4.1 SystemWebViewOptionskunt u het volgende opgeven:

• De URI naar (BrowserRedirectError) of het HTML-fragment om weer te geven (HtmlMessageError) als aanmeldings- of toestemmingsfouten worden weergegeven in de webbrowser van het systeem.
• De URI om naar (BrowserRedirectSuccess) of het HTML-fragment te gaan om weer te geven (HtmlMessageSuccess) als aanmelden of toestemming is geslaagd.
• De actie die moet worden uitgevoerd om de systeembrowser te starten. U kunt uw eigen implementatie opgeven door de OpenBrowserAsync gedelegeerde in te stellen. De klasse biedt ook een standaard implementatie voor twee browsers: OpenWithEdgeBrowserAsync voor Microsoft Edge en OpenWithChromeEdgeBrowserAsync voor Microsoft Edge op Chromium.

Als u deze structuur wilt gebruiken, schrijft u iets zoals in het volgende voorbeeld:

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

Andere optionele parameters

Zie AcquireTokenInteractiveParameterBuilder voor meer informatie over de andere optionele parameters voorAcquireTokenInteractive.

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

Code in MSAL voor iOS en 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 verkrijgt u tokens via autorisatiecodestroom met Proof Key for Code Exchange (PKCE). Het proces bestaat uit twee stappen:

1. De toepassing verkrijgt een URL die kan worden gebruikt om een autorisatiecode te genereren. Gebruikers kunnen de URL openen in een browser en hun referenties invoeren. Ze worden vervolgens teruggeleid naar redirectUri (geregistreerd tijdens de app-registratie) met een autorisatiecode.
2. De toepassing geeft de ontvangen autorisatiecode door aan de acquireTokenByCode() methode, waarmee deze wordt uitgewisseld voor een toegangstoken.

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+ biedt een interactieve methode voor het verkrijgen van een 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"])

Volgende stappen

Ga verder met het volgende artikel in dit scenario, Een web-API aanroepen vanuit de desktop-app.