Aplicativo de área de trabalho que chama APIs da Web: adquira um token interativamente

O exemplo a seguir mostra o código mínimo para obter um token interativamente para ler o perfil do usuário com o Microsoft Graph.

.NET

Código em 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();
}

Parâmetros obrigatórios

AcquireTokenInteractive tem apenas um parâmetro obrigatório, scopes. Ele contém uma enumeração de cadeias de caracteres que definem os escopos para os quais um token é necessário. Se o token for para o Microsoft Graph, você poderá encontrar os escopos necessários na referência de API de cada API do Microsoft Graph na seção chamada "Permissões". Por exemplo, para listar os contatos do usuário, você deve usar ambos User.Read e Contacts.Read como o escopo. Para obter mais informações, veja Referência de permissões do Microsoft Graph.

Em aplicativos móveis e de desktop, é importante especificar o pai usando .WithParentActivityOrWindow. Em muitos casos, é um requisito e a MSAL lançará exceções.

Para aplicativos da área de trabalho, consulte Identificadores de janela pai.

Para aplicativos móveis, forneça Activity (Android) ou UIViewController (iOS).

Parâmetros opcionais no MSAL.NET

WithParentActivityOrWindow

A interface do usuário é importante porque é interativa. AcquireTokenInteractive tem um parâmetro opcional específico que pode especificar (para plataformas que o suportam) a interface do usuário pai. Quando você usa .WithParentActivityOrWindow em um aplicativo de desktop, ele tem um tipo diferente que depende da plataforma.

Como alternativa, você pode omitir o parâmetro opcional da janela pai para criar uma janela, se não quiser controlar onde a caixa de diálogo de entrada aparece na tela. Essa opção é aplicável para aplicativos baseados em uma linha de comando, usados para passar chamadas para qualquer outro serviço back-end e não precisam de janelas para interação do usuário.

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

Observações:

• No .NET Standard, o valor esperado object está Activity no Android, UIViewController no iOS, NSWindow no Mac e IWin32Window ou IntPr no Windows.

• No Windows, você deve chamar AcquireTokenInteractive a partir do thread da interface do usuário para que o navegador incorporado obtenha o contexto de sincronização da interface do usuário apropriado. Não chamar a partir do thread da interface do usuário pode fazer com que as mensagens não bombeiem corretamente e causar cenários de bloqueio com a interface do usuário. Uma maneira de chamar a Biblioteca de Autenticação da Microsoft (MSAL) do thread da interface do usuário se você ainda não estiver no thread da interface do usuário é usar Dispatcher no Windows Presentation Foundation (WPF).

• Se você estiver usando WPF, para obter uma janela de um controle WPF, você pode usar a WindowInteropHelper.Handle classe. Em seguida, a chamada é de um controle WPF (this):

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

ComPrompt

Você usa WithPrompt() para controlar a interatividade com o usuário especificando um prompt. Você pode controlar o comportamento exato usando a estrutura Microsoft.Identity.Client.Prompt .

A estrutura define as seguintes constantes:

• SelectAccount força o serviço de token de segurança (STS) a apresentar a caixa de diálogo de seleção de conta que contém contas para as quais o usuário tem uma sessão. Esta é a opção predefinida. É útil quando você deseja permitir que os usuários escolham entre identidades diferentes.

  Esta opção leva a MSAL a enviar prompt=select_account para o provedor de identidade. Ele fornece a melhor experiência possível com base nas informações disponíveis, como a conta e a presença de uma sessão para o usuário. Não o altere, a menos que tenha uma boa razão.

• Consent Permite que você force o usuário a ser solicitado a dar consentimento, mesmo que o aplicativo tenha concedido consentimento antes. Nesse caso, o MSAL envia prompt=consent para o provedor de identidade. Você pode usar essa opção em alguns aplicativos focados em segurança em que a governança da organização exige que a caixa de diálogo de consentimento apareça sempre que o usuário abrir o aplicativo.

• ForceLogin Permite que o aplicativo solicite credenciais ao usuário, mesmo que esse prompt do usuário não seja necessário. Essa opção pode ser útil para permitir que o usuário entre novamente se a aquisição de token falhar. Nesse caso, o MSAL envia prompt=login para o provedor de identidade. Às vezes, as organizações usam essa opção em aplicativos focados em segurança, onde a governança exige que os usuários entrem cada vez que acessam partes específicas de um aplicativo.

• Create Aciona uma experiência de inscrição para identidades externas enviando prompt=create para o provedor de identidade. Os aplicativos do Azure Ative Directory B2C (Azure AD B2C) não devem enviar esse prompt. Para obter mais informações, consulte Adicionar um fluxo de usuário de inscrição de autoatendimento a um aplicativo.

• Never (somente para .NET 4.5 e Tempo de Execução do Windows) não solicita ao usuário. Em vez disso, tenta usar o cookie armazenado na visualização oculta da Web incorporada.

  O uso desta opção pode falhar. Nesse caso, AcquireTokenInteractive lança uma exceção para notificá-lo de que você precisa de uma interação com a interface do usuário. Em seguida, use outro Prompt parâmetro.

• NoPrompt não envia nenhum prompt para o provedor de identidade. O provedor de identidade decide qual experiência de login é melhor para o usuário (logon único ou conta selecionada).

  Esta opção é obrigatória para editar políticas de perfil no Azure AD B2C. Para obter mais informações, consulte Detalhes do Azure AD B2C.

WithUseEmbeddedWebView

Esse método permite que você especifique se deseja forçar o uso de um WebView incorporado ou do sistema WebView (quando disponível). Para obter mais informações, consulte Uso de navegadores da Web.

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

ComExtraScopeToConsent

Esse modificador é para cenários avançados em que você deseja que o usuário consinta com vários recursos antecipadamente e não deseja usar o consentimento incremental. Os desenvolvedores normalmente usam consentimento incremental com MSAL.NET e a plataforma de identidade da Microsoft. Para obter mais informações, consulte Ter o consentimento do usuário antecipadamente para vários recursos.

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

ComCustomWebUi

Uma interface do usuário da Web é um mecanismo para invocar um navegador. Esse mecanismo pode ser um controle WebBrowser de interface do usuário dedicado ou uma maneira de delegar a abertura do navegador. O MSAL fornece implementações de interface do usuário da Web para a maioria das plataformas, mas talvez você queira hospedar o navegador por conta própria nestes casos:

• Você tem plataformas que a MSAL não cobre explicitamente, como Blazor, Unity e Mono em desktops.
• Você deseja testar seu aplicativo e usar um navegador automatizado que pode ser usado com o Selenium.
• O navegador e o aplicativo que executam o MSAL estão em processos separados.

Para conseguir isso, você dá ao MSAL start Url, que precisa ser exibido em um navegador para que os usuários possam inserir itens como seu nome de usuário. Após a conclusão da autenticação, seu aplicativo precisa passar de volta para o MSAL end Url, que contém um código fornecido pelo Microsoft Entra ID. O anfitrião de end Url é sempre redirectUri. Para intercetar end Url, siga um destes procedimentos:

• Monitorize os redirecionamentos de navegador até redirect Url ser atingido.
• Faça com que o navegador redirecione para um URL que você monitora.

WithCustomWebUi é um ponto de extensibilidade que você pode usar para fornecer sua própria interface do usuário em aplicativos cliente públicos. Você também pode permitir que os /Authorize usuários passem pelo ponto de extremidade do provedor de identidade e permitir que eles entrem e consintam. MSAL.NET pode resgatar o código de autenticação e obter um token.

Por exemplo, você pode usar WithCustomWebUi no Visual Studio para fazer com que os aplicativos Electron (por exemplo, Visual Studio Feedback) forneçam a interação da Web, mas deixe que MSAL.NET faça a maior parte do trabalho. Você também pode usar WithCustomWebUi se quiser fornecer automação da interface do usuário.

Em aplicativos cliente públicos, MSAL.NET usa o padrão PKCE (Proof Key for Code Exchange) para garantir que a segurança seja respeitada. Somente MSAL.NET pode resgatar o código. Para obter mais informações, consulte RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients.

using Microsoft.Identity.Client.Extensions;

Usar WithCustomWebUI

Para utilizar WithCustomWebUIo , siga estes passos:

1. Implemente a interface ICustomWebUi. Para obter mais informações, consulte esta página do GitHub.

2. Implemente um AcquireAuthorizationCodeAsyncmétodo e aceite a URL do código de autorização que MSAL.NET calcula.

3. Permita que o usuário passe pela interação com o provedor de identidade e retorne a URL que o provedor de identidade usou para chamar de volta sua implementação, juntamente com o código de autorização. Se você tiver problemas, sua implementação deve lançar uma MsalExtensionException exceção para cooperar com a MSAL.

4. Na chamada AcquireTokenInteractive , use o .WithCustomUI() modificador passando a instância da interface do usuário da Web personalizada:

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

A equipe MSAL.NET reescreveu os testes da interface do usuário para usar esse mecanismo de extensibilidade. Se você estiver interessado, exiba a classe SeleniumWebUI no código-fonte MSAL.NET.

Proporcione uma ótima experiência com SystemWebViewOptions

A partir de MSAL.NET 4.1 SystemWebViewOptions, você pode especificar:

• O URI para ir para (BrowserRedirectError) ou o fragmento HTML para exibir (HtmlMessageError) se erros de login ou consentimento aparecerem no navegador da Web do sistema.
• O URI para ir para (BrowserRedirectSuccess) ou o fragmento HTML para exibir (HtmlMessageSuccess) se o login ou consentimento for bem-sucedido.
• A ação a ser executada para iniciar o navegador do sistema. Você pode fornecer sua própria implementação definindo o OpenBrowserAsync delegado. A classe também fornece uma implementação padrão para dois navegadores: OpenWithEdgeBrowserAsync para o Microsoft Edge e OpenWithChromeEdgeBrowserAsync para o Microsoft Edge no Chromium.

Para usar essa estrutura, escreva algo como o exemplo a seguir:

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

Outros parâmetros opcionais

Para saber mais sobre os outros parâmetros opcionais do AcquireTokenInteractive, consulte 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

Código em MSAL para 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

No MSAL Node, você adquire tokens por meio do fluxo de código de autorização com PKCE (Proof Key for Code Exchange). O processo tem duas etapas:

1. O aplicativo obtém uma URL que pode ser usada para gerar um código de autorização. Os usuários podem abrir a URL em um navegador e inserir suas credenciais. Em seguida, eles são redirecionados de volta para redirectUri (registrados durante o registro do aplicativo) com um código de autorização.
2. O aplicativo passa o código de autorização recebido para o acquireTokenByCode() método, que o troca por um token de acesso.

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+ fornece um método interativo para adquirir um 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"])

Próximos passos

Passe para o próximo artigo neste cenário, Chamar uma API da Web a partir do aplicativo da área de trabalho.