Skip to content

Commit

Permalink
Clarify method comments (#4436)
Browse files Browse the repository at this point in the history 
Add clarity to method comments.
  • Loading branch information
@pmaytak
pmaytak authored Dec 5, 2023
1 parent ac2f3ae commit 0eecb41
Show file tree
Hide file tree
Showing 10 changed files with 156 additions and 308 deletions.
8 changes: 6 additions & 2 deletions ...icrosoft.Identity.Client/ApiConfig/AcquireTokenByIntegratedWindowsAuthParameterBuilder.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,14 @@ internal static AcquireTokenByIntegratedWindowsAuthParameterBuilder Create(
/// <summary>
/// Specifies the username.
/// </summary>
/// <remarks>
/// Specifying the username explicitly 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.
/// </remarks>
/// <param name="username">Identifier of the user account for which to acquire a token with
/// Integrated Windows authentication. Generally in UserPrincipalName (UPN) format,
/// Integrated Windows Authentication. Generally in UserPrincipalName (UPN) format,
/// e.g. <c>[email protected]</c></param>
/// <returns>The builder to chain the .With methods</returns>
/// <returns>The builder to chain the .With methods.</returns>
public AcquireTokenByIntegratedWindowsAuthParameterBuilder WithUsername(string username)
{
Parameters.Username = username;
Expand Down
99 changes: 11 additions & 88 deletions src/client/Microsoft.Identity.Client/ClientApplicationBase.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
using Microsoft.Identity.Client.TelemetryCore.Internal.Events;
using Microsoft.Identity.Client.Utils;
using static Microsoft.Identity.Client.TelemetryCore.Internal.Events.ApiEvent;

namespace Microsoft.Identity.Client
{
/// <inheritdoc/>
Expand All @@ -27,31 +27,17 @@ public abstract partial class ClientApplicationBase : ApplicationBase, IClientAp
/// </summary>
public IAppConfig AppConfig => ServiceBundle.Config;

/// <summary>
/// User token cache. It holds access tokens, id tokens and refresh tokens for accounts. It's used
/// and updated silently if needed when calling <see cref="AcquireTokenSilent(IEnumerable{string}, IAccount)"/>
/// or one of the overrides of <see cref="AcquireTokenSilent(IEnumerable{string}, IAccount)"/>.
/// It is updated by each AcquireTokenXXX method, with the exception of <c>AcquireTokenForClient</c> which only uses the application
/// cache (see <c>IConfidentialClientApplication</c>).
/// </summary>
/// <remarks>On .NET Framework and .NET Core you can also customize the token cache serialization.
/// See https://aka.ms/msal-net-token-cache-serialization. This is taken care of by MSAL.NET on mobile platforms and on UWP.
/// It is recommended to use token cache serialization for web site and web api scenarios.
/// </remarks>
/// <inheritdoc/>
public ITokenCache UserTokenCache => UserTokenCacheInternal;

internal ITokenCacheInternal UserTokenCacheInternal { get; }

/// <summary>
/// Gets the URL of the authority, or security token service (STS) from which MSAL.NET will acquire security tokens
/// The return value of this property is either the value provided by the developer in the constructor of the application, or otherwise
/// the value of the <see cref="ApplicationBase.DefaultAuthority"/> static member (that is <c>https://login.microsoftonline.com/common/</c>)
/// </summary>
/// <inheritdoc/>
public string Authority => ServiceBundle.Config.Authority.AuthorityInfo.CanonicalAuthority?.ToString(); // Do not use in MSAL, use AuthorityInfo instead to avoid re-parsing

internal AuthorityInfo AuthorityInfo => ServiceBundle.Config.Authority.AuthorityInfo;

internal ClientApplicationBase(ApplicationConfiguration config) : base(config)
internal ClientApplicationBase(ApplicationConfiguration config) : base(config)
{
ICacheSerializationProvider defaultCacheSerialization = ServiceBundle.PlatformProxy.CreateTokenCacheBlobStorage();

Expand All @@ -66,9 +52,7 @@ internal ClientApplicationBase(ApplicationConfiguration config) : base(config)
}

#region Accounts
/// <summary>
/// Returns all the available <see cref="IAccount">accounts</see> in the user token cache for the application.
/// </summary>
/// <inheritdoc/>
public async Task<IEnumerable<IAccount>> GetAccountsAsync()
{
return await GetAccountsAsync(default(CancellationToken)).ConfigureAwait(false);
Expand All @@ -83,12 +67,7 @@ public async Task<IEnumerable<IAccount>> GetAccountsAsync(CancellationToken canc
return await GetAccountsInternalAsync(ApiIds.GetAccounts, null, cancellationToken).ConfigureAwait(false);
}

/// <summary>
/// Get the <see cref="IAccount"/> collection by its identifier among the accounts available in the token cache,
/// based on the user flow. This is for Azure AD B2C scenarios.
/// </summary>
/// <param name="userFlow">The identifier is the user flow being targeted by the specific B2C authority/>.
/// </param>
/// <inheritdoc/>
public async Task<IEnumerable<IAccount>> GetAccountsAsync(string userFlow)
{
return await GetAccountsAsync(userFlow, default(CancellationToken)).ConfigureAwait(false);
Expand Down Expand Up @@ -131,13 +110,7 @@ public async Task<IAccount> GetAccountAsync(string accountId, CancellationToken
return accounts.SingleOrDefault();
}

/// <summary>
/// Get the <see cref="IAccount"/> by its identifier among the accounts available in the token cache.
/// </summary>
/// <param name="accountId">Account identifier. The identifier is typically the
/// value of the <see cref="AccountId.Identifier"/> property of <see cref="AccountId"/>.
/// You typically get the account ID from an <see cref="IAccount"/> by using the <see cref="IAccount.HomeAccountId"/> property>
/// </param>
/// <inheritdoc/>
public async Task<IAccount> GetAccountAsync(string accountId)
{
if (!string.IsNullOrWhiteSpace(accountId))
Expand Down Expand Up @@ -273,7 +246,7 @@ private async Task<IEnumerable<IAccount>> GetAccountsFromBrokerAsync(
// Not all brokers return the accounts only for the given env
private async Task<IEnumerable<IAccount>> FilterBrokerAccountsByEnvAsync(IEnumerable<IAccount> brokerAccounts, CancellationToken cancellationToken)
{
ServiceBundle.ApplicationLogger.Verbose(()=>$"Filtering broker accounts by environment. Before filtering: " + brokerAccounts.Count());
ServiceBundle.ApplicationLogger.Verbose(() => $"Filtering broker accounts by environment. Before filtering: " + brokerAccounts.Count());

ISet<string> allEnvs = new HashSet<string>(
brokerAccounts.Select(aci => aci.Environment),
Expand All @@ -286,7 +259,7 @@ private async Task<IEnumerable<IAccount>> FilterBrokerAccountsByEnvAsync(IEnumer

brokerAccounts = brokerAccounts.Where(acc => instanceMetadata.Aliases.ContainsOrdinalIgnoreCase(acc.Environment));

ServiceBundle.ApplicationLogger.Verbose(()=>$"After filtering: " + brokerAccounts.Count());
ServiceBundle.ApplicationLogger.Verbose(() => $"After filtering: " + brokerAccounts.Count());

return brokerAccounts;
}
Expand Down Expand Up @@ -324,31 +297,7 @@ internal RequestContext CreateRequestContext(Guid correlationId, CancellationTok

#endregion

/// <summary>
/// [V3 API] Attempts to acquire an access token for the <paramref name="account"/> from the user token cache.
/// See https://aka.ms/msal-net-acquiretokensilent for more details
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="account">Account for which the token is requested.</param>
/// <returns>An <see cref="AcquireTokenSilentParameterBuilder"/> used to build the token request, adding optional
/// parameters</returns>
/// <exception cref="MsalUiRequiredException">will be thrown in the case where an interaction is required with the end user of the application,
/// for instance, if no refresh token was in the cache, or the user needs to consent, or re-sign-in (for instance if the password expired),
/// or the user needs to perform two factor authentication</exception>
/// <remarks>
/// The access token is considered a match if it contains <b>at least</b> all the requested scopes. This means that an access token with more scopes than
/// requested could be returned. If the access token is expired or close to expiration - within a 5 minute window -
/// then the cached refresh token (if available) is used to acquire a new access token by making a silent network call.
///
/// You can set additional parameters by chaining the builder with:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithTenantId(string)"/>
/// to request a token for a different authority than the one set at the application construction
/// <see cref="AcquireTokenSilentParameterBuilder.WithForceRefresh(bool)"/> to bypass the user token cache and
/// force refreshing the token, as well as
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to
/// specify extra query parameters
///
/// </remarks>
/// <inheritdoc/>
public AcquireTokenSilentParameterBuilder AcquireTokenSilent(IEnumerable<string> scopes, IAccount account)
{
return AcquireTokenSilentParameterBuilder.Create(
Expand All @@ -357,33 +306,7 @@ public AcquireTokenSilentParameterBuilder AcquireTokenSilent(IEnumerable<string>
account);
}

/// <summary>
/// [V3 API] Attempts to acquire an access token for the <see cref="IAccount"/>
/// having the <see cref="IAccount.Username" /> match the given <paramref name="loginHint"/>, from the user token cache.
/// See https://aka.ms/msal-net-acquiretokensilent for more details
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="loginHint">Typically the username, in UPN format, e.g. [email protected] </param>
/// <returns>An <see cref="AcquireTokenSilentParameterBuilder"/> used to build the token request, adding optional
/// parameters</returns>
/// <exception cref="MsalUiRequiredException">will be thrown in the case where an interaction is required with the end user of the application,
/// for instance, if no refresh token was in the cache, or the user needs to consent, or re-sign-in (for instance if the password expired),
/// or the user needs to perform two factor authentication</exception>
/// <remarks>
/// If multiple <see cref="IAccount"/> match the <paramref name="loginHint"/>, or if there are no matches, an exception is thrown.
///
/// The access token is considered a match if it contains <b>at least</b> all the requested scopes. This means that an access token with more scopes than
/// requested could be returned. If the access token is expired or close to expiration - within a 5 minute window -
/// then the cached refresh token (if available) is used to acquire a new access token by making a silent network call.
///
/// You can set additional parameters by chaining the builder with:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithTenantId(string)"/> to request a token for a different authority than the one set at the application construction
/// <see cref="AcquireTokenSilentParameterBuilder.WithForceRefresh(bool)"/> to bypass the user token cache and
/// force refreshing the token, as well as
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/> to
/// specify extra query parameters
///
/// </remarks>
/// <inheritdoc/>
public AcquireTokenSilentParameterBuilder AcquireTokenSilent(IEnumerable<string> scopes, string loginHint)
{
if (string.IsNullOrWhiteSpace(loginHint))
Expand Down
Loading

0 comments on commit 0eecb41

Please sign in to comment.