Skip to content

Commit

Permalink
Documentation updates (#4188)
Browse files Browse the repository at this point in the history 
* Documentation updates

* Update PublicClientApplication.cs

* More documentation update

* Update documentation

* Update HREF

* Update with proper doc inheritance

* Add clarifications
  • Loading branch information
@localden
localden committed Jul 3, 2023
1 parent f300c0b commit 47b5997
Show file tree
Hide file tree
Showing 2 changed files with 88 additions and 218 deletions.
158 changes: 73 additions & 85 deletions src/client/Microsoft.Identity.Client/IPublicClientApplication.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,132 +6,120 @@
using System.ComponentModel;
using System.Security;
using System.Threading.Tasks;
using static System.Net.WebRequestMethods;

namespace Microsoft.Identity.Client
{
/// <summary>
/// Interface to be used with desktop or mobile applications (Desktop / UWP / Xamarin.iOS / Xamarin.Android).
/// public client applications are not trusted to safely keep application secrets, and therefore they only access web APIs in the name of the user only.
/// For details see https://aka.ms/msal-net-client-applications.
/// Class used to acquire tokens in desktop and mobile applications. Public client applications are not trusted to safely keep application secrets and therefore they can only access web APIs in the name of the authenticating user.
/// For more details on differences between public and confidential clients, refer to <see href="https://aka.ms/msal-net-client-applications">our documentation</see>.
/// </summary>
/// <remarks>
/// <para>
/// Unlike <see cref="Microsoft.Identity.Client.IConfidentialClientApplication"/>, public clients are unable to securely store secrets on a client device and as a result do not require the use of a client secret.
/// </para>
/// <para>
/// The redirect URI needed for interactive authentication is automatically determined by the library. It does not need to be passed explicitly in the constructor. Depending
/// on the authentication strategy (e.g., through the <see href="https://learn.microsoft.com/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam?view=msal-dotnet-latest">Web Account Manager</see>, the Authenticator app, web browser, etc.), different redirect URIs will be used by MSAL. Redirect URIs must always be configured for the application in the Azure Portal.
/// </para>
/// </remarks>
public partial interface IPublicClientApplication : IClientApplicationBase
{
/// <summary>
/// Tells if the application can use the system web browser, therefore getting single-sign-on with web applications.
/// Tells if the application can use the system web browser, therefore enabling single-sign-on with web applications.
/// By default, MSAL will try to use a system browser on the mobile platforms, if it is available.
/// See https://aka.ms/msal-net-uses-web-browser.
/// See <see href="https://aka.ms/msal-net-uses-web-browser">our documentation</see> for more details.
/// </summary>
/// <remarks>
/// On Windows, macOS, and Linux a system browser can always be used, except in cases where there is no UI (e.g., a SSH session).
/// On Android, the browser must support tabs.
/// </remarks>
/// <returns>Returns <c>true</c> if MSAL can use the system web browser.</returns>
bool IsSystemWebViewAvailable { get; }

#pragma warning disable CS1574 // XML comment has cref attribute that could not be resolved
/// <summary>
/// Interactive request to acquire a token for the specified scopes. The interactive window will be parented to the specified
/// window. The user will be required to select an account
/// Interactive request to acquire a token for the specified scopes. The interactive window will be parented to an application
/// window specified through a handle. The user will be required to select an account.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>The user will be signed-in interactively if needed,
/// and will consent to scopes and do multi-factor authentication if such a policy was enabled in the Azure AD tenant.
/// <param name="scopes">Scopes requested to access a protected API.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request.</returns>
/// <remarks>The user will be signed-in interactively and will consent to scopes, as well as perform a multi-factor authentication step if such a policy was enabled in the Azure AD tenant.
///
/// You can also pass optional parameters by calling:
/// <list type="table">
/// <item>
/// <term><see cref="AcquireTokenInteractiveParameterBuilder.WithPrompt(Prompt)"/> </term>
/// <description>to specify the user experience
/// when signing-in</description>
/// </item>
/// <item>
/// <term><see cref="AcquireTokenInteractiveParameterBuilder.WithUseEmbeddedWebView(bool)"/></term>
/// <description>to specify
/// if you want to use the embedded web browser or the system default browser</description>
/// </item>
/// <item>
/// <term><see cref="AcquireTokenInteractiveParameterBuilder.WithSystemWebViewOptions(SystemWebViewOptions)"/></term>
/// <description>to configure
/// the user experience when using the Default browser</description>
/// </item>
/// <item>
/// <term><see cref="AcquireTokenInteractiveParameterBuilder.WithAccount(IAccount)"/> or <see cref="AcquireTokenInteractiveParameterBuilder.WithLoginHint(string)"/></term>
/// <description>to prevent the select account dialog from appearing in the case you want to sign-in a specific accounts</description>
/// </item>
/// <item>
/// <term><see cref="AcquireTokenInteractiveParameterBuilder.WithExtraScopesToConsent(IEnumerable{string})"/></term>
/// <description>if you want to let the
/// user pre-consent to additional scopes (which won't be returned in the access token)</description>
/// </item>
/// <item>
/// <term><see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/></term>
/// <description>to pass
/// additional query parameters to the Identity Provider, and <see cref="AbstractAcquireTokenParameterBuilder{T}.WithTenantId(string)"/>
/// in order to change the tenant of the authority set at the application construction. </description>
/// </item>
/// <list type="bullet">
/// <item><description><see cref="AcquireTokenInteractiveParameterBuilder.WithPrompt(Prompt)"/> to specify the user experience when signing-in.</description></item>
/// <item><description><see cref="AcquireTokenInteractiveParameterBuilder.WithUseEmbeddedWebView(bool)"/> to specify if you want to use the embedded web browser or the default system browser.</description></item>
/// <item><description><see cref="AcquireTokenInteractiveParameterBuilder.WithSystemWebViewOptions(SystemWebViewOptions)"/> to configure the user experience when using the default system browser.</description></item>
/// <item><description><see cref="AcquireTokenInteractiveParameterBuilder.WithAccount(IAccount)"/> or <see cref="AcquireTokenInteractiveParameterBuilder.WithLoginHint(string)"/> to prevent the account selection dialog from appearing if you want to sign-in a specific account.</description></item>
/// <item><description><see cref="AcquireTokenInteractiveParameterBuilder.WithExtraScopesToConsent(IEnumerable{string})"/> if you want to let the user pre-consent to additional scopes (which won't be returned in the access token).</description></item>
/// <item><description><see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to pass additional query parameters to the authentication service.</description></item>
/// <item><description>One of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/> to override the default authority set at the application construction. Note that the overriding authority needs to be part of the known authorities added to the application constructor.</description></item>
/// </list>
/// </remarks>
AcquireTokenInteractiveParameterBuilder AcquireTokenInteractive(IEnumerable<string> scopes);
#pragma warning restore CS1574 // XML comment has cref attribute that could not be resolved

/// <summary>
/// Acquires a security token on a device without a Web browser, by letting the user authenticate on
/// another device. This is done in two steps:
/// <list type="bullet">
/// <item><description>The method first acquires a device code from the authority and returns it to the caller via
/// the <paramref name="deviceCodeResultCallback"/>. This callback takes care of interacting with the user
/// to direct them to authenticate (to a specific URL, with a code)</description></item>
/// <item><description>The method then proceeds to poll for the security
/// token which is granted upon successful login by the user based on the device code information</description></item>
/// </list>
/// See https://aka.ms/msal-device-code-flow.
/// Acquires a security token on a device without a web browser, by letting the user authenticate on
/// another device.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="deviceCodeResultCallback">Callback containing information to show the user about how to authenticate and enter the device code.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>
/// You can also pass optional parameters by calling:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to pass
/// additional query parameters to the Identity Provider, and <see cref="AbstractAcquireTokenParameterBuilder{T}.WithTenantId(string)"/>
/// in order to change the tenant of the authority set at the application construction.
/// The token acquisition is done in two steps:
/// <list type="bullet">
/// <item><description>The method first acquires a device code from the authority and returns it to the caller via
/// the <paramref name="deviceCodeResultCallback"/>. This callback takes care of interacting with the user
/// to direct them to authenticate (i.e., to a specific URL, with a code)</description></item>
/// <item><description>The method then proceeds to poll for the security
/// token which is granted upon successful login by the user based on the device code information.</description></item>
/// </list>
/// See <see href="https://aka.ms/msal-device-code-flow">our documentation</see> for additional context.
/// You can also pass optional parameters by calling <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>
/// and one of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>
/// in order to override the default authority. Note that the overriding authority needs to be part
/// of the known authorities added to the application constructor.
/// </remarks>
AcquireTokenWithDeviceCodeParameterBuilder AcquireTokenWithDeviceCode(
IEnumerable<string> scopes,
Func<DeviceCodeResult, Task> deviceCodeResultCallback);

/// <summary>
/// Non-interactive request to acquire a security token for the signed-in user in Windows,
/// via Integrated Windows Authentication. See https://aka.ms/msal-net-iwa.
/// via Integrated Windows Authentication.
/// The account used in this overrides is pulled from the operating system as the current user principal name.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>
/// You can also pass optional parameters by calling:
/// <see cref="AcquireTokenByIntegratedWindowsAuthParameterBuilder.WithUsername(string)"/> to pass the identifier
/// of the user account for which to acquire a token with Integrated Windows authentication. This is generally in
/// UserPrincipalName (UPN) format, e.g. john.doe@contoso.com. This is normally not needed, but some Windows administrators
/// set policies preventing applications from looking-up the signed-in user in Windows, and in that case the username
/// needs to be passed.
/// You can also chain with
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to pass
/// additional query parameters to the STS, and one of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>
/// in order to override the default authority set at the application construction. Note that the overriding authority needs to be part
/// of the known authorities added to the application construction.
/// See <see href="https://aka.ms/msal-net-iwa">our documentation</see> for more details.
/// You can pass optional parameters by calling <see cref="AcquireTokenByIntegratedWindowsAuthParameterBuilder.WithUsername(string)"/> to pass the identifier
/// of the user account for which to acquire a token with Integrated Windows Authentication. This is generally in
/// User Principal Name (UPN) format (e.g. john.doe@contoso.com). This is normally not needed, but some Windows administrators
/// set policies preventing applications from looking up the signed-in user and in that case the username needs to be passed.
/// You can also chain with <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to pass
/// additional query parameters to the authentication service, along with one of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>
/// in order to override the default authority. Note that the overriding authority needs to be part
/// of the known authorities added to the application constructor.
/// </remarks>
AcquireTokenByIntegratedWindowsAuthParameterBuilder AcquireTokenByIntegratedWindowsAuth(
IEnumerable<string> scopes);

/// <summary>
/// Non-interactive request to acquire a security token from the authority, via Username/Password Authentication.
/// Available only on .net desktop and .net core. See https://aka.ms/msal-net-up for details.
/// Non-interactive request to acquire a token via username and password authentication.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="username">Identifier of the user application requests token on behalf.
/// Generally in UserPrincipalName (UPN) format, e.g. <c>john.doe@contoso.com</c></param>
/// <param name="password">User password as a secure string.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>You can also pass optional parameters by chaining the builder with:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to pass
/// additional query parameters to the STS, and one of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>
/// in order to override the default authority set at the application construction. Note that the overriding authority needs to be part
/// of the known authorities added to the application construction.
/// .NET no longer recommends using SecureString and MSAL puts the plaintext value of the password on the wire, as required by the OAuth protocol. See <see href="https://docs.microsoft.com/en-us/dotnet/api/system.security.securestring?view=net-6.0#remarks">SecureString documentation</see>.
/// <remarks>
/// Available only for .NET Framework and .NET Core applications. See <see href="https://aka.ms/msal-net-up">our documentation</see> for details.
/// You can also pass optional parameters by chaining the builder with <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>
/// and one of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>
/// to override the default authority. Note that the overriding authority needs to be part
/// of the known authorities added to the application constructor.
/// .NET no longer recommends using SecureString and MSAL puts the plaintext value of the password on the wire, as required by the OAuth protocol. See <see href="https://docs.microsoft.com/dotnet/api/system.security.securestring?view=net-6.0#remarks">SecureString documentation</see> for details.
/// </remarks>
[Obsolete("Using SecureString is not recommended. Use AcquireTokenByUsernamePassword(IEnumerable<string> scopes, string username, string password) instead.", false)]
[EditorBrowsable(EditorBrowsableState.Never)]
Expand All @@ -141,19 +129,19 @@ AcquireTokenByUsernamePasswordParameterBuilder AcquireTokenByUsernamePassword(
SecureString password);

/// <summary>
/// Non-interactive request to acquire a security token from the authority, via Username/Password Authentication.
/// Available only on .NET desktop and .NET core. See https://aka.ms/msal-net-up for details.
/// Non-interactive request to acquire a token via username and password authentication.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="username">Identifier of the user application requests token on behalf.
/// Generally in UserPrincipalName (UPN) format, e.g. <c>john.doe@contoso.com</c></param>
/// <param name="password">User password as a string.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>You can also pass optional parameters by chaining the builder with:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to pass
/// additional query parameters to the Azure AD, and one of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>
/// in order to override the default authority set at the application construction. Note that the overriding authority needs to be part
/// of the known authorities added to the application construction.
/// <remarks>
/// Available only for .NET Framework and .NET Core applications. See <see href="https://aka.ms/msal-net-up">our documentation</see> for details.
/// You can also pass optional parameters by chaining the builder with <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>
/// and one of the overrides of <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>
/// to override the default authority. Note that the overriding authority needs to be part
/// of the known authorities added to the application constructor.
/// </remarks>
AcquireTokenByUsernamePasswordParameterBuilder AcquireTokenByUsernamePassword(
IEnumerable<string> scopes,
Expand Down
Loading

0 comments on commit 47b5997

Please sign in to comment.