diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 1c9ff15db..faa94609b 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -47,6 +47,18 @@ { "source_path": "dotnet/api/overview/msal-public-client/index.md", "redirect_url": "/dotnet/api/overview/core-msal-net-libraries/" + }, + { + "source_path": "msal-dotnet-articles/resources/ios12-security-advisory.md", + "redirect_url": "/entra/msal/dotnet/" + }, + { + "source_path": "msal-dotnet-articles/acquiring-tokens/desktop-mobile/uwp.md", + "redirect_url": "/entra/msal/dotnet/" + }, + { + "source_path": "msal-dotnet-articles/acquiring-tokens/desktop-mobile/xamarin.md", + "redirect_url": "/entra/msal/dotnet/acquiring-tokens/desktop-mobile/mobile-applications" } ] } diff --git a/msal-dotnet-articles/TOC.yml b/msal-dotnet-articles/TOC.yml index d6cf56581..056fc0ddf 100644 --- a/msal-dotnet-articles/TOC.yml +++ b/msal-dotnet-articles/TOC.yml @@ -28,9 +28,7 @@ - name: Using MSAL.NET with Web Account Manager (WAM) href: acquiring-tokens/desktop-mobile/wam.md - name: Xamarin - href: acquiring-tokens/desktop-mobile/xamarin.md - - name: Universal Windows Platform - href: acquiring-tokens/desktop-mobile/uwp.md + href: acquiring-tokens/desktop-mobile/mobile-applications.md - name: Sign-in users with social identities href: acquiring-tokens/desktop-mobile/social-identities.md - name: Integrated Windows Authentication for domain or Microsoft Entra joined machines @@ -185,8 +183,6 @@ href: resources/telemetry-overview.md - name: Handling of personally identifiable information href: resources/handling-pii.md - - name: iOS12 security advisory - href: resources/ios12-security-advisory.md - name: Releases href: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases - name: MSAL.NET reference documentation diff --git a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/acquiring-tokens-interactively.md b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/acquiring-tokens-interactively.md index a422a7d9b..18f8f1978 100644 --- a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/acquiring-tokens-interactively.md +++ b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/acquiring-tokens-interactively.md @@ -196,13 +196,10 @@ Depending on the platform, additional configuration might be required for intera - [Configuration requirements and troubleshooting tips for Xamarin Android with MSAL.NET](/entra/identity-platform/msal-net-xamarin-android-considerations) - [Considerations for using Xamarin iOS with MSAL.NET](/entra/identity-platform/msal-net-xamarin-ios-considerations) -- [Using MSAL.NET with UWP applications](./uwp.md) ## Samples | Sample | Platform | Description | |------ | -------- | ----------- | | [active-directory-dotnet-desktop-msgraph-v2](https://github.com/azure-samples/active-directory-dotnet-desktop-msgraph-v2) | Desktop (WPF) | Windows Desktop .NET (WPF) application calling the Microsoft Graph API. ![WPF app topology](../../media/wpf-app-topology.png) | -| [active-directory-dotnet-native-uwp-v2](https://github.com/azure-samples/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.0 endpoint. ![UWP app topology](../../media/uwp-app-topology.png) | -| [https://github.com/Azure-Samples/active-directory-xamarin-native-v2](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 Microsoft accounts and Microsoft Entra ID via the Microsoft identity platform endpoint, and access the Microsoft Graph with the resulting token. ![Xamarin Forms app topology](../../media/xamarin-forms-topology.png) | | [https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2](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.0. ![Desktop and web app interaction topology](../../media/desktop-web-topology.png) | diff --git a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/integrated-windows-authentication.md b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/integrated-windows-authentication.md index 846d817c8..be549b245 100644 --- a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/integrated-windows-authentication.md +++ b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/integrated-windows-authentication.md @@ -14,7 +14,7 @@ If your desktop or mobile application runs on Windows and on a machine connected - **Federated** users only, i.e. those created in an Active Directory and backed by Microsoft Entra ID. Users created directly in Microsoft Entra ID, without AD backing - **managed** users - cannot use this auth flow. This limitation does not affect the Username/Password flow. - Does not work for MSA users. For MSA uses try out [WAM](./wam.md) -- IWA is for apps written for .NET Framework, .NET Core and UWP platforms +- IWA is for applications written for .NET and .NET Framework. - IWA does NOT bypass MFA (multi factor authentication). If MFA is configured, IWA might fail if an MFA challenge is required, because MFA requires user interaction. > This one is tricky. IWA is non-interactive, but 2FA requires user interactivity. You do not control when the identity provider requests 2FA to be performed, the tenant admin does. From our observations, 2FA is required when you login from a different country, when not connected via VPN to a corporate network, and sometimes even when connected via VPN. Don’t expect a deterministic set of rules, Microsoft Entra ID uses AI to continuously learn if 2FA is required. You should fallback to a [user prompt](./acquiring-tokens-interactively.md) if IWA fails @@ -120,10 +120,7 @@ static async Task GetATokenForGraph() // Explanation: the library was unable to query the current Windows logged-in user or this user is not AD or Azure AD // joined (work-place joined users are not supported). - // Mitigation 1: on UWP, check that the application has the following capabilities: Enterprise Authentication, - // Private Networks (Client and Server), User Account Information - - // Mitigation 2: Implement your own logic to fetch the username (e.g. john@contoso.com) and use the + // Mitigation: Implement your own logic to fetch the username (e.g. john@contoso.com) and use the // AcquireTokenByIntegratedWindowsAuth form that takes in the username // Error Code: integrated_windows_auth_not_supported_managed_user diff --git a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/xamarin.md b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/mobile-applications.md similarity index 63% rename from msal-dotnet-articles/acquiring-tokens/desktop-mobile/xamarin.md rename to msal-dotnet-articles/acquiring-tokens/desktop-mobile/mobile-applications.md index a2d71f0e3..4afb2989c 100644 --- a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/xamarin.md +++ b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/mobile-applications.md @@ -1,9 +1,9 @@ --- -title: Using MSAL.NET With MAUI and Xamarin +title: Using MSAL.NET With .NET MAUI description: "How to use MSAL.NET on mobile platforms." --- -# Using MSAL.NET With MAUI and Xamarin +# Using MSAL.NET With MAUI MSAL.NET can run on mobile devices (both iOS and Android) through applications built with [.NET Multi-platform App UI (MAUI)](https://dotnet.microsoft.com/apps/maui). @@ -14,19 +14,19 @@ MSAL.NET can run on mobile devices (both iOS and Android) through applications b MSAL.NET can be used with authentication brokers on mobile devices, such as Microsoft Authenticator or the Company Portal. To learn more about how to configure applications to use brokers on iOS and Android, refer to [Use Microsoft Authenticator or Intune Company Portal on Xamarin applications](/azure/active-directory/develop/msal-net-use-brokers-with-xamarin-apps). -## MAUI and Xamarin Android +## MAUI on Android To get started with MSAL.NET integration on Android, refer to the following resources: -- [How to migrate Xamarin ADAL apps to MSAL for Android](/azure/active-directory/develop/msal-net-migration-android-broker) -- [Xamarin Android Configuration Tips + Troubleshooting](/azure/active-directory/develop/msal-net-xamarin-android-considerations) -- [Xamarin Android System Browser Info](/azure/active-directory/develop/msal-net-system-browser-android-considerations) +- [How to migrate Xamarin ADAL apps to MSAL for Android](/entra/identity-platform/msal-net-migration-android-broker) +- [Xamarin Android Configuration Tips + Troubleshooting](/entra/identity-platform/msal-net-xamarin-android-considerations) +- [Xamarin Android System Browser Info](/entra/identity-platform/msal-net-system-browser-android-considerations) To learn more about testing MSAL on Android devices, refer to the [MSAL for Android Wiki](https://github.com/AzureAD/microsoft-authentication-library-for-android/wiki/Android-Emulator-with-MSAL). -## MAUI and Xamarin iOS +## MAUI on iOS To get started with MSAL.NET integration on iOS, refer to the following resources: -- [How to migrate Xamarin ADAL apps to MSAL for iOS](/azure/active-directory/develop/msal-net-migration-ios-broker) -- [Xamarin iOS Configuration Tips + Troubleshooting](/azure/active-directory/develop/msal-net-xamarin-ios-considerations) \ No newline at end of file +- [How to migrate Xamarin ADAL apps to MSAL for iOS](/entra/identity-platform/msal-net-migration-ios-broker) +- [Xamarin iOS Configuration Tips + Troubleshooting](/entra/identity-platform/msal-net-xamarin-ios-considerations) \ No newline at end of file diff --git a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/social-identities.md b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/social-identities.md index c7fb92fcf..85d234e9e 100644 --- a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/social-identities.md +++ b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/social-identities.md @@ -220,9 +220,3 @@ One option is to use the "name" claim as the preferred username. The process is ## Customizing the UI [Customize the user interface with Azure AD B2C](/azure/active-directory-b2c/customize-ui-overview). - -## Samples illustrating acquiring tokens interactively with MSAL.NET for B2C applications - -Sample | Platform | Description ------- | -------- | ----------- -[active-directory-b2c-xamarin-native](https://github.com/Azure-Samples/active-directory-b2c-xamarin-native) | Xamarin iOS, Xamarin Android, UWP | A simple Xamarin Forms app showcasing how to use MSAL.NET to authenticate users via Azure Active Directory B2C, and access a Web API with the resulting tokens. diff --git a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/username-password-authentication.md b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/username-password-authentication.md index 733edb043..c3102ebbc 100644 --- a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/username-password-authentication.md +++ b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/username-password-authentication.md @@ -23,7 +23,7 @@ In addition to the [Integrated Windows Authentication constraints](integrated-wi - Available starting with MSAL 2.1.0. - Not compatible with conditional access and multi-factor authentication. As a consequence, if the app runs in a Microsoft Entra tenant where the tenant admin requires multi-factor authentication, the flow cannot be used. - Only available for work and school accounts and **not** personal Microsoft accounts. -- Available on .NET Framework and .NET/.NET Core, but not for Universal Windows Platform (UWP) applications. +- Available on .NET Framework and .NET/.NET Core. ### Authority implications diff --git a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/uwp.md b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/uwp.md deleted file mode 100644 index ce004b170..000000000 --- a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/uwp.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Using MSAL.NET with UWP applications -description: Learn how to build MSAL.NET applications on the Universal Windows Platform." -services: active-directory -author: Dickson-Mwendia -manager: CelesteDG - -ms.service: msal -ms.subservice: msal-dotnet -ms.topic: conceptual -ms.workload: identity -ms.date: 08/24/2023 -ms.author: dmwendia -ms.reviewer: ddelimarsky -ms.custom: devx-track-csharp, aaddev, devx-track-dotnet -#Customer intent: As an application developer, I want to learn about considerations for using Universal Windows Platform and MSAL.NET so that I can decide if this platform meets my application development needs. ---- - -# Using MSAL.NET with UWP applications - -> [!NOTE] -> MSAL.NET versions 4.61.0 and above do not provide support for UWP. - -Developers of applications that use Universal Windows Platform (UWP) with MSAL.NET should consider the concepts this article presents. - ->[!NOTE] ->Please see [Using MSAL.NET with Web Account Manager (WAM)](./wam.md) for how to configure your UWP app to handle authentication through the Windows Broker. - -## Legacy scenarios that do not use the broker / WAM - -### UseCorporateNetwork - -In the context of UWP applications, has [`WithUseCorporateNetwork`](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/c9bdd0dd191ab2e658a1c949e43e3959fe3d1aa5/src/client/Microsoft.Identity.Client/AppConfig/PublicClientApplicationBuilder.cs#L244). This is a function that accepts a boolean value determining whether the application should use [Integrated Windows Authentication](./integrated-windows-authentication.md) (and therefore SSO with the user signed-in with the operating system) if this user is signed-in with an account in a federated Microsoft Entra tenant. - -**Important:** -Setting this property to true assumes that the application developer has enabled Integrated Windows Authentication (IWA) in the application. For this: - -- In the ``Package.appxmanifest`` for your UWP application, in the Capabilities tab, enable the following capabilities: - - Enterprise Authentication - - Private Networks (Client & Server) - - Shared User Certificate - -IWA is not enabled by default because applications requesting the Enterprise Authentication or Shared User Certificates capabilities require a higher level of verification to be accepted into the Windows Store, and not all developers may wish to perform the higher level of verification. - ->[!NOTE] ->The underlying implementation on the UWP platform (WAB) does not work correctly in Enterprise scenarios where Conditional Access was enabled. The symptom is that the user tries to sign-in with Windows hello, and is proposed to choose a certificate, but the certificate for the pin is not found, or the user chooses it, but never get prompted for the Pin. A workaround is to use an alternative method (username/password + phone authentication), but the experience is not good. In the future MSAL will leverage WAM, which will solve the problem. - -### Troubleshooting - -Some customers have reported that in specific enterprise environments there was the following sign-in error: - -```text -We can't connect to the service you need right now. Check your network connection or try this again later -``` - -Whereas they know they have an internet connection and the code works with a public network. - -A workaround is to make sure that WAB (the underlying Windows component) allows private network access. You can do that by setting a registry key: - -```text -HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001 -``` - -For details see [Web authentication broker debugging with Fiddler](/windows/uwp/security/web-authentication-broker#fiddler). - -## Sample illustrating UWP specific properties - -More details are provided in the following samples: - -Sample | Platform | Description ------- | -------- | ----------- -[active-directory-dotnet-native-uwp-v2](https://github.com/azure-samples/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.0 endpoint. ![UWP app topology](../../media/uwp-app-topology.png) -[https://github.com/Azure-Samples/active-directory-xamarin-native-v2](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 Microsoft accounts and Microsoft Entra ID via the Microsoft identity platform endpoint, and access the Microsoft Graph with the resulting token. ![Xamarin Forms topology](../../media/xamarin-forms-topology.png) diff --git a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/wam.md b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/wam.md index 31db94a27..e4bba5cae 100644 --- a/msal-dotnet-articles/acquiring-tokens/desktop-mobile/wam.md +++ b/msal-dotnet-articles/acquiring-tokens/desktop-mobile/wam.md @@ -33,12 +33,12 @@ WAM support is split across two packages: >[!NOTE] >For migration purposes, and if you have a .NET 6, .NET Core, or a .NET Standard application that needs to use _both_ WAM and the [embedded browser](/azure/active-directory/develop/msal-net-web-browsers#embedded-vs-system-web-ui), you will also need to use the [Microsoft.Identity.Client.Desktop](https://www.nuget.org/packages/Microsoft.Identity.Client.Desktop/) package. Once added, developers can use [`WithWindowsDesktopFeatures`](xref:Microsoft.Identity.Client.Desktop.DesktopExtensions.WithWindowsDesktopFeatures*) when setting up their public client application. > ->If your application targets UWP or `net-windows` (version-dependent Target Framework Moniker for Windows), WAM is included in the MSAL.NET package (applicable to versions 4.60.3 and below). +>If your application targets `net-windows` (version-dependent Target Framework Moniker for Windows), WAM is included in the MSAL.NET package. After referencing the relevant packages, call [`WithBroker(BrokerOptions)`](xref:Microsoft.Identity.Client.Desktop.WamExtension.WithBroker*) with broker configuration options and [a window handle](#parent-window-handles) that the broker will be bound to. >[!NOTE] ->Most apps need to reference the [`Microsoft.Identity.Client.Broker`](https://www.nuget.org/packages/Microsoft.Identity.Client.Broker/) package to use this integration. .NET MAUI and UWP applications don't need to add the dependency because the functionality is embedded into MSAL. +>Most apps need to reference the [`Microsoft.Identity.Client.Broker`](https://www.nuget.org/packages/Microsoft.Identity.Client.Broker/) package to use this integration. .NET MAUI applications don't need to add the dependency because the functionality is embedded into MSAL. ```csharp var scopes = new[] { "User.Read" }; @@ -158,8 +158,6 @@ This flow, also known as Resource Owner Password Credentials (ROPC), is not reco - Azure B2C and Active Directory Federation Services (ADFS) authorities aren't supported. MSAL will fall back to using a browser for user authentication. - On Mac, Linux, and versions of Windows earlier than 10 or Windows Server 2019, MSAL will fall back to a browser. -- Updated WAM broker is not available on UWP due to Windows API limitations. UWP apps will use the legacy WAM implementation. -- At this time, WAM uses EdgeHTML as the browser engine for authentication flows. Organizations and identity providers need to ensure that EdgeHTML is an allowed browser engine on customer devices for WAM-based applications to work. ## Package availability diff --git a/msal-dotnet-articles/acquiring-tokens/overview.md b/msal-dotnet-articles/acquiring-tokens/overview.md index ba4185f1d..92f07d311 100644 --- a/msal-dotnet-articles/acquiring-tokens/overview.md +++ b/msal-dotnet-articles/acquiring-tokens/overview.md @@ -25,7 +25,7 @@ As explained in [Scenarios](../getting-started/scenarios.md), there are many way For both public and confidential client applications, MSAL.NET supports adding a token cache that preserves authentication and refresh tokens, as well as proactively refreshes those on an as-needed basis. For details, see [Token cache serialization in MSAL.NET](../how-to/token-cache-serialization.md). -In the case of Universal Windows Platform (UWP) applications, Xamarin for iOS, and Xamarin for Android, token cache serialization to an isolated storage is automatically provided by MSAL.NET and developers do not need to add any custom caching logic. For .NET desktop applications (.NET, .NET Framework, and .NET Core) the application needs to handle the token cache serialization and storage directly; however, helper classes are available to help simplify the process. +For .NET desktop applications (.NET, .NET Framework, and .NET Core) the application needs to handle the token cache serialization and storage directly; however, helper classes are available to help simplify the process. ## Token acquisition methods @@ -42,8 +42,8 @@ The following table summarizes the available approaches to acquire tokens in pub | Operating system | Platform | App type | [Interactive](./desktop-mobile/acquiring-tokens-interactively.md) | [IWA](./desktop-mobile/integrated-windows-authentication.md) | [Device Code](./desktop-mobile/device-code-flow.md) | |:----------------------|:----------------|:---------|:------------------------------------------------------------------|:-------------------------------------------------------------|:----------------------------------------------------| | Windows (desktop) | .NET | Desktop (WPF, Windows Forms, Console) | ✅ | ✅ | ✅ | -| Android | Xamarin Android | Mobile | ✅ | ❌ | ❌ | -| iOS | Xamarin iOS | Mobile | ✅ | ❌ | ✅ | +| Android | .NET MAUI | Mobile | ✅ | ❌ | ❌ | +| iOS | .NET MAUI | Mobile | ✅ | ❌ | ✅ | | macOS, Linux, Windows | .NET Core | Console | N/A see [Using web browsers](../acquiring-tokens/using-web-browsers.md) | ✅ | ✅ | ### Confidential client applications diff --git a/msal-dotnet-articles/acquiring-tokens/using-web-browsers.md b/msal-dotnet-articles/acquiring-tokens/using-web-browsers.md index 27eecb910..1ee6bc11d 100644 --- a/msal-dotnet-articles/acquiring-tokens/using-web-browsers.md +++ b/msal-dotnet-articles/acquiring-tokens/using-web-browsers.md @@ -35,7 +35,7 @@ It's important to understand that when acquiring a token interactively, the cont ### Embedded web view vs system browser -MSAL.NET is a multi-framework library and has framework-specific code to host a browser in a UI control (for example, on .NET either WinForms or WebView2; on Xamarin, native mobile controls, etc.). This control is called an *embedded* web view. Alternatively, MSAL.NET is also able to open a system web browser. +MSAL.NET is a multi-framework library and has framework-specific code to host a browser in a UI control (for example, on .NET either WinForms or WebView2; on .NET MAUI, native mobile controls, etc.). This control is called an *embedded* web view. Alternatively, MSAL.NET is also able to open a system web browser. Generally, it's recommended that you use the platform default, and this is typically the system browser. The system browser is better at remembering the users that have logged in before. To change this behavior, use @@ -50,9 +50,6 @@ Generally, it's recommended that you use the platform default, and this is typic | .NET 4.6.2+ | ✅ Yes | ✅ Yes | Embedded | | .NET Standard | ⛔ No††† | ✅ Yes | System | | .NET Core | ⛔ No††† | ✅ Yes | System | -| UWP†††† | ✅ Yes | ⛔ No | Embedded | -| Xamarin.Android†††† | ✅ Yes | ✅ Yes | System | -| Xamarin.iOS†††† | ✅ Yes | ✅ Yes | System | **†** System browser requires `http://localhost` redirect URI. @@ -60,8 +57,6 @@ Generally, it's recommended that you use the platform default, and this is typic **†††** Reference [Microsoft.Identity.Client.Desktop](https://www.nuget.org/packages/Microsoft.Identity.Client.Desktop) and call to use the embedded browser. -**††††** MSAL.NET versions 4.61.0 and above do not provide support for UWP, Xamarin Android, and Xamarin iOS. - ## System web browser Using the system browser has the significant advantage of sharing the Single Sign-On (SSO) state with web applications and other applications without needing a broker (WAM, Company Portal, Authenticator, etc.). @@ -100,8 +95,6 @@ When you configure `http://localhost`, MSAL.NET will find a random open port and Azure B2C and ADFS 2019 do not yet implement the *any port* option. So, you cannot set `http://localhost` (no port) redirect URI, but only `http://localhost:1234` (with port) URI. This means that you will have to do your own port management, for example, you can reserve a few ports and configure them as redirect URIs. Then your app can cycle through them until a port is free - this can then be used by MSAL. -UWP doesn't support listening to a port and thus doesn't support system browsers. - For more details, see [Localhost exceptions](/azure/active-directory/develop/reply-url#localhost-exceptions). ### Linux and macOS @@ -138,12 +131,12 @@ var options = new SystemWebViewOptions() } ``` -## Web views on Xamarin.Android and Xamarin.iOS +## Web views in mobile applications > [!NOTE] > MSAL.NET versions 4.61.0 and above do not provide support for Xamarin Android and Xamarin iOS. -Embedded web views can be enabled in Xamarin.Android and Xamarin.iOS apps. As a developer using MSAL.NET targeting Xamarin, you may choose to use either embedded web views or system browsers. This is your choice depending on the user experience and security concerns you want to target. +Embedded web views can be enabled in .NET MAUI applications. You may choose to use either embedded web views or system browsers. This is your choice depending on the user experience and security concerns you want to target. ### Differences between embedded web view and system browser @@ -181,7 +174,7 @@ var result = app.AcquireTokenInteractive(scopes) .ExecuteAsync(); ``` -#### Choosing between embedded web view or system browser on Xamarin.iOS +#### Choosing between embedded web view or system browser on iOS In your iOS app, in `AppDelegate.cs` you can initialize the `ParentWindow` to `null`. It's not used in iOS. @@ -189,7 +182,7 @@ In your iOS app, in `AppDelegate.cs` you can initialize the `ParentWindow` to `n App.ParentWindow = null; // no UI parent on iOS ``` -#### Choosing between embedded web view or system browser on Xamarin.Android +#### Choosing between embedded web view or system browser on Android In your Android app, in `MainActivity.cs` you can set the parent activity so that the authentication result gets back to it: @@ -206,7 +199,7 @@ var result = await App.PCA.AcquireTokenInteractive(App.Scopes) .ExecuteAsync(); ``` -#### Detecting the presence of custom tabs on Xamarin.Android +#### Detecting the presence of custom tabs on Android If you want to use the system web browser to enable Single-Sign On with the apps running in the browser, but are worried about the user experience for Android devices not having a browser with custom tab support, you have the option to decide by calling the . This method returns `true` if the Android package manager detects custom tabs and `false` if they aren't detected on the device. diff --git a/msal-dotnet-articles/acquiring-tokens/web-apps-apis/client-credential-flows.md b/msal-dotnet-articles/acquiring-tokens/web-apps-apis/client-credential-flows.md index 02ef55514..a85118a26 100644 --- a/msal-dotnet-articles/acquiring-tokens/web-apps-apis/client-credential-flows.md +++ b/msal-dotnet-articles/acquiring-tokens/web-apps-apis/client-credential-flows.md @@ -7,7 +7,7 @@ description: "Client credential authentication flows allow services, APIs, and d ## Supported platforms -While MSAL.NET is a multi-framework library, Confidential Client flows are not available on mobile and client-facing platforms (e.g., UWP, Xamarin.iOS, and Xamarin.Android) since there is no secure way of deploying a secret with an application. +While MSAL.NET is a multi-framework library, Confidential Client flows are not available on mobile and client-facing platforms since there is no secure way of deploying a secret with an application. ## Supported client credentials diff --git a/msal-dotnet-articles/advanced/exceptions/device-authentication-errors.md b/msal-dotnet-articles/advanced/exceptions/device-authentication-errors.md index cdc74edce..5b7420579 100644 --- a/msal-dotnet-articles/advanced/exceptions/device-authentication-errors.md +++ b/msal-dotnet-articles/advanced/exceptions/device-authentication-errors.md @@ -17,8 +17,8 @@ This is a conditional access policy applied by the tenant admin. For details see ## How to fix this? -To satisfy this requirement you will have to leverage WAM on Windows or the system browser (Edge on Chromium). On mobile platform, you'll need to enable the brokers (Microsoft Authenticator and Company portal) +To satisfy this requirement you will have to leverage WAM on Windows or the system browser. On mobile platforms, you'll need to enable the brokers (Microsoft Authenticator and Company portal) - If you are writing a desktop application running on Windows, see [WAM integration for Desktop applications](../../acquiring-tokens/desktop-mobile/wam.md). -- [On iOS and Android](../../acquiring-tokens/desktop-mobile/xamarin.md), we recommend [enabling the authentication broker](/azure/active-directory/develop/msal-net-use-brokers-with-xamarin-apps) +- [On iOS and Android](../../acquiring-tokens/desktop-mobile/mobile-applications.md), we recommend [enabling the authentication broker](/azure/active-directory/develop/msal-net-use-brokers-with-xamarin-apps) - The same principles apply to Web Applications, though given you are in a browser you must leverage a browser which can "talk to" WAM (that is either Edge on Chromium or Chrome with the Microsoft Entra extensions). For details see [Conditional access conditions](/azure/active-directory/conditional-access/concept-conditional-access-conditions#chrome-support). diff --git a/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md b/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md index 349b084d8..86bd915f1 100644 --- a/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md +++ b/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md @@ -48,7 +48,7 @@ Here are the common exceptions that might be thrown and some possible mitigation | [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS50079: The user is required to use [multi-factor authentication (MFA)](/azure/active-directory/authentication/concept-mfa-howitworks).| There's no mitigation. If MFA is configured for your tenant and Microsoft Entra ID decides to enforce it, fall back to an interactive flow such as `AcquireTokenInteractive`.| | [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) |AADSTS90010: The grant type isn't supported over the */common* or */consumers* endpoints. Use the */organizations* or tenant-specific endpoint. You used */common*.| As explained in the message from Microsoft Entra ID, the authority needs to have a tenant or otherwise */organizations*.| | [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) | AADSTS70002: The request body must contain the following parameter: `client_secret or client_assertion`.| This exception can be thrown if your application wasn't registered as a public client application in Microsoft Entra ID. In the Azure portal, edit the manifest for your application and set `allowPublicClient` to `true`. | -| [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)| `unknown_user Message`: Couldn't identify logged in user| The library was unable to query the current Windows logged-in user or this user isn't Active Directory or Microsoft Entra joined (work-place joined users aren't supported). Mitigation 1: on UWP, check that the application has the following capabilities: Enterprise Authentication, Private Networks (Client and Server), User Account Information. Mitigation 2: Implement your own logic to fetch the username (for example, john@contoso.com) and use the `AcquireTokenByIntegratedWindowsAuth` form that takes in the username.| +| [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)| `unknown_user Message`: Couldn't identify logged in user| The library was unable to query the current Windows logged-in user or this user isn't Active Directory or Microsoft Entra joined (work-place joined users aren't supported). Mitigation: Implement your own logic to fetch the username (for example, john@contoso.com) and use the `AcquireTokenByIntegratedWindowsAuth` form that takes in the username.| | [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)|integrated_windows_auth_not_supported_managed_user| This method relies on a protocol exposed by Active Directory (AD). If a user was created in Microsoft Entra ID without AD backing ("managed" user), this method will fail. Users created in AD and backed by Microsoft Entra ID ("federated" users) can benefit from this non-interactive method of authentication. Mitigation: Use interactive authentication.| ### `MsalUiRequiredException` diff --git a/msal-dotnet-articles/advanced/exceptions/msal-logging.md b/msal-dotnet-articles/advanced/exceptions/msal-logging.md index 68bd1a7a4..cfc99b262 100644 --- a/msal-dotnet-articles/advanced/exceptions/msal-logging.md +++ b/msal-dotnet-articles/advanced/exceptions/msal-logging.md @@ -150,7 +150,7 @@ To enable distributed cache logging, set the ; -2. from a service exception - , and -3. by passing a custom correlation ID to when building a token request. +1. From a successful authentication result - ; +2. From a service exception - , and +3. By passing a custom correlation ID to when building a token request. When providing your own correlation ID, use a different ID value for each request. Don't use a constant as we won't be able to differentiate between the requests. diff --git a/msal-dotnet-articles/advanced/exceptions/unity.md b/msal-dotnet-articles/advanced/exceptions/unity.md index 67ef45777..490720bda 100644 --- a/msal-dotnet-articles/advanced/exceptions/unity.md +++ b/msal-dotnet-articles/advanced/exceptions/unity.md @@ -11,7 +11,7 @@ MSAL 4.48.0 and above stopped using reflection on its `net6` target. This is the ### The issue -When using MSAL.NET in a Unity UWP app, the application builds successfully. However at runtime, exceptions, like the ones below, are thrown that some members don't exist in MSAL.NET's code: +When using MSAL.NET in a Unity app, the application builds successfully. However at runtime, exceptions, like the ones below, are thrown that some members don't exist in MSAL.NET's code: ```bash Error on deserializing read-only members in the class: No set method for property 'Claims' in type 'Microsoft.Identity.Client.OAuth2.OAuth2ResponseBase'. diff --git a/msal-dotnet-articles/advanced/testing-apps-using-msal.md b/msal-dotnet-articles/advanced/testing-apps-using-msal.md index b091c1024..fc2fb54e5 100644 --- a/msal-dotnet-articles/advanced/testing-apps-using-msal.md +++ b/msal-dotnet-articles/advanced/testing-apps-using-msal.md @@ -48,15 +48,9 @@ Daemon apps use pre-deployed secrets (passwords or certificates) to talk to Micr For native clients, there are several approaches to testing: - Use the [Username / Password](../acquiring-tokens/desktop-mobile/username-password-authentication.md) grant to fetch a token in a non-interactive way. This flow is not recommended in production, but it is reasonable to use it for testing. - - Use a framework, like Appium or Xamarin.Test, that provides an automation interface for both your app and the MSAL created browser. - -- MSAL exposes an extensibility point that allows developers to inject their own browser experience. The MSAL team uses this internally to test interactive auth scenarios. Have a look at [this test](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/main/tests/Microsoft.Identity.Test.Integration.netfx/SeleniumTests/InteractiveFlowTests.cs) project to see how to inject a [Selenium powered browser](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/tree/main/tests/Microsoft.Identity.Test.Integration.netfx/Infrastructure) that can handle authentication. - -### Xamarin apps - -The MSAL team are currently running tests on a Xamarin app that uses MSAL.net; We are using [App Center](https://appcenter.ms/apps) to manage devices, test runs etc. The test framework is [Xamarin.UITest](/appcenter/test-cloud/uitest/). A limitation that we have found is that we are unable to test system browsers, only embedded browsers. +- MSAL exposes an extensibility point that allows developers to inject their own browser experience. The MSAL team uses this internally to test interactive auth scenarios. ## Library feedback -Please log issues or ask questions related to testing. Providing a good test experience is one of the goals of the team. +Please [log issues](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues) or ask questions related to testing. Providing a good test experience is one of the goals of the team. diff --git a/msal-dotnet-articles/getting-started/choosing-msal-dotnet.md b/msal-dotnet-articles/getting-started/choosing-msal-dotnet.md index 2954f09ef..6cba022a2 100644 --- a/msal-dotnet-articles/getting-started/choosing-msal-dotnet.md +++ b/msal-dotnet-articles/getting-started/choosing-msal-dotnet.md @@ -96,12 +96,10 @@ By using token cache serializers you partition the token caches depending on the ![Image showing token caches with and without custom serializers](../media/msal-serializers.png) -### Why do you need Microsoft Identity Web.TokenCache? +### Why do you need Microsoft.Identity.Web.TokenCache? -Microsoft Identity Web.TokenCache provides token cache serialization for you. See [Token cache serialization](https://github.com/AzureAD/microsoft-identity-web/wiki/asp-net#token-cache-serialization-for-msalnet) for details. - -Another example of leveraging Microsoft Identity Web from .NET classic (MVC) can be found in that [ConfidentialClientTokenCache sample](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache). +[Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache) provides token cache serialization for you. See [Token cache serialization](../how-to/token-cache-serialization.md) for details. Examples of how to use token caches for web apps and web APIs are available in the [ASP.NET Core web app tutorial](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/) in the phase [2-2 Token Cache](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/2-WebApp-graph-user/2-2-TokenCache). For implementations have a look at the [TokenCacheProviders](https://github.com/AzureAD/microsoft-identity-web/tree/master/src/Microsoft.Identity.Web/TokenCacheProviders) folder in the [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) repository. -Microsoft Identity Web also helps with [certificate loading](https://github.com/AzureAD/microsoft-identity-web/wiki/asp-net#help-loading-certificates). +Microsoft Identity Web also helps with [certificate loading](https://github.com/AzureAD/microsoft-identity-web/wiki/asp-net#help-loading-certificates). diff --git a/msal-dotnet-articles/getting-started/instantiate-public-client-config-options.md b/msal-dotnet-articles/getting-started/instantiate-public-client-config-options.md index 0ba408aed..f6af7e9c7 100644 --- a/msal-dotnet-articles/getting-started/instantiate-public-client-config-options.md +++ b/msal-dotnet-articles/getting-started/instantiate-public-client-config-options.md @@ -33,15 +33,12 @@ In MSAL.NET 4.1+ the default redirect URI (Reply URI) can now be set with the `p This method's behavior is dependent upon the platform that you are using at the time. Here is a table that describes what redirect URI is set on certain platforms: -Platform | Redirect URI ---------- | -------------- -Desktop app (.NET FW) | `https://login.microsoftonline.com/common/oauth2/nativeclient` -UWP | value of `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()` -.NET Core | `http://localhost` +| Platform | Redirect URI | +|:----------|:-------------| +| Desktop app (.NET Framework) | `https://login.microsoftonline.com/common/oauth2/nativeclient` | +| .NET Core | `http://localhost` | -For the UWP platform, is enhanced the experience by enabling SSO with the browser by setting the value to the result of `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`. - -For .NET Core, MSAL.Net is setting the value to the local host to enable the user to use the system browser for interactive authentication. +For .NET, MSAL.NET is setting the value to the host to enable the user to use the system browser for interactive authentication. > [!NOTE] > For embedded browsers in desktop scenarios the redirect URI used is intercepted by MSAL to detect that a response is returned from the identity provider that an auth code has been returned. This URI can therefore be used in any cloud without seeing an actual redirect to that URI. This means you can and should use `https://login.microsoftonline.com/common/oauth2/nativeclient` in any cloud. If you prefer you can also use any other URI as long as you configure the redirect URI correctly with MSAL and in the app registration. Specifying the default URI in the application registration means there is the least amount of setup in MSAL. diff --git a/msal-dotnet-articles/getting-started/scenarios.md b/msal-dotnet-articles/getting-started/scenarios.md index 639e6386a..b0d141aeb 100644 --- a/msal-dotnet-articles/getting-started/scenarios.md +++ b/msal-dotnet-articles/getting-started/scenarios.md @@ -28,7 +28,7 @@ As a developer, you can acquire a token from a number of **application types**, MSAL.NET supports acquiring tokens either in the name of a **user** ![user icon](../media/user-icon.png), or, (and only for confidential client applications), in the name of the application itself (for no user). In that case the confidential client application shares a secret with Microsoft Entra ID ![Microsoft Entra ID icon](../media/certificate-icon.png) -MSAL.NET supports a number of **platforms** (.NET Framework, .NET Core, Windows 10/UWP, MAUI, Xamarin.iOS, Xamarin.Android). .NET Core apps can also run on different operating systems (Windows, but also Linux and MacOs). The scenarios can be different depending on the platforms. +MSAL.NET supports a number of **platforms** (.NET Framework, .NET, and .NET MAUI). .NET apps can also run on different operating systems (Windows, Linux, and macOS). The scenarios can be different depending on the platforms. ## The Scenarios @@ -48,7 +48,7 @@ To call the web API in the name of the user, you'll use MSAL.NET `ConfidentialCl To call a web API from a mobile application, you use MSAL.NET's PublicClientApplication's [interactive](../acquiring-tokens/desktop-mobile/acquiring-tokens-interactively.md) token acquisition methods. These interactive methods enable you to control the sign-in UI experience, as well as the location of the interactive dialog on some platforms. -To enable this interaction, MSAL.NET leverages a [web browser](/azure/active-directory/develop/msal-net-web-browsers). There are specificities depending on the mobile platform ([UWP](../acquiring-tokens/desktop-mobile/uwp.md), [iOS](/azure/active-directory/develop/msal-net-xamarin-ios-considerations), or [Android](/azure/active-directory/develop/msal-net-xamarin-android-considerations)). On iOS and Android, you can even choose if you want to leverage the system browser (the default), or an embedded web browser. You can enable some kind of token cache sharing on iOS. +To enable this interaction, MSAL.NET leverages a [web browser](/azure/active-directory/develop/msal-net-web-browsers). There are specificities depending on the mobile platform. On iOS and Android, you can choose if you want to leverage the system browser (the default) or an embedded web browser. You can enable token cache sharing on iOS. ![Image showing flows in a mobile app that calls a web API on behalf of the user](../media/net-mobile-api.png) diff --git a/msal-dotnet-articles/how-to/default-reply-uri.md b/msal-dotnet-articles/how-to/default-reply-uri.md index da0408c97..e3283ac5a 100644 --- a/msal-dotnet-articles/how-to/default-reply-uri.md +++ b/msal-dotnet-articles/how-to/default-reply-uri.md @@ -12,11 +12,8 @@ This method's behavior is dependent upon the platform that you are using at the | Platform | Redirect URI | |----------------------------------|-----------------------------------------------------------------------| | Desktop (.NET Framework) | `https://login.microsoftonline.com/common/oauth2/nativeclient` | -| Universal Windows Platform (UWP) | Value of `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()` | | .NET Core | `http://localhost` | -For the UWP platform, we want to enhance the experience by enabling SSO with the browser by setting the value to the result of [`WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`](/uwp/api/windows.security.authentication.web.webauthenticationbroker.getcurrentapplicationcallbackuri). - For .NET Core, we are setting the value to the local host to enable the user to use the system browser for interactive authentication since .NET Core does not have a UI for the embedded web view at the moment. > [!NOTE] diff --git a/msal-dotnet-articles/how-to/migrate-confidential-client.md b/msal-dotnet-articles/how-to/migrate-confidential-client.md index 81a00fb1b..9866f0b1c 100644 --- a/msal-dotnet-articles/how-to/migrate-confidential-client.md +++ b/msal-dotnet-articles/how-to/migrate-confidential-client.md @@ -168,7 +168,7 @@ public partial class AuthWrapper If you don't setup token caching, the token issuer will throttle you, resulting in errors. It also takes a lot less to get a token from the cache (10-20ms) than it is from ESTS (500-30000ms). -If you want to implement a distributed token cache, see [Token cache for a web app or web API (confidential client application)](token-cache-serialization.md?tabs=aspnet) and the sample [active-directory-dotnet-v1-to-v2/ConfidentialClientTokenCache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache). +If you want to implement a distributed token cache, see [Token cache for a web app or web API (confidential client application)](token-cache-serialization.md?tabs=aspnet). [Learn more about the daemon scenario](/azure/active-directory/develop/scenario-daemon-overview) and how it's implemented with MSAL.NET or Microsoft.Identity.Web in new applications. @@ -299,7 +299,7 @@ public partial class AuthWrapper #### Benefit from token caching -For token caching in OBOs, use a distributed token cache. For details, see [Token cache for a web app or web API (confidential client app)](token-cache-serialization.md?tabs=aspnet) and read through [sample code](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache). +For token caching in OBOs, use a distributed token cache. For details, see [Token cache for a web app or web API (confidential client app)](token-cache-serialization.md?tabs=aspnet). ```CSharp app.UseInMemoryTokenCaches(); // or a distributed token cache. @@ -474,8 +474,7 @@ public partial class AuthWrapper #### Benefit from token caching -Because your web app uses `AcquireTokenByAuthorizationCode`, it needs to use a distributed token cache for token caching. For details, see [Token cache for a web app or web API](token-cache-serialization.md?tabs=aspnet) and read through [sample code](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache). - +Because your web app uses `AcquireTokenByAuthorizationCode`, it needs to use a distributed token cache for token caching. For details, see [Token cache for a web app or web API](token-cache-serialization.md?tabs=aspnet). ```CSharp app.UseInMemoryTokenCaches(); // or a distributed token cache. diff --git a/msal-dotnet-articles/how-to/migrate-public-client.md b/msal-dotnet-articles/how-to/migrate-public-client.md index 1ab562124..0c6b6d87f 100644 --- a/msal-dotnet-articles/how-to/migrate-public-client.md +++ b/msal-dotnet-articles/how-to/migrate-public-client.md @@ -17,7 +17,7 @@ ms.custom: devx-track-csharp, aaddev, has-adal-ref, devx-track-dotnet # Migrate public client applications from ADAL.NET to MSAL.NET -This article describes how to migrate a public client application from Azure Active Directory Authentication Library for .NET (ADAL.NET) to Microsoft Authentication Library for .NET (MSAL.NET). Public client applications are desktop apps, including Win32, WPF, and UWP apps, and mobile apps, that call another service on the user's behalf. For more information about public client applications, see [Authentication flows and application scenarios](/azure/active-directory/develop/authentication-flows-app-scenarios). +This article describes how to migrate a public client application from Azure Active Directory Authentication Library for .NET (ADAL.NET) to Microsoft Authentication Library for .NET (MSAL.NET). Public client applications are desktop apps, including Win32, WPF, and mobile apps, that call another service on the user's behalf. For more information about public client applications, see [Authentication flows and application scenarios](/azure/active-directory/develop/authentication-flows-app-scenarios). ## Migration steps @@ -108,7 +108,7 @@ catch (MsalUiRequiredException) // no change in the pattern // 5. AcquireTokenInteractive var authResult = await pca.AcquireTokenInteractive(new[] { "User.Read" }) .WithAccount(accountToLogin) // this already exists in MSAL, but it is more important for WAM - .WithParentActivityOrWindow(myWindowHandle) // to be able to parent WAM's windows to your app (optional, but highly recommended; not needed on UWP) + .WithParentActivityOrWindow(myWindowHandle) // to be able to parent WAM's windows to your app (optional, but highly recommended) .ExecuteAsync(); } ``` @@ -212,10 +212,7 @@ result = await context.AcquireTokenAsync(resource, clientId, // Explanation: the library was unable to query the current Windows logged-in user or this user is not AD or Azure AD // joined (work-place joined users are not supported). - // Mitigation 1: on UWP, check that the application has the following capabilities: Enterprise Authentication, - // Private Networks (Client and Server), User Account Information - - // Mitigation 2: Implement your own logic to fetch the username (e.g. john@contoso.com) and use the + // Mitigation: Implement your own logic to fetch the username (e.g. john@contoso.com) and use the // AcquireTokenByIntegratedWindowsAuth form that takes in the username // Error Code: integrated_windows_auth_not_supported_managed_user diff --git a/msal-dotnet-articles/how-to/token-cache-serialization.md b/msal-dotnet-articles/how-to/token-cache-serialization.md index d6e10d47e..36327232e 100644 --- a/msal-dotnet-articles/how-to/token-cache-serialization.md +++ b/msal-dotnet-articles/how-to/token-cache-serialization.md @@ -327,8 +327,7 @@ var app = ConfidentialClientApplicationBuilder ### Samples -- The following sample showcases using the token cache serializers in .NET Framework and .NET Core applications: [ConfidentialClientTokenCache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache). -- The following sample is an ASP.NET web app that uses the same techniques: [Use OpenID Connect to sign in users to Microsoft identity platform](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect). +- The following sample is an ASP.NET web app: [Use OpenID Connect to sign in users to Microsoft identity platform](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect). ## [Desktop apps](#tab/desktop) @@ -392,7 +391,7 @@ If you want to write your own token cache serializer, MSAL.NET provides custom t On confidential client applications that handle users (web apps that sign in users and call web APIs, and web APIs that call downstream web APIs), there can be many users. The users are processed in parallel. For security and performance reasons, our recommendation is to serialize one cache per user. Serialization events compute a cache key based on the identity of the processed user and serialize or deserialize a token cache for that user. -Remember, custom serialization isn't available on mobile platforms (UWP, Xamarin.iOS, and Xamarin.Android). MSAL already defines a secure and performant serialization mechanism for these platforms. .NET desktop and .NET Core applications, however, have varied architectures. And MSAL can't implement a general-purpose serialization mechanism. +Remember, custom serialization isn't available on mobile platforms. MSAL already defines a secure and performant serialization mechanism for these platforms. .NET desktop and .NET Core applications, however, have varied architectures. And MSAL can't implement a general-purpose serialization mechanism. For example, websites might choose to store tokens in a Redis cache, or desktop apps might store tokens in an encrypted file. So serialization isn't provided out of the box. To have a persistent token cache application in .NET desktop or .NET Core, customize the serialization. @@ -488,10 +487,6 @@ static class TokenCacheHelper A product-quality, file-based token cache serializer for public client applications (for desktop applications running on Windows, Mac, and Linux) is available from the [Microsoft.Identity.Client.Extensions.Msal](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet/tree/master/src/Microsoft.Identity.Client.Extensions.Msal) open-source library. You can include it in your applications from the following NuGet package: [Microsoft.Identity.Client.Extensions.Msal](https://www.nuget.org/packages/Microsoft.Identity.Client.Extensions.Msal/). -#### Dual token cache serialization (MSAL unified cache) - -If you want to implement token cache serialization with the unified cache format (common to MSAL.NET 2.x and other MSALs of the same generation or older, on the same platform), take a look at the following sample: https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/TokenCacheMigration/ADAL2MSAL. - --- ## Monitor cache hit ratios and cache performance @@ -547,5 +542,5 @@ The following samples illustrate token cache serialization. | Sample | Platform | Description| | ------ | -------- | ----------- | |[active-directory-dotnet-desktop-msgraph-v2](https://github.com/azure-samples/active-directory-dotnet-desktop-msgraph-v2) | Desktop (WPF) | Windows Desktop .NET (WPF) application that calls the Microsoft Graph API. ![Diagram that shows a topology with a desktop app client flowing to Microsoft Entra ID by acquiring a token interactively and to Microsoft Graph.](../media/msal-net-token-cache-serialization/topology.png)| -|[active-directory-dotnet-v1-to-v2](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2) | Desktop (console) | Set of Visual Studio solutions that illustrate the migration of Azure AD v1.0 applications (using ADAL.NET) to Microsoft identity platform applications (using MSAL.NET). In particular, see [Token cache migration](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/blob/master/TokenCacheMigration/README.md) and [Confidential client token cache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache). | +|[active-directory-dotnet-v1-to-v2](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2) | Desktop (console) | Set of Visual Studio solutions that illustrate the migration of Azure AD v1.0 applications (using ADAL.NET) to Microsoft identity platform applications (using MSAL.NET). | [ms-identity-aspnet-webapp-openidconnect](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect) | ASP.NET (net472) | Example of token cache serialization in an ASP.NET MVC application (using MSAL.NET). diff --git a/msal-dotnet-articles/index.md b/msal-dotnet-articles/index.md index 9e4ca6141..e4d0ce646 100644 --- a/msal-dotnet-articles/index.md +++ b/msal-dotnet-articles/index.md @@ -17,7 +17,9 @@ ms.custom: devx-track-csharp, aaddev # Microsoft Authentication Library for .NET -MSAL.NET ([Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client)) is an authentication library that enables you to acquire tokens from Microsoft Entra ID, to access protected web APIs (Microsoft APIs or applications registered with Microsoft Entra ID). MSAL.NET is available on several .NET platforms (Desktop, Universal Windows Platform, MAUI, Xamarin Android, Xamarin iOS, Windows 8.1, and .NET Core). +MSAL.NET ([Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client)) is an authentication library that enables you to acquire tokens from Microsoft Entra ID to access protected web APIs (Microsoft APIs or applications registered with Microsoft Entra ID). + +MSAL.NET is available on several .NET platforms (desktop, mobile, and web). > [!div class="nextstepaction"] > [Get MSAL.NET >](https://www.nuget.org/packages/Microsoft.Identity.Client/) @@ -26,95 +28,56 @@ MSAL.NET ([Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.I MSAL.NET supports different application topologies, including: -- [Native clients](/azure/active-directory/develop/active-directory-dev-glossary#native-client) (mobile or desktop applications) calling the Microsoft Graph API on behalf of a user, +- [Native clients](/azure/active-directory/develop/active-directory-dev-glossary#native-client) (mobile or desktop applications) calling the Microsoft Graph API on behalf of a user. - Daemons, services, or [web clients](/azure/active-directory/develop/active-directory-dev-glossary#web-client) (web apps or web APIs) calling the Microsoft Graph API on behalf of a user, or without a user. -With the exception of [User-agent based client](/azure/active-directory/develop/active-directory-dev-glossary#user-agent-based-client) which is only supported in JavaScript. - For more details about the supported scenarios, see [Scenarios](./getting-started/scenarios.md). -MSAL.NET supports multiple platforms, including .NET Framework, [.NET Core](https://www.microsoft.com/net/learn/get-started/windows)(including .NET 6), [MAUI](https://dotnet.microsoft.com/apps/maui), [Xamarin](https://www.xamarin.com/) Android, Xamarin iOS, and [UWP](/windows/uwp/get-started/universal-application-platform-guide). +MSAL.NET supports multiple platforms, including [.NET](https://dotnet.microsoft.com/), [.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework), and [.NET MAUI](https://dotnet.microsoft.com/apps/maui). - > [!NOTE] - > Not all the authentication features are available in all platforms, mostly because: - > - >- Mobile platforms (Xamarin, MAUI and UWP) do not allow confidential client flows, because they are not meant to function as a backend and cannot store secrets securely. - >- On public clients (mobile and desktop), the default browser and redirect URIs are different from platform to platform and broker availability varies (details [in browser usage documentation](./acquiring-tokens/using-web-browsers.md)). +> [!NOTE] +> Not all the authentication features are available in all platforms. +> +>- Mobile platforms do not allow confidential client flows. They are not meant to function as a backend and cannot store secrets securely. +>- On public clients (mobile and desktop) the default browser and redirect URIs are different from platform to platform, and broker availability varies (details [in browser usage documentation](./acquiring-tokens/using-web-browsers.md)). - Most of the articles in this MSAL.NET reference content describe the most complete platform (.NET Framework), but, topic by topic, it occasionally calls out differences between platforms. +> [!NOTE] +> MSAL.NET versions 4.61.0 and above do not provide support for Universal Windows Platform, Xamarin Android, and Xamarin iOS. Read more about the deprecation in [Announcing the Upcoming Deprecation of MSAL.NET for Xamarin and UWP](https://devblogs.microsoft.com/identity/uwp-xamarin-msal-net-deprecation/). ## Why use MSAL.NET ? -MSAL.NET ([Microsoft Authentication Library for .NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet)) enables developers of .NET applications to acquire tokens in order to call secured web APIs. These web APIs can be the Microsoft Graph API, other Microsoft APIS, 3rd party Web APIs, or your own Web API. - -As a token acquisition library, MSAL.NET provides several ways of getting a token, with a consistent API for a number of platforms. Using MSAL.NET adds value over using OAuth libraries and coding against the protocol by: +MSAL.NET provides several ways of getting a token. Using MSAL.NET is easier than using generic OAuth libraries or writing calls against the protocol. MSAL.NET provides several out-of-the-box benefits that simplify the developer workflow: -- Maintains a **token cache** and **refreshes tokens** for you when they are close to expire. -- Eliminates the need for you to handle token expiration by yourself. -- Helps you specify which **audience** you want your application to sign-in (your organization, several organizations, work and school and Microsoft personal accounts, social identities with Azure AD B2C, users in sovereign and national clouds). +- Maintain a **token cache** and **refresh tokens** for you when they are close to expiry. +- Helps you specify which **audience** you want your application to sign-in (your organization, several organizations, work, school, and Microsoft personal accounts, social identities with Microsoft Entra External ID, or users in sovereign and national clouds). - Helps you set-up the application through **configuration** files. - Helps you troubleshoot the app by exposing actionable exceptions, logging, and telemetry. -### MSAL.NET is about acquiring tokens, not protecting an API - -MSAL.NET is used to acquire tokens. It's not used to protect a Web API. If you are interested in protecting a Web API with Microsoft Entra ID, you might want to check out: - -- [Microsoft Entra ID with ASP.NET Core](/aspnet/core/security/authentication/azure-active-directory/). Note that some of these examples present web apps which also call a web API with MSAL.NET. -- [Active-directory-dotnet-native-aspnetcore-v2](https://github.com/azure-samples/active-directory-dotnet-native-aspnetcore-v2) which shows how to call an ASP.NET Core Web API from a WPF application using Azure AD v2. -- The [IdentityModel extensions for .Net](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet) open source library providing middleware used by ASP.NET and ASP.NET Core to protect APIs. - -## Conceptual documentation - -### Getting started with MSAL.NET +## Getting started with MSAL.NET 1. Learn about [MSAL.NET usage scenarios](./getting-started/scenarios.md). -1. You will need to [register your app](/azure/active-directory/develop/quickstart-register-app) with Microsoft Entra ID. -1. Learn about the [types of client applications](/azure/active-directory/develop/msal-client-applications): public client and confidential client. +1. [Register your app](/azure/active-directory/develop/quickstart-register-app) with Microsoft Entra ID. +1. Learn about the [types of client applications](/entra/identity-platform/msal-client-applications): public client and confidential client. 1. Learn about [acquiring tokens](acquiring-tokens/overview.md) to access a protected API. -### Acquiring tokens - -#### Acquiring tokens from cache in any app +## Considerations -- [AcquireTokenSilent](acquiring-tokens/acquiretokensilentasync-api.md) enables you to get a previously cached token. +MSAL.NET is used to acquire tokens. It's not used to protect a Web API. If you are interested in protecting a Web API with Microsoft Entra ID, check out: -#### Acquiring tokens in desktop and mobile apps (public client applications) - -- [Acquiring a token interactively](acquiring-tokens/desktop-mobile/acquiring-tokens-interactively.md) enables the application to acquire a token after authenticating the user through an interactive sign-in. There are implementation-specific details depending on the target platforms, such as [Xamarin Android](acquiring-tokens/desktop-mobile/xamarin.md) or [UWP](acquiring-tokens/desktop-mobile/uwp.md). -- Acquiring a token silently on a Windows domain or Microsoft Entra joined machine with [Integrated Windows Authentication](./acquiring-tokens/desktop-mobile/integrated-windows-authentication.md) or by using [Username/passwords](./acquiring-tokens/desktop-mobile/username-password-authentication.md) (not recommended). -- Acquiring a token on a text-only device, by directing the user to sign-in on another device with the [Device Code Flow](./acquiring-tokens/desktop-mobile/device-code-flow.md). -- Acquiring a token using the [Web Account Manager (WAM)](./acquiring-tokens/desktop-mobile/wam.md), a Windows OS component that acts a broker allowing the users of your app benefit from integration with accounts known to Windows. - -#### Acquiring tokens in web apps, web APIs, and daemon apps (confidential client applications) - -- Acquiring a token for the app (without a user) with [client credential flows](acquiring-tokens/web-apps-apis/client-credential-flows.md). -- Acquiring a token [on behalf of a user](acquiring-tokens/web-apps-apis/on-behalf-of-flow.md) in service-to-service calls. -- Acquiring a token for the signed-in user [by authorization code](acquiring-tokens/web-apps-apis/authorization-codes.md) in Web Apps. - -#### Confidential client availability - -MSAL.NET is a multi-framework library. All confidential client flows **are available on**: - -- .NET Core -- .NET Desktop -- .NET Standard - -They are not available on the mobile platforms, because the OAuth2 spec states that there should be a secure, dedicated connection between the application and the identity provider. This secure connection can be achieved on web servers and web API back-ends by deploying a certificate (or a secret string, but this is not recommended for production). It cannot be achieved on mobile apps and other client applications that are distributed to users. As such, these confidential flows **are not available on**: - -- Xamarin.Android / MAUI Android -- Xamarin.iOS / MAUI iOS -- UWP and WinUI +- [Microsoft Entra ID with ASP.NET Core](/aspnet/core/security/authentication/azure-active-directory/). Examples showcase web apps that call a web API with MSAL.NET. +- [active-directory-dotnet-native-aspnetcore-v2](https://github.com/azure-samples/active-directory-dotnet-native-aspnetcore-v2) shows how to call an ASP.NET Core Web API from a WPF application using Microsoft Entra ID. +- The [IdentityModel extensions for .NET](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet) open source library provides middleware used by ASP.NET and ASP.NET Core to protect APIs. ## Migration from Azure Active Directory Authentication Library (ADAL) -Microsoft Authentication Library (MSAL) for .NET is the supported library that can be used for authentication token acquisition. If you or your organization are using the Azure Active Directory Authentication Library (ADAL), you should [migrate to MSAL](/azure/active-directory/develop/msal-migration). ADAL will reach end-of-life by **June 30, 2023**. +Microsoft Authentication Library (MSAL) for .NET is the supported library that can be used for authentication token acquisition. If you or your organization are using the Azure Active Directory Authentication Library (ADAL), you should [migrate to MSAL](/entra/identity-platform/msal-migration). ADAL reached end-of-life on **June 30, 2023**. > [!NOTE] -> While ADAL will be deprecated on June 30, 2023, applications depending on ADAL should not break as the underlying endpoint will remain active. However, no new features or support will be offered for ADAL. +> While ADAL is deprecated since June 30, 2023, applications depending on ADAL should not break as the underlying endpoint will remain active. However, no new features or support will be offered for ADAL. ## Releases -For previous releases, see the [Releases page on GitHub](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases). Minor (feature) releases are published every month. A feature could be included in a release or not depending on its complexity. Smaller patch or urgent fixes can be releases more frequently. Some of the security issues are back ported to the last major/minor release. +For previous releases, see the [Releases on GitHub](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases). For work-in-progress and future releases, see [Milestones](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/milestones). @@ -122,9 +85,4 @@ For additional information on versioning, see [Semantic versioning - API change ## Samples -See [our comprehensive sample list](/azure/active-directory/develop/active-directory-v2-code-samples). - -## FAQ - -- How MSAL.NET uses [web browsers](/azure/active-directory/develop/msal-net-web-browsers) for interactive authentication. -- If you have issues with Xamarin.Forms applications leveraging MSAL.NET please read [Troubleshooting Xamarin.Android issues with MSAL](/azure/active-directory/develop/msal-net-xamarin-android-considerations). +See [our comprehensive sample list](/entra/identity-platform/sample-v2-code). diff --git a/msal-dotnet-articles/resources/handling-pii.md b/msal-dotnet-articles/resources/handling-pii.md index f8e7d7679..51b3e10a3 100644 --- a/msal-dotnet-articles/resources/handling-pii.md +++ b/msal-dotnet-articles/resources/handling-pii.md @@ -7,47 +7,54 @@ description: Outlines what MSAL considers to be personally identifiable informat ## Data classification -Microsoft defines the following [data classification](https://www.microsoft.com/en-us/trust-center/privacy/customer-data-definitions). MSAL libraries, for simplicity, expose a single "allow PII" (personally identifiable information) flag for logging. This single flag combines all data categories mention above. +Microsoft defines the following [data classification](https://www.microsoft.com/trust-center/privacy/customer-data-definitions). MSAL libraries, for simplicity, expose a single PII (personally identifiable information) enablement flag for logging. This single flag combines all categories covered by the data classification document. + +## Logging approach + +To read more about how MSAL.NET does logging, refer to [Logging in MSAL.NET](../advanced/exceptions/msal-logging.md). Specifically, logging data that contains personally-identifiable information (PII) will require the use of the `enablePiiLogging` flag when using . + +>[!NOTE] +>Using `enablePiiLogging` will influence what PII is shown in MSAL exception messages, including those that stem from the [using the Web Account Manager (WAM)](../acquiring-tokens/desktop-mobile/wam.md). This also coveres end-user identifiable information (EUII), such as UPN, name, or email. ## What MSAL will never log -- Tokens (access tokens, ID tokens, refresh tokens, client assertions generated by MSAL, etc.) -- Passwords (MSAL is only given the password during the Username / Password (ROPC) flow. MSAL does not have access to the password entered by the user in a browser.) -- Authorization codes -- PKCE code -- Successful network responses from the _/authorize_ or _/token_ endpoints (because they may contain tokens or auth codes) -- Network requests (they may contain passwords) -- Private keys of certificates +- Tokens, including access tokens, ID tokens, refresh tokens, and client assertions generated by MSAL. +- Passwords, as MSAL is only given the password during the username and password flow. MSAL does not have access to the password entered by the user in a browser. +- Authorization codes. +- PKCE code. +- Successful network responses from the `/authorize` or `/token` endpoints because they may contain tokens or auth codes. +- Network requests, as they may contain passwords. +- Private keys of certificates. ## What MSAL considers as PII -- username -- login hint -- ID token claims, which include names, address, and other user details (MSAL only parses the ID token, it never looks at access or refresh tokens) -- authorization URI (it may contain a login hint) -- object ID (i.e. `oid` claim) +- Username. +- Login hint. +- ID token claims, which include names, address, or other user details. MSAL only parses the ID token, it never looks at access or refresh tokens. +- Authorization URI, as it may contain a login hint. +- Object ID (i.e. `oid` claim). ## What MSAL does not consider as PII -- IDs related to an organization or tenant, not the user, like tenant ID, directory ID, directory name (e.g. contonso.onmicrosoft.com) -- authority -- scopes and resource names -- client (application) ID -- service principal details (object ID, client ID) -- exception messages and stack traces, including error codes coming from Microsoft Entra ID -- HTTP details other than request and response (HTTP status codes, payload size, etc.) -- correlation ID -- runtime details (OS name, .NET version) -- internal API details (class names, method names) -- request details (algorithm names (e.g. RSA), OIDC constants, etc.) -- certificate thumbprints other than key IDs +- IDs related to an organization or tenant (not the user) like tenant ID, directory ID, or directory name (e.g. `contoso.onmicrosoft.com`). +- Authority. +- Scopes and resource names. +- Client (application) ID. +- Service principal details, such as object ID and client ID. +- Exception messages and stack traces, including error codes coming from Microsoft Entra ID. +- HTTP details other than request and response (for example, HTTP status codes or payload size). +- Correlation IDs. +- Runtime details, such as OS name, .NET platform version. +- Internal API details, such as class names, method names. +- Request details, such as algorithm names (e.g. RSA) or OIDC constants. +- Certificate thumbprints other than key IDs. ## PII in exceptions -MSAL generates exception messages that do not contain PII. s, generated by MSAL or passed from Microsoft Entra ID) are considered to not contain PII. +MSAL generates exception messages that do not contain PII. instances, generated by MSAL or passed from Microsoft Entra ID, are considered to not contain PII. -Some framework exception may contain PII, although this is rare (e.g. a `PathInvalidException` may contain the username). SDKs take care to not log framework exceptions which may contain PII. +Some framework exception may contain PII, although this is rare (e.g. a `PathInvalidException` may contain the username). MSAL takes care to not log framework exceptions which may contain PII. ## Organization identifiable information -MSAL can log organization identifiable information (OII) because as per the official data classification, organization identifiable information is not PII. OII includes data like tenant ID, object ID for service principals, scope names. Remember that the app developer still controls the destination of this logging data. +MSAL can log organization identifiable information (OII) because, as per the official data classification, organization identifiable information is not considered PII. OII includes data like tenant ID, object ID for service principals, or scope names. The application developer still controls the destination of this logging data. diff --git a/msal-dotnet-articles/resources/ios12-security-advisory.md b/msal-dotnet-articles/resources/ios12-security-advisory.md deleted file mode 100644 index fc7fabba2..000000000 --- a/msal-dotnet-articles/resources/ios12-security-advisory.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: iOS 12 security advisory ---- - -# iOS 12 security advisory - -There is a known issue with iOS12 and social, WSFed, and OIDC Logins. The asp.net team has issued a [security advisory](https://github.com/aspnet/Security/issues/1864). - -You may see something similar to this [ADAL issue](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/issues/1329) or this [webkit bug](https://bugs.webkit.org/show_bug.cgi?id=188165) when using iOS12. The issue is external to MSAL. diff --git a/msal-dotnet-articles/resources/known-issues.md b/msal-dotnet-articles/resources/known-issues.md index c007fd89f..79cd06542 100644 --- a/msal-dotnet-articles/resources/known-issues.md +++ b/msal-dotnet-articles/resources/known-issues.md @@ -24,8 +24,8 @@ Users are unable to login interactively and a "Device is not compliant" error is #### Mitigation * The recommended approach is to use [WAM](../acquiring-tokens/desktop-mobile/wam.md). -* Otherwise, you can also configure MSAL to use the system (default OS) browser (details in [Using web browsers (MSAL.NET)](/azure/active-directory/develop/msal-net-web-browsers#how-to-use-the-default-os-browser)). Both Chrome and Microsoft Edge browsers are able to satisfy the device policy. -* If using ADAL, migrate to MSAL first. There is no mitigation for ADAL use. +* You can also configure MSAL to use the system (default OS) browser. Details in [Using web browsers (MSAL.NET)](/azure/active-directory/develop/msal-net-web-browsers#how-to-use-the-default-os-browser). Both Microsoft Edge and Chrome browsers are able to satisfy the device policy. +* If using ADAL, [**migrate to MSAL**](/entra/identity-platform/msal-migration). There is no mitigation for ADAL. ### Android @@ -35,12 +35,6 @@ On Android, an `AndroidActivityNotFound` exception is thrown when the device doe Please see [Xamarin iOS Considerations](/azure/active-directory/develop/msal-net-xamarin-ios-considerations#known-issues-with-ios-12-and-authentication). -### UWP - -The recommended approach is to use [WAM](../acquiring-tokens/desktop-mobile/wam.md). - -Most issues on UWP occur due to network problems, such as proxies that block the traffic etc. Integrated Windows Auth may also be blocked by admins. For more details see [Considerations for using Universal Windows Platform with MSAL.NET](/azure/active-directory/develop/msal-net-uwp-considerations#troubleshooting). - ### Desktop On a Desktop app, a `StateMismatchError` exception is thrown when the using a long Facebook ID (via B2C) in conjunction with the embedded browser. @@ -50,4 +44,4 @@ For more details, please [refer to our documentation](../advanced/exceptions/und Behavior: an error similar to `Microsoft.Windows.SDK.Contracts.targets(4,5): error : Must use PackageReference` is thrown -Starting with version 4.23, MSAL references `Microsoft.Windows.SDK.Contracts`. NuGet can only resolve this reference if the application consuming MSAL references it as `` and not via the legacy `packages.config` mechanism. See #2247 for details on how to fix this. +Starting with version 4.23, MSAL references `Microsoft.Windows.SDK.Contracts`. NuGet can only resolve this reference if the application consuming MSAL references it as `` and not via the legacy `packages.config` mechanism. See [#2247](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/2247) for details on how to fix this. diff --git a/msal-dotnet-articles/resources/semantic-versioning-api-change-management.md b/msal-dotnet-articles/resources/semantic-versioning-api-change-management.md index bf2b6b131..ed6a7f88e 100644 --- a/msal-dotnet-articles/resources/semantic-versioning-api-change-management.md +++ b/msal-dotnet-articles/resources/semantic-versioning-api-change-management.md @@ -1,9 +1,10 @@ --- title: Semantic versioning and API change management +description: "MSAL.NET strategy for versioning library releases" --- # Semantic versioning and API change management -MSAL.NET has adopted [semantic versioning](https://semver.org/), the industry standard for OSS projects. +MSAL.NET has adopted [semantic versioning](https://semver.org/), the industry standard for open-source projects. -Per the semantic versioning spec, breaking changes (a.k.a. incompatible changes) will only be released with a major version bump. When that happens, we will document that change in the [release notes](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases). +Per the semantic versioning specification, breaking changes (i.e., incompatible changes) will only be released with a major version bump. When that happens, we will document that change in the [release notes](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases). diff --git a/msal-dotnet-articles/resources/telemetry-overview.md b/msal-dotnet-articles/resources/telemetry-overview.md index b932148b5..4cd17692f 100644 --- a/msal-dotnet-articles/resources/telemetry-overview.md +++ b/msal-dotnet-articles/resources/telemetry-overview.md @@ -5,24 +5,29 @@ description: Explore MSAL.NET's telemetry capabilities for Microsoft Entra token # MSAL.NET telemetry overview -MSAL.NET sends basic telemetry about the client side state on requests to the Microsoft Entra token endpoint. Telemetry data will be logged by Microsoft Entra ID. This telemetry will give us visibility into both 1st and 3rd party app health without introducing an additional telemetry pipeline dependency into the open source SDK. MSAL.NET collects this telemetry to proactively detect server side failures or library regressions, in order to provide a better service. +MSAL.NET sends basic telemetry about the client side state on requests to the Microsoft Entra token endpoint. Telemetry data will be logged by Microsoft Entra ID. This telemetry will give us visibility into both first and third party app health without introducing an additional telemetry pipeline dependency into the open source SDK. -Basic telemetry includes: +MSAL.NET collects this telemetry to proactively detect server side failures or library regressions in order to provide a better service. -* Client side state at the time of the request - shows the reason for the request execution, e.g. client app requested prompt, no cached tokens, expired access token etc -* Errors for preceding requests that failed -* SDK API usage metadata - e.g. which API/parameters were used for the request +Basic library telemetry includes: + +* Client side state at the time of the request. It shows the reason for the request execution, for example client app requested prompt, no cached tokens, expired access, or others. +* Errors for preceding requests that failed. +* SDK API usage metadata, such as which API and parameters were used for the request. + +>[!IMPORTANT] +>For details on how personally identifiable information (PII) or organizational identifiable information (OII) is handled, refer to [Handling of personally-identifiable information in MSAL.NET](handling-pii.md). ## Data MSAL requests to the token endpoint will have 2 additional headers: -* Current request header: "x-client-current-telemetry" +* Current request header: `x-client-current-telemetry` * Current request will contain information about the current public API request. -* Last request header: "x-client-last-telemetry" - * Last request contains information about failures for any previous requests. +* Last request header: `x-client-last-telemetry` + * Last request contains information about failures for any previous requests. -Current request and last request are appended to calls to the token endpoint. +Current request and last request are appended to calls to the token endpoint. ### Current request example diff --git a/msal-dotnet-articles/resources/troubleshooting.md b/msal-dotnet-articles/resources/troubleshooting.md index d449b92ee..98bc1177e 100644 --- a/msal-dotnet-articles/resources/troubleshooting.md +++ b/msal-dotnet-articles/resources/troubleshooting.md @@ -59,20 +59,6 @@ Auto-discovery happens once and only once before the first call to acquire token Restart your service and capture logs. Look at `AuthenticationResult.AuthenticationResultMetadata.RegionDetails` to understand if auto-discovery failed. Send the logs to the MSAL team. -## AcquireTokenInteractive crashes in a UWP app for ARM64 - -### Symptom - -On ARM64 (for example a Surface Pro X), the app crashes with an unrecoverable exception in SharedLibrary.dll. - -### Workaround - -Add this to the .csproj file: - -```xml -false -``` - ## GetAccountAsync doesn't return any account in clouds scenarios ### Symptom