Skrivbordsapp som anropar webb-API:er: Hämta en token interaktivt

Gäller för: Workforce-klienter externa klienter (läs mer)

I följande exempel visas minimal kod för att hämta en token interaktivt för att läsa användarens profil med Microsoft Graph.

.NET

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

Obligatoriska parametrar

AcquireTokenInteractive har bara en obligatorisk parameter, scopes. Den innehåller en uppräkning av strängar som definierar de omfång som en token krävs för. Om token är för Microsoft Graph kan du hitta de nödvändiga omfången i API-referensen för varje Microsoft Graph-API i avsnittet "Behörigheter". Om du till exempel vill visa en lista över användarens kontakter måste du använda både User.Read och Contacts.Read som omfång. Mer information finns i Behörighetsreferens för Microsoft Graph.

I både skrivbords- och mobilapplikationer är det viktigt att specificera det överordnade objektet med hjälp av .WithParentActivityOrWindow. I många fall är det ett krav och MSAL utlöser undantag.

Information om skrivbordsprogram finns i Överordnade fönsterhandtag.

För mobila program anger du Activity (Android) eller UIViewController (iOS).

Valfria parametrar i MSAL.NET

WithParentActivityOrWindow

Användargränssnittet är viktigt eftersom det är interaktivt. AcquireTokenInteractive har en specifik valfri parameter som kan ange (för plattformar som stöder det) det överordnade användargränssnittet. När du använder .WithParentActivityOrWindow i ett skrivbordsprogram har det en annan typ som är beroende av plattformen.

Du kan också utelämna den valfria överordnade fönsterparametern för att skapa ett fönster, om du inte vill styra var inloggningsdialogrutan visas på skärmen. Det här alternativet gäller för program som baseras på en kommandorad, används för att skicka anrop till andra serverdelstjänster och behöver inga fönster för användarinteraktion.

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

Kommentarer:

• På .NET Standard är det förväntade object värdet på Android, UIViewController på iOS, NSWindow på Mac och IWin32Window eller IntPr på Windows.

• I Windows måste du anropa AcquireTokenInteractive från användargränssnittstråden så att den inbäddade webbläsaren får rätt kontext för användargränssnittssynkronisering. Att inte anropa från användargränssnittstråden kan leda till att meddelanden inte pumpar korrekt och orsakar dödlägesscenarier med användargränssnittet. Ett sätt att anropa Microsoft Authentication Library (MSAL) från användargränssnittstråden om du inte redan använder användargränssnittstråden är att använda Dispatcher i Windows Presentation Foundation (WPF).

• Om du använder WPF kan du använda WindowInteropHelper.Handle klassen för att hämta ett fönster från en WPF-kontroll. Sedan kommer anropet från en WPF-kontroll (this):

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

WithPrompt

Du använder WithPrompt() för att styra interaktiviteten med användaren genom att ange en uppmaning. Du kan styra det exakta beteendet med hjälp av strukturen Microsoft.Identity.Client.Prompt .

Strukturen definierar följande konstanter:

• SelectAccount tvingar säkerhetstokentjänsten (STS) att visa dialogrutan för kontoval som innehåller konton som användaren har en session för. Det här alternativet är standardinställningen. Det är användbart när du vill låta användarna välja mellan olika identiteter.

  Det här alternativet kör MSAL att skicka prompt=select_account till identitetsprovidern. Det ger bästa möjliga upplevelse baserat på tillgänglig information, till exempel kontot och förekomsten av en session för användaren. Ändra det inte om du inte har en bra anledning.

• Consent gör att du kan tvinga användaren att uppmanas att ge sitt medgivande, även om programmet har beviljats medgivande tidigare. I det här fallet skickar MSAL prompt=consent till identitetsprovidern. Du kan använda det här alternativet i vissa säkerhetsfokuserade program där organisationens styrning kräver att dialogrutan medgivande visas varje gång användaren öppnar programmet.

• ForceLogin gör att du kan få programmet att fråga användaren om autentiseringsuppgifter, även om den här användarprompten kanske inte behövs. Det här alternativet kan vara användbart för att låta användaren logga in igen om tokenförvärvet misslyckas. I det här fallet skickar MSAL prompt=login till identitetsprovidern. Organisationer använder ibland det här alternativet i säkerhetsfokuserade program där styrningen kräver att användarna loggar in varje gång de får åtkomst till specifika delar av ett program.

• Create utlöser en registreringsupplevelse för externa identiteter genom att skicka prompt=create till identitetsprovidern. Azure Active Directory B2C-appar (Azure AD B2C) bör inte skicka den här uppmaningen. Mer information finns i Lägga till ett användarflöde för självbetjäningsregistrering i en app.

• Never (endast för .NET 4.5 och Windows Runtime) frågar inte användaren. I stället försöker den använda cookien som lagras i den dolda inbäddade webbvyn.

  Det här alternativet kan misslyckas. I så fall AcquireTokenInteractive utlöser ett undantag för att meddela dig att du behöver en interaktion med användargränssnittet. Använd sedan en annan Prompt parameter.

• NoPrompt skickar ingen uppmaning till identitetsprovidern. Identitetsprovidern bestämmer vilken inloggningsupplevelse som är bäst för användaren (enkel inloggning eller välj konto).

  Det här alternativet är obligatoriskt för redigering av profilprinciper i Azure AD B2C. Mer information finns i Azure AD B2C-detaljer.

WithUseEmbeddedWebView

Med den här metoden kan du ange om du vill framtvinga användningen av en inbäddad WebView eller systemet WebView (när det är tillgängligt). Mer information finns i Användning av webbläsare.

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

MedExtraRäckviddFörSamtycke

Den här modifieraren är avsedd för avancerade scenarier där du vill att användaren ska godkänna flera resurser i förväg och du inte vill använda inkrementellt medgivande. Utvecklare använder vanligtvis inkrementellt medgivande med MSAL.NET och Microsofts identitetsplattform.

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

WithCustomWebUi

Ett webbgränssnitt är en mekanism för att anropa en webbläsare. Den här mekanismen kan vara en dedikerad WebBrowser-kontroll för användargränssnittet eller ett sätt att delegera öppnandet av webbläsaren. MSAL tillhandahåller implementeringar av webbgränssnittet för de flesta plattformar, men du kanske vill vara värd för webbläsaren själv i följande fall:

• Du har plattformar som MSAL inte uttryckligen täcker, till exempel Blazor, Unity och Mono på stationära datorer.
• Du vill testa ditt program och använda en automatiserad webbläsare som kan användas med Selenium.
• Webbläsaren och appen som kör MSAL finns i separata processer.

För att uppnå detta ger du till MSAL start Url, som måste visas i en webbläsare så att användare kan ange objekt som deras användarnamn. När autentiseringen är klar måste appen gå tillbaka till MSAL end Url, som innehåller en kod som Microsoft Entra ID tillhandahåller. Värden för end Url är alltid redirectUri. Om du vill fånga upp end Urlgör du något av följande:

• Övervaka webbläsarens omdirigeringar tills redirect Url nås.
• Låt webbläsaren omdirigeras till en URL som du övervakar.

WithCustomWebUi är en utökningspunkt som du kan använda för att tillhandahålla ditt eget användargränssnitt i offentliga klientprogram. Du kan också låta användare gå igenom identitetsleverantörens /Authorize slutpunkt och låta dem logga in samt ge samtycke. MSAL.NET kan sedan lösa in autentiseringskoden och hämta en token.

Du kan till exempel använda WithCustomWebUi i Visual Studio för att låta Electron-program (till exempel Visual Studio Feedback) tillhandahålla webbinteraktion, men lämna åt MSAL.NET att utföra det mesta av arbetet. Du kan också använda WithCustomWebUi om du vill tillhandahålla automatisering av användargränssnittet.

I offentliga klientprogram använder MSAL.NET PKCE-standarden (Proof Key for Code Exchange) för att säkerställa att säkerheten respekteras. Endast MSAL.NET kan lösa in koden. Mer information finns i RFC 7636 – Bevisnyckel för kodutbyte av offentliga OAuth-klienter.

using Microsoft.Identity.Client.Extensions;

Använd WithCustomWebUI

Följ dessa steg för att använda WithCustomWebUI:

1. Implementera gränssnittet ICustomWebUi. Mer information finns på den här GitHub-sidan.

2. Implementera en AcquireAuthorizationCodeAsyncmetod och godkänn auktoriseringskod-URL:en som MSAL.NET beräkningar.

3. Låt användaren gå igenom interaktionen med identitetsprovidern och returnera den URL som identitetsprovidern använde för att anropa implementeringen tillsammans med auktoriseringskoden. Om du har problem bör implementeringen utlösa ett MsalExtensionException undantag för att samarbeta med MSAL.

4. I ditt AcquireTokenInteractive anrop använder du .WithCustomUI() modifieraren genom att skicka instansen av ditt anpassade webbgränssnitt:

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

MSAL.NET-teamet har skrivit om användargränssnittstesterna för att använda den här utökningsmekanismen. Om du är intresserad kan du visa klassen SeleniumWebUI i MSAL.NET källkod.

Ge en bra upplevelse med SystemWebViewOptions

Från MSAL.NET 4.1 SystemWebViewOptionskan du ange:

• URI:n som ska öppnas (BrowserRedirectError) eller HTML-fragmentet som ska visas (HtmlMessageError) om det uppstår inloggnings- eller medgivandefel i systemets webbläsare.
• Den URI som ska gå till (BrowserRedirectSuccess) eller HTML-fragmentet för att visa (HtmlMessageSuccess) om inloggningen eller medgivandet lyckas.
• Åtgärden som ska köras för att starta systemwebbläsaren. Du kan tillhandahålla din egen implementering genom att ställa in delegeringen OpenBrowserAsync. Klassen tillhandahåller också en standardimplementering för två webbläsare: OpenWithEdgeBrowserAsync för Microsoft Edge och OpenWithChromeEdgeBrowserAsync för Microsoft Edge på Chromium.

Om du vill använda den här strukturen skriver du något som liknar följande exempel:

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

Andra valfria parametrar

Mer information om de andra valfria parametrarna för AcquireTokenInteractivefinns i 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

Kod i MSAL för iOS och 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

I MSAL Node hämtar du token via auktoriseringskodflöde med proof key for Code Exchange (PKCE). Processen har två steg:

1. Programmet hämtar en URL som kan användas för att generera en auktoriseringskod. Användare kan öppna URL:en i en webbläsare och ange sina autentiseringsuppgifter. De omdirigeras sedan tillbaka till redirectUri (registreras under appregistreringen) med en auktoriseringskod.
2. Programmet skickar den mottagna auktoriseringskoden till acquireTokenByCode() metoden, som byter ut den mot en åtkomsttoken.

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+ tillhandahåller en interaktiv metod för att hämta en 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"])

Nästa steg

• Lär dig mer genom att bygga en React Single-page application (SPA) som loggar in användare i följande självstudieserie i flera delar.

• Utforska Microsofts identitetsplattform exempel på skrivbordskod