Skip to content

Acquiring tokens interactively

Bogdan Gavril edited this page Jun 20, 2018 · 43 revisions

AcquireTokenAsync

In MSAL.NET, all the overrides of AcquireTokenAsync are interactive.

image

Parameters

The parameters are the following:

  • Scopes contains an enumeration of strings which define the scopes for which a token is required. If the token is for the Microsoft Graph, the required scopes can be found in api reference of each Microsoft graph API in the section named "Permissions". For instance, to list the user's contacts, the scope "User.Read", "Contacts.Read" will need to be used. See also Microsoft Graph permissions reference.
  • User (optional) of type IUser, provides a hint to the STS about the user for which to get the token. This can be set from the User member of a previous AuthenticationResult, or one of the elements of the Users property of the PublicClientApplication.
  • loginHint (optional) offers an alternative to user. It's used like userIdentifyer in ADAL. Needs to be passed the UPN (User Principal Name)
  • UIBehavior (optional) is the way to control, in MSAL.NET, the interaction between the user and the STS to enter credentials. It's different depending on the platform (See below)
  • extraQueryParameters (optional) is the same as for ADAL.NET (a string with the following format "key1=value1&key2=value2", enabling developers to pass extra parameters to the STS endpoint.
  • extraScopesToConsent (optional) enables application developers to specify additional scopes for which users will pre-consent. - This can be in order to avoid having them see incremental consent screens when the Web API require them. - This is also indispensable in the case where you want to provide scopes for several resources. See [the paragraph] (https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Acquiring-tokens-interactively#how-to-get-consent-for-several-resources) below for more details
  • parent (optional) enables, for some platform, to specify the parent UI (window in Windows, Activity in Android, .) which will be the parent of the dialog.

Controlling the interactivity with the user with the behavior parameter (UIBehavior)

Equivalent to the PromptBehavior in ADAL.NET, MSAL.NET defines the notion of UIBehavior. This is actually a structure with public static members.

image

The public members are:

  • Consent: enables the application developer to have the user be prompted for consent even if consent was granted before. This is done by sending prompt=consent to Azure AD
  • ForceLogin: enables the application developer to have the user prompted for credentials by the service even if this would not be needed. This can be useful if Acquiring a token fails, to let the user re-sign-in. This is done by sending prompt=login to Azure AD
  • Never (for .NET 4.5 and WinRT only) will not prompt the user, but instead will try to use the cookie stored in the hidden embedded web view (See below: Web Views in MSAL.NET). This might fail, and in that case AcquireTokenAsync will throw an exception to notify that a UI interaction is needed, and you will try again by calling an override of AcquireTokenAsync without a UIBehavior or with a different UIBehavior
  • SelectAccount: will force the STS to present the account for which the user has a session. This is useful when applications developers want to let user choose among different identities. This is done by sending prompt=select_account to Azure AD

Controlling the location of the dialog with the parent parameters (UIParent)

UIParent is used, in the platforms allowing it, to specify the parent window for the authentication dialog.

  • For .NET 4.5 and WinRT, it provides a constructor with an object: the OwerWindow parameter
  • For Android, it provides a constructor with the parent Activity.

More specificities depending on the platforms

Depending on the platforms, you will need to do a bit of extra work to use MSAL.NET. For more details on each platform, see:

How to get consent for several resources

The Azure AD V2 endpoint does not allow you to get a token for several resources at once. Therefore the scopes parameter should only contain scopes for a single resource. However, you can ensure that the user pre-consents to several resources by using the extraScopesToConsent parameter.

For instance if you have two resources, which have 2 scopes each:

  • https://myb2c.onmicrosoft.com/customerapi (with 2 scopes customer.read and customer.write)
  • https://myb2c.onmicrosoft.com/vendorapi (with 2 scopes vendor.read and vendor.write)

you should use an override of AcquireTokenAsync which has the extraScopesToConsent parameter.

For instance:

string[] scopesForCustomerApi = new string[]
{
  "https://myb2c.onmicrosoft.com/customerapi/customer.read",
  "https://myb2c.onmicrosoft.com/customerapi/customer.write"
};
string[] scopesForVendorApi = new string[] 
{
 "https://myb2c.onmicrosoft.com/vendorapi/vendor.read", 
 "https://myb2c.onmicrosoft.com/vendorapi/vendor.write" 
};

var result = await app.AcquireTokenAsync(scopesForCustomerApi, 
                                         app.Users.FirstOrDefault(), 
                                         uiBehavior, 
                                         string.Empty, 
                                         scopesForVendorApi); 

This will get you an access token for the first Web API. Then when you need to call the second one, you can call

AcquireTokenSilentAsync(scopesForVendorApi);

See this GitHub issue for more context.

Samples illustrating acquiring tokens interactively with MSAL.NET

Sample Platform Description
active-directory-dotnet-desktop-msgraph-v2 Desktop (WPF) Windows Desktop .NET (WPF) application calling the Microsoft Graph API.
active-directory-dotnet-native-uwp-v2 UWP A Windows Universal Platform client application using msal.net, accessing the Microsoft Graph for a user authenticating with Azure AD V2 endpoint.
https://github.com/Azure-Samples/active-directory-xamarin-native-v2 Xamarin iOS, Android, UWP A simple Xamarin Forms app showcasing how to use MSAL to authenticate MSA and Azure AD via the AADD V2 endpoint, and access the Microsoft Graph with the resulting token.
https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2 WPF, ASP.NET Core 2.0 Web API A WPF application calling an ASP.NET Core Web API using Azure AD V2.

Getting started with MSAL.NET

Acquiring tokens

Desktop/Mobile apps

Web Apps / Web APIs / daemon apps

Advanced topics

News

FAQ

Other resources

Clone this wiki locally