Identity
April 21, 2021 · View on GitHub
Table of Contents
- Introduction
- Authentication Endpoints
- Understanding the authentication flow
- Further restricting access to authorized users
- Understanding the code
- Calling the Microsoft.Graph
- Terminology
- Additional resources
Introduction
The Identity features add user authentication to your app and enable you to restrict your app (Forced Login) or provide restricted content (Optional Login) to authenticated users.
Both Forced Login and Optional Login use the Microsoft.Identity.Client (MSAL) NuGet package to authenticate the user using Azure Active Directory.
Once the user has been authenticated, the app will call the Microsoft Graph to retrieve user information. This info is displayed on the Navigation View (for project types Navigation Pane and Horizontal Navigation Pane), and also on the SettingsPage that also allows the user to log out.
Authentication Endpoints
You can choose between different ways to initialize the IdentityService, restricting hereby the allowed account types.
- InitializeWithAadAndPersonalMsAccounts() (Default) - allows Azure Active Directory Accounts and Personal Microsoft Accounts
- InitializeWithPersonalMsAccounts() - allows Personal Microsoft Accounts
- InitializeWithAadMultipleOrgs() - allows Azure Active Directory Accounts from any organization
- InitializeWithAadSingleOrg() - allows Azure Active Directory Accounts from the specified organization
The method you choose needs to allow the same account types as the ClientID you configure in Azure.
By choosing options 3 or 4 you can enable Windows Integrated Auth for domain joined machines. For more info regarding intergrated auth see Integrated Windows Authentication.
Understanding the authentication flow
The authentication process is initialized on app activation in the ActivationService (App.xaml.cs in Prism). First of all the IdentityService tries to get an AccessToken silently from the cache. This AccessToken is then passed to the Microsoft Graph to get user information.
If silently requesting the token from the cache fails, the interactive authentication process is triggered:
Forced Login
Apps with the Forced Login feature will be redirected to a LoginPage that can be used as a landing page and restricts the access to the rest of the pages.
Optional Login
Apps with Optional Login feature will show a LogIn button on the NavigationView (if available) and in the SettingsPage. While the user is not logged in only unrestricted pages are shown.
The following graphics explain the silent and interactive login process:
Silent LogIn
Interactive LogIn
Further restricting access to authorized users
If you want to further restrict app access, the IdentityService provides a method called IsAuthorized() where you can include further authorization checks (i.e. check permissions in a database).
In Forced Login apps unauthorized users cannot log into the app, in Optional Login apps unauthorized users can login but will not see restricted pages.
Understanding the code
IdentityService (Core project)
This class is responsible for obtaining the AccessToken from the cache or via Windows Integrated or Interactive Auth. The class uses the MSAL NuGet library to connect with Azure Active Directory. The Identity service is uses a ClientID configured in the App.config. If you haven't done already create a ClientID following the steps on https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app and update the App.config IdentityClientId.
MicrosoftGraphService (Core project)
This class calls the Microsoft Graph to obtain the user information and the user photo. It can be extended adding methods that get info from other Microsoft Graph services.
UserDataService
This class consumes the MicrosoftGraphService and is responsible for storing the user information in the cache.
Forced Login code
Forced login adds a LoginPage with a button that allows the user to interactively login calling the IdentityService. When the user is logged in, the apps navigates to the ShellPage that gives access to the rest of the pages. When the user logs out, the LoginPage is shown again.
If the app is activated from activations other than LaunchActivation (for example DeepLinking or ToastNotification) the activation flow is intercepted by the IdentityService to ensure the user is logged in before redirecting to the requested page.
Optional Login code
Optional login allows the user to log in from the SettingsPage and the NavigationView (if available).
To restrict the access to a page and make it invisible and inaccessible for un-authenticated and un-authorized users you have to add the "Restricted" attribute to the page and limit its visibility on the ShellPage as shown below. (The MainPage and the SettingsPage should not be restricted):
1. Add the Restricted Attribute to the Views CodeBehind code
PageName.xaml.cs
namespace YourAppNamespace.Views
{
[Restricted]
public sealed partial class PageName : Page
{
public PageName()
{
}
}
}
2. Bind the NavViewItems Visibility to the IsAuthorized property
ShellPage.xaml
<!--
Find MenuItems definition in page xaml code
-->
<winui:NavigationView.MenuItems>
<!--
Add Visibility to hide restricted pages.
-->
<winui:NavigationViewItem
x:Uid="Shell_PageName"
Icon="Document"
helpers:NavHelper.NavigateTo="views:PageName"
Visibility="{x:Bind ViewModel.IsAuthorized, Mode=OneWay}" />
</winui:NavigationView.MenuItems>
Calling the Microsoft.Graph
The MicrosoftGraphService class in the core project allows you to retrieve information of the user from the Microsoft Graph, calling the following endpoint using a HttpClient.
https://graph.microsoft.com/v1.0/
All calls need to add the AccessToken as an authentication header. If your app has a lot of interaction with the Graph, consider using the Microsoft Graph Client Library.
Terminology
In the context of authentication in general, there are a few concepts to keep in mind:
| Term | Definition |
|---|---|
| JWT |
|
| Access Token |
|
| Client ID |
|
| Client Secret |
|
| Integrated Auth |
|
| Kerberos |
|
| Auth Endpoint |
|
| Microsoft Graph |
|
| Azure AD (AAD) |
|
| Microsoft Account (MSA) |
|
| MSAL |
|
| Azure B2B |
|
| Azure B2C |
|
| OIDC |
|
| OAuth2 |
|
| OpenID |
|