Skip to content

Update CustomWebUI interface docs with security related caution message #721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Dickson-Mwendia merged 6 commits into from
Feb 4, 2026
Merged

Update CustomWebUI interface docs with security related caution message #721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2ee7dc9
Update CustomWebUI inerface docs with security caution
ashok672 Jan 27, 2026
a2f68c7
fix link for embedded browser flow documenation
ashok672 Jan 27, 2026
93ae232
fix for review comments
ashok672 Jan 27, 2026
02f2cb9
Fix for review comments.
ashok672 Feb 3, 2026
8b69f1f
fix for review comments
ashok672 Feb 3, 2026
e45af06
Update ICustomWebUi.xml
ashok672 Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion dotnet/xml/Microsoft.Identity.Client.Extensibility/ICustomWebUi.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,13 +55,24 @@
</AssemblyInfo>
<Interfaces />
<Docs>
<remarks>
<format type="text/markdown"><![CDATA[
> [!CAUTION]
> **ICustomWebUi is not recommended for production use due to security risks and current service limitations, and is on a deprecation path.**
>
> This pattern introduces security risks and is not supported by Entra ID cloud services. Using native client redirect URIs (like `https://login.microsoftonline.com/common/oauth2/nativeclient`) with custom web UI implementations typically requires users to manually copy the authorization code from the URL—an anti-pattern most commonly seen with the `nativeclient` URI. This pattern will not work in most configurations and poses security risks.
>
> - **Recommended Alternatives**:
> - **Use [Broker authentication (WAM)](https://learn.microsoft.com/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam)** for Windows 10+ applications - provides the best security and user experience
> - **Use embedded browser flow** as described in [Using web browsers](https://learn.microsoft.com/entra/msal/dotnet/acquiring-tokens/using-web-browsers)
]]></format>
</remarks>
<summary>
Interface that an MSAL.NET extender can implement to provide their own web UI in public client applications
to sign-in user and have them consented part of the Authorization code flow.
MSAL.NET provides an embedded web view for Windows and Mac, but there are other scenarios not yet supported.
This extensibility point enables them to provide such UI in a secure way
</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
<Member MemberName="AcquireAuthorizationCodeAsync">
Expand Down
11 changes: 10 additions & 1 deletion msal-dotnet-articles/advanced/extensibility-points.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,15 @@ Details [here](/dotnet/api/microsoft.identity.client.abstractacquiretokenparamet

## Desktop / Mobile Apps - ICustomWebUi

Allows desktop and mobile apps to use their own browser instead of the embedded / system browsers provided by MSAL.
> [!CAUTION]
> **ICustomWebUi is not recommended for production use due to security risks and current service limitations, and is on a deprecation path.**
>
> This pattern introduces security risks and is not supported by Entra ID cloud services. Using native client redirect URIs (like `https://login.microsoftonline.com/common/oauth2/nativeclient`) with custom web UI implementations typically requires users to manually copy the authorization code from the URL—an anti-pattern most commonly seen with the `nativeclient` URI. This pattern will not work in most configurations and poses security risks.
>
> - **Recommended Alternatives**:
> - **Use [Broker authentication (WAM)](../acquiring-tokens/desktop-mobile/wam.md)** for Windows 10+ applications - provides the best security and user experience
> - **Use embedded browser flow** as described in [Using web browsers](../acquiring-tokens/using-web-browsers.md)

While ICustomWebUi allows desktop and mobile apps to use their own browser instead of the embedded / system browsers provided by MSAL, it should only be used for testing or legacy scenarios where migration is not yet possible.

Details [here](/dotnet/api/microsoft.identity.client.extensibility.icustomwebui?view=azure-dotnet)