diff --git a/src/Security/Authentication/Certificate/src/CertificateAuthenticationExtensions.cs b/src/Security/Authentication/Certificate/src/CertificateAuthenticationExtensions.cs index a1007108271a..fca00ee7eb1d 100644 --- a/src/Security/Authentication/Certificate/src/CertificateAuthenticationExtensions.cs +++ b/src/Security/Authentication/Certificate/src/CertificateAuthenticationExtensions.cs @@ -36,7 +36,7 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu /// /// /// The . - /// + /// The authentication scheme. /// The . public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder builder, string authenticationScheme) => builder.AddCertificate(authenticationScheme, configureOptions: null); @@ -50,7 +50,7 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu /// /// /// The . - /// + /// A delegate to configure . /// The . public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder builder, Action configureOptions) => builder.AddCertificate(CertificateAuthenticationDefaults.AuthenticationScheme, configureOptions); @@ -64,8 +64,8 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu /// /// /// The . - /// - /// + /// The authentication scheme. + /// A delegate to configure . /// The . public static AuthenticationBuilder AddCertificate( this AuthenticationBuilder builder, @@ -82,7 +82,7 @@ public static AuthenticationBuilder AddCertificate( /// /// /// The . - /// + /// A delegate to configure . /// The . public static AuthenticationBuilder AddCertificateCache( this AuthenticationBuilder builder, diff --git a/src/Security/Authentication/Facebook/src/FacebookDefaults.cs b/src/Security/Authentication/Facebook/src/FacebookDefaults.cs index bab049a7bf73..6e3b67b54c9b 100644 --- a/src/Security/Authentication/Facebook/src/FacebookDefaults.cs +++ b/src/Security/Authentication/Facebook/src/FacebookDefaults.cs @@ -3,17 +3,37 @@ namespace Microsoft.AspNetCore.Authentication.Facebook { + /// + /// Default values for the Facebook authentication handler. + /// public static class FacebookDefaults { + /// + /// The default scheme for Facebook authentication. The value is Facebook. + /// public const string AuthenticationScheme = "Facebook"; + /// + /// The default display name for Facebook authentication. Defaults to Facebook. + /// public static readonly string DisplayName = "Facebook"; - // https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow#login + /// + /// The default endpoint used to perform Facebook authentication. + /// + /// + /// For more details about this endpoint, see https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow#login. + /// public static readonly string AuthorizationEndpoint = "https://www.facebook.com/v8.0/dialog/oauth"; + /// + /// The OAuth endpoint used to retrieve access tokens. + /// public static readonly string TokenEndpoint = "https://graph.facebook.com/v8.0/oauth/access_token"; + /// + /// The Facebook Graph API endpoint that is used to gather additional user information. + /// public static readonly string UserInformationEndpoint = "https://graph.facebook.com/v8.0/me"; } } diff --git a/src/Security/Authentication/Facebook/src/FacebookExtensions.cs b/src/Security/Authentication/Facebook/src/FacebookExtensions.cs index 2273724a42ff..7af0077e23bc 100644 --- a/src/Security/Authentication/Facebook/src/FacebookExtensions.cs +++ b/src/Security/Authentication/Facebook/src/FacebookExtensions.cs @@ -7,17 +7,61 @@ namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods to configure Facebook OAuth authentication. + /// public static class FacebookAuthenticationOptionsExtensions { + /// + /// Adds Facebook OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Facebook authentication allows application users to sign in with their Facebook account. + /// + /// + /// The . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder) => builder.AddFacebook(FacebookDefaults.AuthenticationScheme, _ => { }); + /// + /// Adds Facebook OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Facebook authentication allows application users to sign in with their Facebook account. + /// + /// + /// The . + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder, Action configureOptions) => builder.AddFacebook(FacebookDefaults.AuthenticationScheme, configureOptions); + /// + /// Adds Facebook OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Facebook authentication allows application users to sign in with their Facebook account. + /// + /// + /// The . + /// The authentication scheme. + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder, string authenticationScheme, Action configureOptions) => builder.AddFacebook(authenticationScheme, FacebookDefaults.DisplayName, configureOptions); + /// + /// Adds Facebook OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Facebook authentication allows application users to sign in with their Facebook account. + /// + /// + /// The . + /// The authentication scheme. + /// A display name for the authentication handler. + /// A delegate to configure . public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action configureOptions) => builder.AddOAuth(authenticationScheme, displayName, configureOptions); } diff --git a/src/Security/Authentication/Facebook/src/FacebookHandler.cs b/src/Security/Authentication/Facebook/src/FacebookHandler.cs index 7fe350385e80..fe8c4a9d3fea 100644 --- a/src/Security/Authentication/Facebook/src/FacebookHandler.cs +++ b/src/Security/Authentication/Facebook/src/FacebookHandler.cs @@ -17,12 +17,20 @@ namespace Microsoft.AspNetCore.Authentication.Facebook { + /// + /// Authentication handler for Facebook's OAuth based authentication. + /// public class FacebookHandler : OAuthHandler { + /// + /// Initializes a new instance of . + /// + /// public FacebookHandler(IOptionsMonitor options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock) : base(options, logger, encoder, clock) { } + /// protected override async Task CreateTicketAsync(ClaimsIdentity identity, AuthenticationProperties properties, OAuthTokenResponse tokens) { var endpoint = QueryHelpers.AddQueryString(Options.UserInformationEndpoint, "access_token", tokens.AccessToken); @@ -64,6 +72,7 @@ private string GenerateAppSecretProof(string accessToken) } } + /// protected override string FormatScope(IEnumerable scopes) { // Facebook deviates from the OAuth spec here. They require comma separated instead of space separated. @@ -72,6 +81,7 @@ protected override string FormatScope(IEnumerable scopes) return string.Join(",", scopes); } + /// protected override string FormatScope() => base.FormatScope(); } diff --git a/src/Security/Authentication/Facebook/src/FacebookOptions.cs b/src/Security/Authentication/Facebook/src/FacebookOptions.cs index c2078a017bf2..5dc529e4ceda 100644 --- a/src/Security/Authentication/Facebook/src/FacebookOptions.cs +++ b/src/Security/Authentication/Facebook/src/FacebookOptions.cs @@ -3,9 +3,8 @@ using System; using System.Collections.Generic; -using System.Security.Claims; -using Microsoft.AspNetCore.Authentication; using System.Globalization; +using System.Security.Claims; using Microsoft.AspNetCore.Authentication.OAuth; using Microsoft.AspNetCore.Http; @@ -68,7 +67,7 @@ public override void Validate() // Facebook uses a non-standard term for this field. /// - /// Gets or sets the Facebook-assigned appId. + /// Gets or sets the Facebook-assigned App ID. /// public string AppId { @@ -87,15 +86,19 @@ public string AppSecret } /// - /// Gets or sets if the appsecret_proof should be generated and sent with Facebook API calls. - /// This is enabled by default. + /// Gets or sets if the appsecret_proof should be generated and sent with Facebook API calls. /// + /// See https://developers.facebook.com/docs/graph-api/securing-requests/#appsecret_proof for more details. + /// Defaults to . public bool SendAppSecretProof { get; set; } /// /// The list of fields to retrieve from the UserInformationEndpoint. /// https://developers.facebook.com/docs/graph-api/reference/user /// + /// + /// Defaults to include the following fields if none are specified: "name", "email", "first_name", and "last_name". + /// public ICollection Fields { get; } = new HashSet(); } } diff --git a/src/Security/Authentication/Facebook/src/Microsoft.AspNetCore.Authentication.Facebook.csproj b/src/Security/Authentication/Facebook/src/Microsoft.AspNetCore.Authentication.Facebook.csproj index 12e6e562b556..36f93e275b67 100644 --- a/src/Security/Authentication/Facebook/src/Microsoft.AspNetCore.Authentication.Facebook.csproj +++ b/src/Security/Authentication/Facebook/src/Microsoft.AspNetCore.Authentication.Facebook.csproj @@ -1,9 +1,9 @@ - + ASP.NET Core middleware that enables an application to support Facebook's OAuth 2.0 authentication workflow. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security diff --git a/src/Security/Authentication/Google/src/GoogleChallengeProperties.cs b/src/Security/Authentication/Google/src/GoogleChallengeProperties.cs index 714df4565522..a2cfaef1d03a 100644 --- a/src/Security/Authentication/Google/src/GoogleChallengeProperties.cs +++ b/src/Security/Authentication/Google/src/GoogleChallengeProperties.cs @@ -1,8 +1,11 @@ -using System.Collections.Generic; +using System.Collections.Generic; using Microsoft.AspNetCore.Authentication.OAuth; namespace Microsoft.AspNetCore.Authentication.Google { + /// + /// for a Google OAuth challenge. + /// public class GoogleChallengeProperties : OAuthChallengeProperties { /// @@ -30,13 +33,24 @@ public class GoogleChallengeProperties : OAuthChallengeProperties /// public static readonly string PromptParameterKey = "prompt"; + /// + /// Initializes a new instance of . + /// public GoogleChallengeProperties() { } + /// + /// Initializes a new instance of . + /// + /// public GoogleChallengeProperties(IDictionary items) : base(items) { } + /// + /// Initializes a new instance of . + /// + /// public GoogleChallengeProperties(IDictionary items, IDictionary parameters) : base(items, parameters) { } diff --git a/src/Security/Authentication/Google/src/GoogleDefaults.cs b/src/Security/Authentication/Google/src/GoogleDefaults.cs index 006abde8b396..5c2a29200e3e 100644 --- a/src/Security/Authentication/Google/src/GoogleDefaults.cs +++ b/src/Security/Authentication/Google/src/GoogleDefaults.cs @@ -10,16 +10,35 @@ namespace Microsoft.AspNetCore.Authentication.Google /// public static class GoogleDefaults { + /// + /// The default scheme for Google authentication. Defaults to Google. + /// public const string AuthenticationScheme = "Google"; + /// + /// The default display name for Google authentication. Defaults to Google. + /// public static readonly string DisplayName = "Google"; - // https://developers.google.com/identity/protocols/oauth2/web-server#httprest + /// + /// The default endpoint used to perform Google authentication. + /// + /// + /// For more details about this endpoint, see https://developers.google.com/identity/protocols/oauth2/web-server#httprest + /// public static readonly string AuthorizationEndpoint = "https://accounts.google.com/o/oauth2/v2/auth"; + /// + /// The OAuth endpoint used to exchange access tokens. + /// public static readonly string TokenEndpoint = "https://oauth2.googleapis.com/token"; - // https://developers.google.com/apis-explorer/#search/oauth2/oauth2/v2/ + /// + /// The Google endpoint that is used to gather additional user information. + /// + /// + /// For more details about this endpoint, see https://developers.google.com/apis-explorer/#search/oauth2/oauth2/v2/. + /// public static readonly string UserInformationEndpoint = "https://www.googleapis.com/oauth2/v2/userinfo"; } } diff --git a/src/Security/Authentication/Google/src/GoogleExtensions.cs b/src/Security/Authentication/Google/src/GoogleExtensions.cs index 95547014ca2e..655efa404075 100644 --- a/src/Security/Authentication/Google/src/GoogleExtensions.cs +++ b/src/Security/Authentication/Google/src/GoogleExtensions.cs @@ -7,17 +7,62 @@ namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods to configure Google OAuth authentication. + /// public static class GoogleExtensions { + /// + /// Adds Google OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Google authentication allows application users to sign in with their Google account. + /// + /// + /// The . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder) => builder.AddGoogle(GoogleDefaults.AuthenticationScheme, _ => { }); + /// + /// Adds Google OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Google authentication allows application users to sign in with their Google account. + /// + /// + /// The . + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder, Action configureOptions) => builder.AddGoogle(GoogleDefaults.AuthenticationScheme, configureOptions); + /// + /// Adds Google OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Google authentication allows application users to sign in with their Google account. + /// + /// + /// The . + /// The authentication scheme. + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder, string authenticationScheme, Action configureOptions) => builder.AddGoogle(authenticationScheme, GoogleDefaults.DisplayName, configureOptions); + /// + /// Adds Google OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Google authentication allows application users to sign in with their Google account. + /// + /// + /// The . + /// The authentication scheme. + /// A display name for the authentication handler. + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action configureOptions) => builder.AddOAuth(authenticationScheme, displayName, configureOptions); } diff --git a/src/Security/Authentication/Google/src/GoogleHandler.cs b/src/Security/Authentication/Google/src/GoogleHandler.cs index 84f713f4404a..6c703609599b 100644 --- a/src/Security/Authentication/Google/src/GoogleHandler.cs +++ b/src/Security/Authentication/Google/src/GoogleHandler.cs @@ -16,12 +16,20 @@ namespace Microsoft.AspNetCore.Authentication.Google { + /// + /// Authentication handler for Google's OAuth based authentication. + /// public class GoogleHandler : OAuthHandler { + /// + /// Initializes a new instance of . + /// + /// public GoogleHandler(IOptionsMonitor options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock) : base(options, logger, encoder, clock) { } + /// protected override async Task CreateTicketAsync( ClaimsIdentity identity, AuthenticationProperties properties, @@ -46,7 +54,7 @@ protected override async Task CreateTicketAsync( } } - // TODO: Abstract this properties override pattern into the base class? + /// protected override string BuildChallengeUrl(AuthenticationProperties properties, string redirectUri) { // Google Identity Platform Manual: diff --git a/src/Security/Authentication/Google/src/GoogleOptions.cs b/src/Security/Authentication/Google/src/GoogleOptions.cs index 9d08bfc56a87..5c8937d383db 100644 --- a/src/Security/Authentication/Google/src/GoogleOptions.cs +++ b/src/Security/Authentication/Google/src/GoogleOptions.cs @@ -34,7 +34,11 @@ public GoogleOptions() } /// - /// access_type. Set to 'offline' to request a refresh token. + /// Indicates whether your application can refresh access tokens when the user is not present at the browser. + /// Valid values are online, which is the default value, and offline. + /// + /// Set the value to offline if your application needs to refresh access tokens when the user is not present at the browser. + /// /// public string AccessType { get; set; } } diff --git a/src/Security/Authentication/Google/src/Microsoft.AspNetCore.Authentication.Google.csproj b/src/Security/Authentication/Google/src/Microsoft.AspNetCore.Authentication.Google.csproj index cfbc074c0e3a..0dba04e82bc4 100644 --- a/src/Security/Authentication/Google/src/Microsoft.AspNetCore.Authentication.Google.csproj +++ b/src/Security/Authentication/Google/src/Microsoft.AspNetCore.Authentication.Google.csproj @@ -1,9 +1,9 @@ - + ASP.NET Core contains middleware to support Google's OpenId and OAuth 2.0 authentication workflows. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security diff --git a/src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj b/src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj index 8b60e587d132..7cacb73ac213 100644 --- a/src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj +++ b/src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj @@ -3,7 +3,7 @@ ASP.NET Core middleware that enables an application to support the Microsoft Account authentication workflow. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security diff --git a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountDefaults.cs b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountDefaults.cs index 0421fa14b4ad..f89fb757c20e 100644 --- a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountDefaults.cs +++ b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountDefaults.cs @@ -3,17 +3,37 @@ namespace Microsoft.AspNetCore.Authentication.MicrosoftAccount { + /// + /// Default values for Microsoft account authentication + /// public static class MicrosoftAccountDefaults { + /// + /// The default scheme for Microsoft account authentication. Defaults to Microsoft. + /// public const string AuthenticationScheme = "Microsoft"; + /// + /// The default display name for Microsoft account authentication. Defaults to Microsoft. + /// public static readonly string DisplayName = "Microsoft"; - // https://developer.microsoft.com/en-us/graph/docs/concepts/auth_v2_user + /// + /// The default endpoint used to perform Microsoft account authentication. + /// + /// + /// For more details about this endpoint, see https://developer.microsoft.com/en-us/graph/docs/concepts/auth_v2_user + /// public static readonly string AuthorizationEndpoint = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"; + /// + /// The OAuth endpoint used to exchange access tokens. + /// public static readonly string TokenEndpoint = "https://login.microsoftonline.com/common/oauth2/v2.0/token"; + /// + /// The Microsoft Graph API endpoint that is used to gather additional user information. + /// public static readonly string UserInformationEndpoint = "https://graph.microsoft.com/v1.0/me"; } } diff --git a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountExtensions.cs b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountExtensions.cs index 7f24e5af77a6..fc88468654e3 100644 --- a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountExtensions.cs +++ b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountExtensions.cs @@ -7,18 +7,63 @@ namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods to configure Microsoft Account OAuth authentication. + /// public static class MicrosoftAccountExtensions { + /// + /// Adds Microsoft Account OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Microsoft Account authentication allows application users to sign in with their work, school, or personal Microsoft account. + /// + /// + /// The . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddMicrosoftAccount(this AuthenticationBuilder builder) => builder.AddMicrosoftAccount(MicrosoftAccountDefaults.AuthenticationScheme, _ => { }); + /// + /// Adds Microsoft Account OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Microsoft Account authentication allows application users to sign in with their work, school, or personal Microsoft account. + /// + /// + /// The . + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddMicrosoftAccount(this AuthenticationBuilder builder, Action configureOptions) => builder.AddMicrosoftAccount(MicrosoftAccountDefaults.AuthenticationScheme, configureOptions); + /// + /// Adds Microsoft Account OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Microsoft Account authentication allows application users to sign in with their work, school, or personal Microsoft account. + /// + /// + /// The . + /// The authentication scheme. + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddMicrosoftAccount(this AuthenticationBuilder builder, string authenticationScheme, Action configureOptions) => builder.AddMicrosoftAccount(authenticationScheme, MicrosoftAccountDefaults.DisplayName, configureOptions); + /// + /// Adds Microsoft Account OAuth-based authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// Microsoft Account authentication allows application users to sign in with their work, school, or personal Microsoft account. + /// + /// + /// The . + /// The authentication scheme. + /// A display name for the authentication handler. + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddMicrosoftAccount(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action configureOptions) => builder.AddOAuth(authenticationScheme, displayName, configureOptions); } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountHandler.cs b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountHandler.cs index d16a8c1301f1..796a5750fd28 100644 --- a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountHandler.cs +++ b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftAccountHandler.cs @@ -18,12 +18,20 @@ namespace Microsoft.AspNetCore.Authentication.MicrosoftAccount { + /// + /// Authentication handler for Microsoft Account based authentication. + /// public class MicrosoftAccountHandler : OAuthHandler { + /// + /// Initializes a new instance of . + /// + /// public MicrosoftAccountHandler(IOptionsMonitor options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock) : base(options, logger, encoder, clock) { } + /// protected override async Task CreateTicketAsync(ClaimsIdentity identity, AuthenticationProperties properties, OAuthTokenResponse tokens) { var request = new HttpRequestMessage(HttpMethod.Get, Options.UserInformationEndpoint); @@ -44,6 +52,7 @@ protected override async Task CreateTicketAsync(ClaimsIden } } + /// protected override string BuildChallengeUrl(AuthenticationProperties properties, string redirectUri) { var queryStrings = new Dictionary diff --git a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftChallengeProperties.cs b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftChallengeProperties.cs index 4e9737b50942..461beafb2063 100644 --- a/src/Security/Authentication/MicrosoftAccount/src/MicrosoftChallengeProperties.cs +++ b/src/Security/Authentication/MicrosoftAccount/src/MicrosoftChallengeProperties.cs @@ -4,6 +4,7 @@ namespace Microsoft.AspNetCore.Authentication.MicrosoftAccount { /// + /// for Microsoft OAuth challenge request. /// See https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code for reference /// public class MicrosoftChallengeProperties : OAuthChallengeProperties @@ -28,19 +29,31 @@ public class MicrosoftChallengeProperties : OAuthChallengeProperties /// public static readonly string PromptKey = "prompt"; + /// + /// Initializes a new instance for . + /// public MicrosoftChallengeProperties() { } + /// + /// Initializes a new instance for . + /// + /// public MicrosoftChallengeProperties(IDictionary items) : base(items) { } + /// + /// Initializes a new instance for . + /// + /// public MicrosoftChallengeProperties(IDictionary items, IDictionary parameters) : base(items, parameters) { } /// - /// The "response_mode" parameter value being used for a challenge request. + /// Gets or sets the value for the response_mode parameter used for a challenge request. The response mode specifies the method + /// that should be used to send the resulting token back to the app. Can be one of the following: query, fragment, form_post. /// public string ResponseMode { @@ -49,7 +62,11 @@ public string ResponseMode } /// - /// The "domain_hint" parameter value being used for a challenge request. + /// Gets or sets the value for the "domain_hint" parameter value being used for a challenge request. + /// + /// If included, authentication will skip the email-based discovery process that user goes through on the sign-in page, + /// leading to a slightly more streamlined user experience. + /// /// public string DomainHint { @@ -58,7 +75,10 @@ public string DomainHint } /// - /// The "login_hint" parameter value being used for a challenge request. + /// Gets or sets the value for the "login_hint" parameter value being used for a challenge request. + /// + /// Can be used to pre-fill the username/email address field of the sign-in page for the user, if their username is known ahead of time. + /// /// public string LoginHint { @@ -67,7 +87,10 @@ public string LoginHint } /// - /// The "prompt" parameter value being used for a challenge request. + /// Gets or sets the value for the "prompt" parameter value being used for a challenge request. + /// + /// Indicates the type of user interaction that is required. The only valid values at this time are login, none, and consent. + /// /// public string Prompt { diff --git a/src/Security/Authorization/Core/src/AssertionRequirement.cs b/src/Security/Authorization/Core/src/AssertionRequirement.cs index 0c31f5710540..b5fc210ab77c 100644 --- a/src/Security/Authorization/Core/src/AssertionRequirement.cs +++ b/src/Security/Authorization/Core/src/AssertionRequirement.cs @@ -57,6 +57,7 @@ public async Task HandleAsync(AuthorizationHandlerContext context) } } + /// public override string ToString() { return $"{nameof(Handler)} assertion should evaluate to true."; diff --git a/src/Security/Authorization/Core/src/AuthorizationPolicyBuilder.cs b/src/Security/Authorization/Core/src/AuthorizationPolicyBuilder.cs index ffcc339aae0a..8def57d1b22c 100644 --- a/src/Security/Authorization/Core/src/AuthorizationPolicyBuilder.cs +++ b/src/Security/Authorization/Core/src/AuthorizationPolicyBuilder.cs @@ -10,7 +10,7 @@ namespace Microsoft.AspNetCore.Authorization { /// - /// Used for building policies during application startup. + /// Used for building policies. /// public class AuthorizationPolicyBuilder { @@ -26,7 +26,7 @@ public AuthorizationPolicyBuilder(params string[] authenticationSchemes) /// /// Creates a new instance of . /// - /// The to build. + /// The to copy. public AuthorizationPolicyBuilder(AuthorizationPolicy policy) { Combine(policy); @@ -41,6 +41,9 @@ public AuthorizationPolicyBuilder(AuthorizationPolicy policy) /// /// Gets or sets a list authentication schemes the /// are evaluated against. + /// + /// When not specified, the requirements are evaluated against default schemes. + /// /// public IList AuthenticationSchemes { get; set; } = new List(); @@ -92,8 +95,8 @@ public AuthorizationPolicyBuilder Combine(AuthorizationPolicy policy) } /// - /// Adds a - /// to the current instance. + /// Adds a to the current instance which requires + /// that the current user has the specified claim and that the claim value must be one of the allowed values. /// /// The claim type required. /// Values the claim must process one or more of for evaluation to succeed. @@ -109,8 +112,8 @@ public AuthorizationPolicyBuilder RequireClaim(string claimType, params string[] } /// - /// Adds a - /// to the current instance. + /// Adds a to the current instance which requires + /// that the current user has the specified claim and that the claim value must be one of the allowed values. /// /// The claim type required. /// Values the claim must process one or more of for evaluation to succeed. @@ -127,8 +130,8 @@ public AuthorizationPolicyBuilder RequireClaim(string claimType, IEnumerable - /// Adds a - /// to the current instance. + /// Adds a to the current instance which requires + /// that the current user has the specified claim. /// /// The claim type required, with no restrictions on claim value. /// A reference to this instance after the operation has completed. @@ -144,8 +147,8 @@ public AuthorizationPolicyBuilder RequireClaim(string claimType) } /// - /// Adds a - /// to the current instance. + /// Adds a to the current instance which enforces that the current user + /// must have at least one of the specified roles. /// /// The allowed roles. /// A reference to this instance after the operation has completed. @@ -160,8 +163,8 @@ public AuthorizationPolicyBuilder RequireRole(params string[] roles) } /// - /// Adds a - /// to the current instance. + /// Adds a to the current instance which enforces that the current user + /// must have at least one of the specified roles. /// /// The allowed roles. /// A reference to this instance after the operation has completed. @@ -177,8 +180,7 @@ public AuthorizationPolicyBuilder RequireRole(IEnumerable roles) } /// - /// Adds a - /// to the current instance. + /// Adds a to the current instance which enforces that the current user matches the specified name. /// /// The user name the current user must possess. /// A reference to this instance after the operation has completed. @@ -194,7 +196,7 @@ public AuthorizationPolicyBuilder RequireUserName(string userName) } /// - /// Adds a to the current instance. + /// Adds to the current instance which enforces that the current user is authenticated. /// /// A reference to this instance after the operation has completed. public AuthorizationPolicyBuilder RequireAuthenticatedUser() diff --git a/src/Security/Authorization/Core/src/AuthorizationResult.cs b/src/Security/Authorization/Core/src/AuthorizationResult.cs index 416e74daec2c..453ca2e0bd10 100644 --- a/src/Security/Authorization/Core/src/AuthorizationResult.cs +++ b/src/Security/Authorization/Core/src/AuthorizationResult.cs @@ -2,7 +2,6 @@ // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Collections.Generic; -using System.Diagnostics.CodeAnalysis; using System.Security.Claims; namespace Microsoft.AspNetCore.Authorization @@ -30,8 +29,17 @@ private AuthorizationResult() { } /// A successful result. public static AuthorizationResult Success() => new AuthorizationResult { Succeeded = true }; + /// + /// Creates a failed authorization result. + /// + /// Contains information about why authorization failed. + /// The . public static AuthorizationResult Failed(AuthorizationFailure failure) => new AuthorizationResult { Failure = failure }; + /// + /// Creates a failed authorization result. + /// + /// The . public static AuthorizationResult Failed() => new AuthorizationResult { Failure = AuthorizationFailure.ExplicitFail() }; } diff --git a/src/Security/Authorization/Core/src/ClaimsAuthorizationRequirement.cs b/src/Security/Authorization/Core/src/ClaimsAuthorizationRequirement.cs index 9a898176bbd0..a1d603e2dd46 100644 --- a/src/Security/Authorization/Core/src/ClaimsAuthorizationRequirement.cs +++ b/src/Security/Authorization/Core/src/ClaimsAuthorizationRequirement.cs @@ -71,6 +71,7 @@ protected override Task HandleRequirementAsync(AuthorizationHandlerContext conte return Task.CompletedTask; } + /// public override string ToString() { var value = (AllowedValues == null || !AllowedValues.Any()) diff --git a/src/Security/Authorization/Core/src/DefaultAuthorizationHandlerProvider.cs b/src/Security/Authorization/Core/src/DefaultAuthorizationHandlerProvider.cs index d297d4cdc6f3..db6934b82d96 100644 --- a/src/Security/Authorization/Core/src/DefaultAuthorizationHandlerProvider.cs +++ b/src/Security/Authorization/Core/src/DefaultAuthorizationHandlerProvider.cs @@ -29,6 +29,7 @@ public DefaultAuthorizationHandlerProvider(IEnumerable ha _handlers = handlers; } + /// public Task> GetHandlersAsync(AuthorizationHandlerContext context) => Task.FromResult(_handlers); } diff --git a/src/Security/Authorization/Core/src/DenyAnonymousAuthorizationRequirement.cs b/src/Security/Authorization/Core/src/DenyAnonymousAuthorizationRequirement.cs index ccb896bbe118..0d0c22d5f9e6 100644 --- a/src/Security/Authorization/Core/src/DenyAnonymousAuthorizationRequirement.cs +++ b/src/Security/Authorization/Core/src/DenyAnonymousAuthorizationRequirement.cs @@ -30,6 +30,7 @@ protected override Task HandleRequirementAsync(AuthorizationHandlerContext conte return Task.CompletedTask; } + /// public override string ToString() { return $"{nameof(DenyAnonymousAuthorizationRequirement)}: Requires an authenticated user."; diff --git a/src/Security/Authorization/Core/src/Microsoft.AspNetCore.Authorization.csproj b/src/Security/Authorization/Core/src/Microsoft.AspNetCore.Authorization.csproj index 904fe35cf82d..8bb6f76bee48 100644 --- a/src/Security/Authorization/Core/src/Microsoft.AspNetCore.Authorization.csproj +++ b/src/Security/Authorization/Core/src/Microsoft.AspNetCore.Authorization.csproj @@ -8,7 +8,7 @@ Microsoft.AspNetCore.Authorization.AuthorizeAttribute $(DefaultNetFxTargetFramework);netstandard2.0;$(DefaultNetCoreTargetFramework) $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authorization enable diff --git a/src/Security/Authorization/Core/src/NameAuthorizationRequirement.cs b/src/Security/Authorization/Core/src/NameAuthorizationRequirement.cs index 36cee10aac63..4a6c930054cd 100644 --- a/src/Security/Authorization/Core/src/NameAuthorizationRequirement.cs +++ b/src/Security/Authorization/Core/src/NameAuthorizationRequirement.cs @@ -49,6 +49,7 @@ protected override Task HandleRequirementAsync(AuthorizationHandlerContext conte return Task.CompletedTask; } + /// public override string ToString() { return $"{nameof(NameAuthorizationRequirement)}:Requires a user identity with Name equal to {RequiredName}"; diff --git a/src/Security/Authorization/Core/src/OperationAuthorizationRequirement.cs b/src/Security/Authorization/Core/src/OperationAuthorizationRequirement.cs index 51cb29ed2004..0e0c4580a0f1 100644 --- a/src/Security/Authorization/Core/src/OperationAuthorizationRequirement.cs +++ b/src/Security/Authorization/Core/src/OperationAuthorizationRequirement.cs @@ -14,6 +14,7 @@ public class OperationAuthorizationRequirement : IAuthorizationRequirement /// public string Name { get; set; } = default!; + /// public override string ToString() { return $"{nameof(OperationAuthorizationRequirement)}:Name={Name}"; diff --git a/src/Security/Authorization/Core/src/RolesAuthorizationRequirement.cs b/src/Security/Authorization/Core/src/RolesAuthorizationRequirement.cs index e5a2251a146f..1626d0208985 100644 --- a/src/Security/Authorization/Core/src/RolesAuthorizationRequirement.cs +++ b/src/Security/Authorization/Core/src/RolesAuthorizationRequirement.cs @@ -64,6 +64,7 @@ protected override Task HandleRequirementAsync(AuthorizationHandlerContext conte return Task.CompletedTask; } + /// public override string ToString() { var roles = $"User.IsInRole must be true for one of the following roles: ({string.Join("|", AllowedRoles)})"; diff --git a/src/Security/Authorization/Policy/src/AuthorizationAppBuilderExtensions.cs b/src/Security/Authorization/Policy/src/AuthorizationAppBuilderExtensions.cs index 41cfcb96fb68..9a216975235f 100644 --- a/src/Security/Authorization/Policy/src/AuthorizationAppBuilderExtensions.cs +++ b/src/Security/Authorization/Policy/src/AuthorizationAppBuilderExtensions.cs @@ -15,9 +15,13 @@ public static class AuthorizationAppBuilderExtensions { /// /// Adds the to the specified , which enables authorization capabilities. + /// + /// When authorizing a resource that is routed using endpoint routing, this call must appear between the calls to + /// app.UseRouting() and app.UseEndpoints(...) for the middleware to function correctly. + /// /// /// The to add the middleware to. - /// A reference to this instance after the operation has completed. + /// A reference to after the operation has completed. public static IApplicationBuilder UseAuthorization(this IApplicationBuilder app) { if (app == null) diff --git a/src/Security/Authorization/Policy/src/AuthorizationEndpointConventionBuilderExtensions.cs b/src/Security/Authorization/Policy/src/AuthorizationEndpointConventionBuilderExtensions.cs index c526e32ee01e..43f46d0facec 100644 --- a/src/Security/Authorization/Policy/src/AuthorizationEndpointConventionBuilderExtensions.cs +++ b/src/Security/Authorization/Policy/src/AuthorizationEndpointConventionBuilderExtensions.cs @@ -13,7 +13,6 @@ namespace Microsoft.AspNetCore.Builder /// public static class AuthorizationEndpointConventionBuilderExtensions { - private static readonly IAllowAnonymous _allowAnonymousMetadata = new AllowAnonymousAttribute(); /// @@ -97,7 +96,6 @@ public static TBuilder AllowAnonymous(this TBuilder builder) where TBu return builder; } - private static void RequireAuthorizationCore(TBuilder builder, IEnumerable authorizeData) where TBuilder : IEndpointConventionBuilder { diff --git a/src/Security/Authorization/Policy/src/AuthorizationMiddleware.cs b/src/Security/Authorization/Policy/src/AuthorizationMiddleware.cs index d876781f96f8..0fddd96878f7 100644 --- a/src/Security/Authorization/Policy/src/AuthorizationMiddleware.cs +++ b/src/Security/Authorization/Policy/src/AuthorizationMiddleware.cs @@ -9,6 +9,9 @@ namespace Microsoft.AspNetCore.Authorization { + /// + /// A middleware that enables authorization capabilities. + /// public class AuthorizationMiddleware { // AppContext switch used to control whether HttpContext or endpoint is passed as a resource to AuthZ @@ -21,12 +24,21 @@ public class AuthorizationMiddleware private readonly RequestDelegate _next; private readonly IAuthorizationPolicyProvider _policyProvider; + /// + /// Initializes a new instance of . + /// + /// The next middleware in the application middleware pipeline. + /// The . public AuthorizationMiddleware(RequestDelegate next, IAuthorizationPolicyProvider policyProvider) { _next = next ?? throw new ArgumentNullException(nameof(next)); _policyProvider = policyProvider ?? throw new ArgumentNullException(nameof(policyProvider)); } + /// + /// Invokes the middleware performing authorization. + /// + /// The . public async Task Invoke(HttpContext context) { if (context == null) diff --git a/src/Security/Authorization/Policy/src/AuthorizationMiddlewareResultHandler.cs b/src/Security/Authorization/Policy/src/AuthorizationMiddlewareResultHandler.cs index 7c7d4592b416..f293670cfa4e 100644 --- a/src/Security/Authorization/Policy/src/AuthorizationMiddlewareResultHandler.cs +++ b/src/Security/Authorization/Policy/src/AuthorizationMiddlewareResultHandler.cs @@ -4,8 +4,12 @@ namespace Microsoft.AspNetCore.Authorization.Policy { + /// + /// Default implementation for . + /// public class AuthorizationMiddlewareResultHandler : IAuthorizationMiddlewareResultHandler { + /// public async Task HandleAsync(RequestDelegate next, HttpContext context, AuthorizationPolicy policy, PolicyAuthorizationResult authorizeResult) { if (authorizeResult.Challenged) diff --git a/src/Security/Authorization/Policy/src/IAuthorizationMiddlewareResultHandler.cs b/src/Security/Authorization/Policy/src/IAuthorizationMiddlewareResultHandler.cs index af07449df419..635ef6f0ec87 100644 --- a/src/Security/Authorization/Policy/src/IAuthorizationMiddlewareResultHandler.cs +++ b/src/Security/Authorization/Policy/src/IAuthorizationMiddlewareResultHandler.cs @@ -4,8 +4,20 @@ namespace Microsoft.AspNetCore.Authorization { + /// + /// Allow custom handling of authorization and handling of the authorization response. + /// public interface IAuthorizationMiddlewareResultHandler { + /// + /// Evaluates the authorization requirement and processes the authorization result. + /// + /// + /// The next middleware in the application pipeline. Implementations may not invoke this if the authorization did not succeed. + /// + /// The . + /// The for the resource. + /// The result of authorization. Task HandleAsync(RequestDelegate next, HttpContext context, AuthorizationPolicy policy, PolicyAuthorizationResult authorizeResult); } } diff --git a/src/Security/Authorization/Policy/src/Microsoft.AspNetCore.Authorization.Policy.csproj b/src/Security/Authorization/Policy/src/Microsoft.AspNetCore.Authorization.Policy.csproj index 17e646635bd7..4a8cfb19656f 100644 --- a/src/Security/Authorization/Policy/src/Microsoft.AspNetCore.Authorization.Policy.csproj +++ b/src/Security/Authorization/Policy/src/Microsoft.AspNetCore.Authorization.Policy.csproj @@ -4,7 +4,7 @@ ASP.NET Core authorization policy helper classes. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authorization false diff --git a/src/Security/Authorization/Policy/src/PolicyAuthorizationResult.cs b/src/Security/Authorization/Policy/src/PolicyAuthorizationResult.cs index c653be105f3b..6bd6bce86aba 100644 --- a/src/Security/Authorization/Policy/src/PolicyAuthorizationResult.cs +++ b/src/Security/Authorization/Policy/src/PolicyAuthorizationResult.cs @@ -3,6 +3,9 @@ namespace Microsoft.AspNetCore.Authorization.Policy { + /// + /// The result of . + /// public class PolicyAuthorizationResult { private PolicyAuthorizationResult() { } @@ -27,15 +30,32 @@ private PolicyAuthorizationResult() { } /// public AuthorizationFailure? AuthorizationFailure { get; private set; } + /// + ///Indicates that an unauthenticated user requested access to an endpoint that requires authentication. + /// + /// The . public static PolicyAuthorizationResult Challenge() => new PolicyAuthorizationResult { Challenged = true }; + /// + /// Indiciates that the access to a resource was forbidden. + /// + /// The . public static PolicyAuthorizationResult Forbid() => Forbid(null); + /// + /// Indiciates that the access to a resource was forbidden. + /// + /// Specifies the reason the authorization failed.s + /// The . public static PolicyAuthorizationResult Forbid(AuthorizationFailure? authorizationFailure) => new PolicyAuthorizationResult { Forbidden = true, AuthorizationFailure = authorizationFailure }; + /// + /// Indicates a successful authorization. + /// + /// The . public static PolicyAuthorizationResult Success() => new PolicyAuthorizationResult { Succeeded = true }; diff --git a/src/Security/Authorization/Policy/src/PolicyEvaluator.cs b/src/Security/Authorization/Policy/src/PolicyEvaluator.cs index 21f0c4e9f009..06da4e969cb0 100644 --- a/src/Security/Authorization/Policy/src/PolicyEvaluator.cs +++ b/src/Security/Authorization/Policy/src/PolicyEvaluator.cs @@ -10,6 +10,9 @@ namespace Microsoft.AspNetCore.Authorization.Policy { + /// + /// Default implementation for . + /// public class PolicyEvaluator : IPolicyEvaluator { private readonly IAuthorizationService _authorization; diff --git a/src/Security/Authorization/Policy/src/PolicyServiceCollectionExtensions.cs b/src/Security/Authorization/Policy/src/PolicyServiceCollectionExtensions.cs index f15413706862..f056bc890cea 100644 --- a/src/Security/Authorization/Policy/src/PolicyServiceCollectionExtensions.cs +++ b/src/Security/Authorization/Policy/src/PolicyServiceCollectionExtensions.cs @@ -14,7 +14,7 @@ namespace Microsoft.Extensions.DependencyInjection public static class PolicyServiceCollectionExtensions { /// - /// Adds the authorization policy evaluator service to the specified . + /// Adds the authorization policy evaluator service to the specified . /// /// The to add services to. /// The so that additional calls can be chained.