WindowsProvider

The WindowsProvider is an authentication provider for accessing locally configured accounts on Windows. It extends IProvider and uses the native Windows AccountManager (WAM) APIs and AccountsSettingsPane for sign in.

Available in the CommunityToolkit.Authentication.Uwp package.

Important

Windows Community Toolkit - Graph Controls and Helpers packages are in preview. To get started using WCT preview packages visit the WCT Preview Packages wiki page.

Prerequisite Windows Store Association in Visual Studio

To get valid tokens and complete sign in, the app will need to be associated with the Microsoft Store. This will enable your app to authenticate consumer MSA accounts without any additional configuration.

  1. In Visual Studio Solution Explorer, right-click the UWP project, then select Store -> Associate App with the Store...

  2. In the wizard, click Next, sign in with your Windows developer account, type a name for your app in Reserve a new app name, then click Reserve.

  3. After completing the app registration, select the new app name, click Next, and then click Associate. This adds the required Windows Store registration information to the application manifest.

Note

You must have a Windows Developer account to use the WindowsProvider in your UWP app. You can register a Microsoft developer account if you don't already have one.

Syntax

The WindowsProvider can be used in just one line of code:

using CommunityToolkit.Authentication;

// Easily create a new WindowsProvider instance and set the GlobalProvider.
// Don't forget to associate your app with the Microsoft Store before attempting sign in.
ProviderManager.Instance.GlobalProvider = new WindowsProvider(new string[] { "User.Read", "Tasks.ReadWrite" });

The WindowsProvider can also be configured to disabled auto-signin or show custom content in the AccountsSettingsPane. Additional configuration for account types will be available via the WebAccountProviderConfig object in the future. Currently, only consumer MSA accounts are supported.

using CommunityToolkit.Authentication;

// Provider config
string[] scopes = { "User.Read", "People.Read", "Calendars.Read", "Mail.Read" };

// Additional parameters are also available,
// such as custom settings commands for the AccountsSettingsPane.
Guid settingsCommandId = Guid.NewGuid();
void OnSettingsCommandInvoked(IUICommand command)
{
    System.Diagnostics.Debug.WriteLine("AccountsSettingsPane command invoked: " + command.Id);
}

// Configure which types accounts should be available to choose from. The default is MSA, but AAD will come in the future.
// ClientId is only required for approving admin level consent in AAD tenants.
var webAccountProviderConfig = new WebAccountProviderConfig(WebAccountProviderType.MSA, "YOUR_CLIENT_ID_HERE");

// Configure details to present in the AccountsSettingsPane, such as custom header text and links.
var accountsSettingsPaneConfig = new AccountsSettingsPaneConfig(
    headerText: "Custom header text",
    commands: new List<SettingsCommand>()
    {
        new SettingsCommand(settingsCommandId: settingsCommandId, label: "Click me!", handler: OnSettingsCommandInvoked)
    });

// Determine it the provider should automatically sign in or not. Default is true.
// Set to false to delay silent sign in until SignInAsync or TrySilentSignInAsync is called.
bool autoSignIn = false;

// Set the GlobalProvider with the extra configuration
ProviderManager.Instance.GlobalProvider = new WindowsProvider(scopes, accountsSettingsPaneConfig, webAccountProviderConfig, autoSignIn);

Constructor

Parameter Type Default Description
scopes string[] null List of scopes to initially request.
webAccountProviderConfig WebAccountProviderConfig? null Configuration value for determining the available web account providers.
accountsSettingsPaneConfig AccountsSettingsPaneConfig? null Configuration values for the AccountsSettingsPane.
autoSignIn bool true Determines whether the provider attempts to silently log in upon instantiation.

Properties

Property Type Description
State ProviderState Gets the current authentication state of the provider.
Scopes string[] List of scopes to pre-authorize on the user during authentication.
WebAccountsProviderConfig WebAccountProviderConfig configuration values for determining the available web account providers.
AccountsSettingsPaneConfig AccountsSettingsPaneConfig Configuration values for the AccountsSettingsPane, shown during authentication.
RedirectUri string Static getter for retrieving a customized redirect uri to put in the Azure app registration.

Events

Event Type Description
StateChanged EventHandler<ProviderStateChangedEventArgs> Event called when the provider state changes.

Methods

Method Arguments Returns Description
AuthenticateRequestAsync HttpRequestMessage Task Authenticate an outgoing request.
GetTokenAsync bool silentOnly = true, string[] scopes = null Task<string> Retrieve a token for the authenticated user.
SignInAsync Task Sign in a user.
SignOutAsync Task Sign out the current user.
TrySilentSignInAsync Task<bool> Try signing in silently, without prompts.

AccountsSettingsPaneConfig Object

Property Type Description
HeaderText string Gets or sets the header text for the accounts settings pane.
Commands IList<SettingsCommand> Gets or sets the SettingsCommand collection for the account settings pane.

WebAccountProviderConfig Object

Property Type Description
ClientId string Client Id obtained from Azure registration.
WebAccountProviderType WebAccountProviderType The types of accounts providers that should be available to the user.

WebAccountProviderType Enum

Name Description
All Enable authentication of all available account types.
MSA Enable authentication of public/consumer MSA accounts.