/// <summary>
/// Acquires a token from the authority configured in the app, for the confidential client itself (in the name of no user)
/// using the client credentials flow. See https://aka.ms/msal-net-client-credentials.
/// </summary>
/// <param name="scopes">scopes requested to access a protected API. For this flow (client credentials), the scopes
/// should be of the form "{ResourceIdUri/.default}" for instance <c>https://management.azure.net/.default</c> or, for Microsoft
/// Graph, <c>https://graph.microsoft.com/.default</c> as the requested scopes are defined statically with the application registration
/// in the portal, and cannot be overriden in the application.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>You can also chain the following optional parameters:
/// <see cref="AcquireTokenForClientParameterBuilder.WithForceRefresh(bool)"/>
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>
/// </remarks>
public AcquireTokenForClientParameterBuilder AcquireTokenForClient(
IEnumerable <string> scopes)
{
return(AcquireTokenForClientParameterBuilder.Create(
ClientExecutorFactory.CreateConfidentialClientExecutor(this),
scopes));
}
/// <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}.WithAuthority(string, bool)"/> or one of its
/// overrides 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>
public AcquireTokenSilentParameterBuilder AcquireTokenSilent(IEnumerable <string> scopes, IAccount account)
{
return(AcquireTokenSilentParameterBuilder.Create(
ClientExecutorFactory.CreateClientApplicationBaseExecutor(this),
scopes,
account));
}
/// <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. /// 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. [email protected]. 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. /// </remarks> public AcquireTokenByIntegratedWindowsAuthParameterBuilder AcquireTokenByIntegratedWindowsAuth( IEnumerable <string> scopes) { return(AcquireTokenByIntegratedWindowsAuthParameterBuilder.Create( ClientExecutorFactory.CreatePublicClientExecutor(this), scopes)); }
/// <summary>
/// Computes the URL of the authorization request letting the user sign-in and consent to the application accessing specific scopes in
/// the user's name. The URL targets the /authorize endpoint of the authority configured in the application.
/// This override enables you to specify a login hint and extra query parameter.
/// </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 to get the
/// URL of the STS authorization endpoint parametrized with the parameters</returns>
/// <remarks>You can also chain the following optional parameters:
/// <see cref="GetAuthorizationRequestUrlParameterBuilder.WithRedirectUri(string)"/>
/// <see cref="GetAuthorizationRequestUrlParameterBuilder.WithLoginHint(string)"/>
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>
/// <see cref="GetAuthorizationRequestUrlParameterBuilder.WithExtraScopesToConsent(IEnumerable{string})"/>
/// </remarks>
public GetAuthorizationRequestUrlParameterBuilder GetAuthorizationRequestUrl(
IEnumerable <string> scopes)
{
return(GetAuthorizationRequestUrlParameterBuilder.Create(
ClientExecutorFactory.CreateConfidentialClientExecutor(this),
scopes));
}
public AcquireTokenInteractiveParameterBuilder AcquireTokenInteractive(
IEnumerable <string> scopes)
{
return(AcquireTokenInteractiveParameterBuilder
.Create(ClientExecutorFactory.CreatePublicClientExecutor(this), scopes)
.WithParentActivityOrWindowFunc(ServiceBundle.Config.ParentActivityOrWindowFunc));
}
/// <summary>
/// Acquires a security token from the authority configured in the app using the authorization code
/// previously received from the STS.
/// It uses the OAuth 2.0 authorization code flow (See https://aka.ms/msal-net-authorization-code).
/// It's usually used in web apps (for instance ASP.NET / ASP.NET Core web apps) which sign-in users,
/// and can request an authorization code.
/// This method does not lookup the token cache, but stores the result in it, so it can be looked up
/// using other methods such as <see cref="IClientApplicationBase.AcquireTokenSilent(IEnumerable{string}, IAccount)"/>.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="authorizationCode">The authorization code received from the service authorization endpoint.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>You can set optional parameters by chaining the builder with:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithAuthority(string, bool)"/>,
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>,
/// </remarks>
public AcquireTokenByAuthorizationCodeParameterBuilder AcquireTokenByAuthorizationCode(
IEnumerable <string> scopes,
string authorizationCode)
{
return(AcquireTokenByAuthorizationCodeParameterBuilder.Create(
ClientExecutorFactory.CreateConfidentialClientExecutor(this),
scopes,
authorizationCode));
}
AcquireTokenByRefreshTokenParameterBuilder IByRefreshToken.AcquireTokenByRefreshToken(
IEnumerable <string> scopes,
string refreshToken)
{
return(AcquireTokenByRefreshTokenParameterBuilder.Create(
ClientExecutorFactory.CreateClientApplicationBaseExecutor(this),
scopes,
refreshToken));
}
/// <summary>
/// Acquires an access token for this application (usually a Web API) from the authority configured in the application,
/// in order to access another downstream protected Web API on behalf of a user using the OAuth 2.0 On-Behalf-Of flow.
/// See https://aka.ms/msal-net-on-behalf-of.
/// This confidential client application was itself called with a token which will be provided in the
/// <paramref name="userAssertion">userAssertion</paramref> parameter.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="userAssertion">Instance of <see cref="UserAssertion"/> containing credential information about
/// the user on behalf of whom to get a token.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>You can also chain the following optional parameters:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>
/// </remarks>
public AcquireTokenOnBehalfOfParameterBuilder AcquireTokenOnBehalfOf(
IEnumerable <string> scopes,
UserAssertion userAssertion)
{
return(AcquireTokenOnBehalfOfParameterBuilder.Create(
ClientExecutorFactory.CreateConfidentialClientExecutor(this),
scopes,
userAssertion));
}
#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.
/// </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 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.
/// </remarks>
public AcquireTokenWithDeviceCodeParameterBuilder AcquireTokenWithDeviceCode(
IEnumerable <string> scopes,
Func <DeviceCodeResult, Task> deviceCodeResultCallback)
{
return(AcquireTokenWithDeviceCodeParameterBuilder.Create(
ClientExecutorFactory.CreatePublicClientExecutor(this),
scopes,
deviceCodeResultCallback));
}
/// <summary> /// Non-interactive request to acquire a security token from the authority, via Username/Password Authentication. /// See https://aka.ms/msal-net-up for details. /// </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>[email protected]</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. /// </remarks> public AcquireTokenByUsernamePasswordParameterBuilder AcquireTokenByUsernamePassword( IEnumerable <string> scopes, string username, SecureString password) { return(AcquireTokenByUsernamePasswordParameterBuilder.Create( ClientExecutorFactory.CreatePublicClientExecutor(this), scopes, username, password)); }
/// <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}.WithAuthority(string, bool)"/> or one of its
/// overrides 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>
public AcquireTokenSilentParameterBuilder AcquireTokenSilent(IEnumerable <string> scopes, string loginHint)
{
if (string.IsNullOrWhiteSpace(loginHint))
{
throw new ArgumentNullException(nameof(loginHint));
}
return(AcquireTokenSilentParameterBuilder.Create(
ClientExecutorFactory.CreateClientApplicationBaseExecutor(this),
scopes,
loginHint));
}
/// <inheritdoc />
public AcquireTokenOnBehalfOfParameterBuilder AcquireTokenInLongRunningProcess(
IEnumerable <string> scopes,
string longRunningProcessSessionKey)
{
if (string.IsNullOrEmpty(longRunningProcessSessionKey))
{
throw new ArgumentNullException(nameof(longRunningProcessSessionKey));
}
return(AcquireTokenOnBehalfOfParameterBuilder.Create(
ClientExecutorFactory.CreateConfidentialClientExecutor(this),
scopes,
longRunningProcessSessionKey));
}
/// <summary>
/// Acquires an access token for this application (usually a Web API) from the authority configured in the application,
/// in order to access another downstream protected web API on behalf of a user using the OAuth 2.0 On-Behalf-Of flow.
/// See https://aka.ms/msal-net-on-behalf-of.
/// This confidential client application was itself called with a token which will be provided in the
/// <paramref name="userAssertion">userAssertion</paramref> parameter.
/// </summary>
/// <param name="scopes">Scopes requested to access a protected API</param>
/// <param name="userAssertion">Instance of <see cref="UserAssertion"/> containing credential information about
/// the user on behalf of whom to get a token.</param>
/// <returns>A builder enabling you to add optional parameters before executing the token request</returns>
/// <remarks>You can also chain the following optional parameters:
/// <see cref="AbstractAcquireTokenParameterBuilder{T}.WithExtraQueryParameters(Dictionary{string, string})"/>
/// </remarks>
public AcquireTokenOnBehalfOfParameterBuilder AcquireTokenOnBehalfOf(
IEnumerable <string> scopes,
UserAssertion userAssertion)
{
if (userAssertion == null)
{
ServiceBundle.ApplicationLogger.Error("User assertion for OBO request should not be null");
throw new MsalClientException(MsalError.UserAssertionNullError);
}
return(AcquireTokenOnBehalfOfParameterBuilder.Create(
ClientExecutorFactory.CreateConfidentialClientExecutor(this),
scopes,
userAssertion));
}
/// <inheritdoc />
public AcquireTokenOnBehalfOfParameterBuilder InitiateLongRunningProcessInWebApi(
IEnumerable <string> scopes,
string userToken,
ref string longRunningProcessSessionKey)
{
if (string.IsNullOrEmpty(userToken))
{
throw new ArgumentNullException(nameof(userToken));
}
UserAssertion userAssertion = new UserAssertion(userToken);
if (string.IsNullOrEmpty(longRunningProcessSessionKey))
{
longRunningProcessSessionKey = userAssertion.AssertionHash;
}
return(AcquireTokenOnBehalfOfParameterBuilder.Create(
ClientExecutorFactory.CreateConfidentialClientExecutor(this),
scopes,
userAssertion,
longRunningProcessSessionKey));
}
