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 2184a59b2a81..8b60e587d132 100644 --- a/src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj +++ b/src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj @@ -1,4 +1,4 @@ - + ASP.NET Core middleware that enables an application to support the Microsoft Account authentication workflow. diff --git a/src/Security/Authentication/Negotiate/src/Events/AuthenticatedContext.cs b/src/Security/Authentication/Negotiate/src/Events/AuthenticatedContext.cs index fee54f3e8d68..838c87490bcb 100644 --- a/src/Security/Authentication/Negotiate/src/Events/AuthenticatedContext.cs +++ b/src/Security/Authentication/Negotiate/src/Events/AuthenticatedContext.cs @@ -13,9 +13,7 @@ public class AuthenticatedContext : ResultContext /// /// Creates a new . /// - /// - /// - /// + /// public AuthenticatedContext( HttpContext context, AuthenticationScheme scheme, diff --git a/src/Security/Authentication/Negotiate/src/Events/AuthenticationFailedContext.cs b/src/Security/Authentication/Negotiate/src/Events/AuthenticationFailedContext.cs index 4ea083c94db2..f5115c6e038f 100644 --- a/src/Security/Authentication/Negotiate/src/Events/AuthenticationFailedContext.cs +++ b/src/Security/Authentication/Negotiate/src/Events/AuthenticationFailedContext.cs @@ -14,9 +14,7 @@ public class AuthenticationFailedContext : RemoteAuthenticationContext /// Creates a . /// - /// - /// - /// + /// public AuthenticationFailedContext( HttpContext context, AuthenticationScheme scheme, diff --git a/src/Security/Authentication/Negotiate/src/Events/ChallengeContext.cs b/src/Security/Authentication/Negotiate/src/Events/ChallengeContext.cs index 23b6ab041de4..94f1742580bb 100644 --- a/src/Security/Authentication/Negotiate/src/Events/ChallengeContext.cs +++ b/src/Security/Authentication/Negotiate/src/Events/ChallengeContext.cs @@ -14,10 +14,7 @@ public class ChallengeContext : PropertiesContext /// /// Creates a new . /// - /// - /// - /// - /// + /// public ChallengeContext( HttpContext context, AuthenticationScheme scheme, @@ -26,7 +23,8 @@ public ChallengeContext( : base(context, scheme, options, properties) { } /// - /// If true, will skip any default logic for this challenge. + /// Gets a value that determines if this challenge was handled. + /// If , will skip any default logic for this challenge. /// public bool Handled { get; private set; } diff --git a/src/Security/Authentication/Negotiate/src/Events/LdapContext.cs b/src/Security/Authentication/Negotiate/src/Events/LdapContext.cs index 9e6d7a40ac82..08483d09d8fa 100644 --- a/src/Security/Authentication/Negotiate/src/Events/LdapContext.cs +++ b/src/Security/Authentication/Negotiate/src/Events/LdapContext.cs @@ -13,10 +13,7 @@ public class LdapContext : ResultContext /// /// Creates a new . /// - /// - /// - /// - /// + /// public LdapContext( HttpContext context, AuthenticationScheme scheme, diff --git a/src/Security/Authentication/Negotiate/src/LdapSettings.cs b/src/Security/Authentication/Negotiate/src/LdapSettings.cs index cdefe6f676e1..fd5728000551 100644 --- a/src/Security/Authentication/Negotiate/src/LdapSettings.cs +++ b/src/Security/Authentication/Negotiate/src/LdapSettings.cs @@ -76,6 +76,9 @@ public class LdapSettings internal MemoryCache ClaimsCache { get; set; } + /// + /// Validates the . + /// public void Validate() { if (EnableLdapClaimResolution) diff --git a/src/Security/Authentication/Negotiate/src/Microsoft.AspNetCore.Authentication.Negotiate.csproj b/src/Security/Authentication/Negotiate/src/Microsoft.AspNetCore.Authentication.Negotiate.csproj index c0aac839f5f7..3554529aff5f 100644 --- a/src/Security/Authentication/Negotiate/src/Microsoft.AspNetCore.Authentication.Negotiate.csproj +++ b/src/Security/Authentication/Negotiate/src/Microsoft.AspNetCore.Authentication.Negotiate.csproj @@ -3,6 +3,7 @@ ASP.NET Core authentication handler used to authenticate requests using Negotiate, Kerberos, or NTLM. $(DefaultNetCoreTargetFramework) + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security diff --git a/src/Security/Authentication/Negotiate/src/NegotiateExtensions.cs b/src/Security/Authentication/Negotiate/src/NegotiateExtensions.cs index e47417e17001..18d2aa5b412e 100644 --- a/src/Security/Authentication/Negotiate/src/NegotiateExtensions.cs +++ b/src/Security/Authentication/Negotiate/src/NegotiateExtensions.cs @@ -17,7 +17,11 @@ namespace Microsoft.Extensions.DependencyInjection public static class NegotiateExtensions { /// - /// Adds Negotiate authentication. + /// Configures the to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication + /// using the default scheme from . + /// + /// This authentication handler supports Kerberos on Windows and Linux servers. + /// /// /// The . /// The original builder. @@ -25,7 +29,11 @@ public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder buil => builder.AddNegotiate(NegotiateDefaults.AuthenticationScheme, _ => { }); /// - /// Adds and configures Negotiate authentication. + /// Configures the to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication + /// using the default scheme. The default scheme is specified by . + /// + /// This authentication handler supports Kerberos on Windows and Linux servers. + /// /// /// The . /// Allows for configuring the authentication handler. @@ -34,7 +42,11 @@ public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder buil => builder.AddNegotiate(NegotiateDefaults.AuthenticationScheme, configureOptions); /// - /// Adds and configures Negotiate authentication. + /// Configures the to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication + /// using the specified authentication scheme. + /// + /// This authentication handler supports Kerberos on Windows and Linux servers. + /// /// /// The . /// The scheme name used to identify the authentication handler internally. @@ -44,7 +56,11 @@ public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder buil => builder.AddNegotiate(authenticationScheme, displayName: null, configureOptions: configureOptions); /// - /// Adds and configures Negotiate authentication. + /// Configures the to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication + /// using the specified authentication scheme. + /// + /// This authentication handler supports Kerberos on Windows and Linux servers. + /// /// /// The . /// The scheme name used to identify the authentication handler internally. diff --git a/src/Security/Authentication/Negotiate/src/NegotiateHandler.cs b/src/Security/Authentication/Negotiate/src/NegotiateHandler.cs index 179a85ed0b91..8b54046ffc4b 100644 --- a/src/Security/Authentication/Negotiate/src/NegotiateHandler.cs +++ b/src/Security/Authentication/Negotiate/src/NegotiateHandler.cs @@ -34,10 +34,7 @@ public class NegotiateHandler : AuthenticationHandler, IAuthen /// /// Creates a new /// - /// - /// - /// - /// + /// public NegotiateHandler(IOptionsMonitor options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock) : base(options, logger, encoder, clock) { } @@ -63,7 +60,7 @@ public NegotiateHandler(IOptionsMonitor options, ILoggerFactor /// /// Intercepts incomplete Negotiate authentication handshakes and continues or completes them. /// - /// True if a response was generated, false otherwise. + /// if a response was generated, otherwise . public async Task HandleRequestAsync() { AuthPersistence persistence = null; diff --git a/src/Security/Authentication/Negotiate/src/NegotiateOptions.cs b/src/Security/Authentication/Negotiate/src/NegotiateOptions.cs index 40d090265c4b..ff0a0b3811e2 100644 --- a/src/Security/Authentication/Negotiate/src/NegotiateOptions.cs +++ b/src/Security/Authentication/Negotiate/src/NegotiateOptions.cs @@ -24,15 +24,15 @@ public class NegotiateOptions : AuthenticationSchemeOptions /// /// Indicates if Kerberos credentials should be persisted and re-used for subsquent anonymous requests. /// This option must not be used if connections may be shared by requests from different users. - /// The default is false. /// + /// Defaults to . public bool PersistKerberosCredentials { get; set; } = false; /// /// Indicates if NTLM credentials should be persisted and re-used for subsquent anonymous requests. /// This option must not be used if connections may be shared by requests from different users. - /// The default is true. /// + /// Defaults to . public bool PersistNtlmCredentials { get; set; } = true; /// diff --git a/src/Security/Authentication/OAuth/src/ClaimAction.cs b/src/Security/Authentication/OAuth/src/ClaimAction.cs index 8d324bc8413b..7aa33e204c82 100644 --- a/src/Security/Authentication/OAuth/src/ClaimAction.cs +++ b/src/Security/Authentication/OAuth/src/ClaimAction.cs @@ -23,11 +23,13 @@ public ClaimAction(string claimType, string valueType) } /// - /// The value to use for Claim.Type when creating a Claim. + /// Gets the value to use for when creating a Claim. /// public string ClaimType { get; } - // The value to use for Claim.ValueType when creating a Claim. + /// + /// Gets the value to use for when creating a Claim. + /// public string ValueType { get; } /// diff --git a/src/Security/Authentication/OAuth/src/ClaimActionCollection.cs b/src/Security/Authentication/OAuth/src/ClaimActionCollection.cs index 63da155d7c65..105f0d6fe00b 100644 --- a/src/Security/Authentication/OAuth/src/ClaimActionCollection.cs +++ b/src/Security/Authentication/OAuth/src/ClaimActionCollection.cs @@ -1,4 +1,4 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; @@ -39,6 +39,7 @@ public void Add(ClaimAction action) Actions.Add(action); } + /// public IEnumerator GetEnumerator() { return Actions.GetEnumerator(); @@ -49,4 +50,4 @@ IEnumerator IEnumerable.GetEnumerator() return Actions.GetEnumerator(); } } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OAuth/src/ClaimActionCollectionMapExtensions.cs b/src/Security/Authentication/OAuth/src/ClaimActionCollectionMapExtensions.cs index f123785691f1..57ce64a7cfe6 100644 --- a/src/Security/Authentication/OAuth/src/ClaimActionCollectionMapExtensions.cs +++ b/src/Security/Authentication/OAuth/src/ClaimActionCollectionMapExtensions.cs @@ -8,13 +8,16 @@ namespace Microsoft.AspNetCore.Authentication { + /// + /// Extension methods for . + /// public static class ClaimActionCollectionMapExtensions { /// /// Select a top level value from the json user data with the given key name and add it as a Claim. /// This no-ops if the key is not found or the value is empty. /// - /// + /// The . /// The value to use for Claim.Type when creating a Claim. /// The top level key to look for in the json user data. public static void MapJsonKey(this ClaimActionCollection collection, string claimType, string jsonKey) @@ -26,7 +29,7 @@ public static void MapJsonKey(this ClaimActionCollection collection, string clai /// Select a top level value from the json user data with the given key name and add it as a Claim. /// This no-ops if the key is not found or the value is empty. /// - /// + /// The . /// The value to use for Claim.Type when creating a Claim. /// The top level key to look for in the json user data. /// The value to use for Claim.ValueType when creating a Claim. @@ -39,7 +42,7 @@ public static void MapJsonKey(this ClaimActionCollection collection, string clai /// Select a second level value from the json user data with the given top level key name and second level sub key name and add it as a Claim. /// This no-ops if the keys are not found or the value is empty. /// - /// + /// The . /// The value to use for Claim.Type when creating a Claim. /// The top level key to look for in the json user data. /// The second level key to look for in the json user data. @@ -52,7 +55,7 @@ public static void MapJsonSubKey(this ClaimActionCollection collection, string c /// Select a second level value from the json user data with the given top level key name and second level sub key name and add it as a Claim. /// This no-ops if the keys are not found or the value is empty. /// - /// + /// The . /// The value to use for Claim.Type when creating a Claim. /// The top level key to look for in the json user data. /// The second level key to look for in the json user data. @@ -66,7 +69,7 @@ public static void MapJsonSubKey(this ClaimActionCollection collection, string c /// Run the given resolver to select a value from the json user data to add as a claim. /// This no-ops if the returned value is empty. /// - /// + /// The . /// The value to use for Claim.Type when creating a Claim. /// The Func that will be called to select value from the given json user data. public static void MapCustomJson(this ClaimActionCollection collection, string claimType, Func resolver) @@ -78,7 +81,7 @@ public static void MapCustomJson(this ClaimActionCollection collection, string c /// Run the given resolver to select a value from the json user data to add as a claim. /// This no-ops if the returned value is empty. /// - /// + /// The . /// The value to use for Claim.Type when creating a Claim. /// The value to use for Claim.ValueType when creating a Claim. /// The Func that will be called to select value from the given json user data. @@ -90,7 +93,7 @@ public static void MapCustomJson(this ClaimActionCollection collection, string c /// /// Clears any current ClaimsActions and maps all values from the json user data as claims, excluding duplicates. /// - /// + /// The . public static void MapAll(this ClaimActionCollection collection) { collection.Clear(); @@ -100,8 +103,8 @@ public static void MapAll(this ClaimActionCollection collection) /// /// Clears any current ClaimsActions and maps all values from the json user data as claims, excluding the specified types. /// - /// - /// + /// The . + /// The types to exclude. public static void MapAllExcept(this ClaimActionCollection collection, params string[] exclusions) { collection.MapAll(); @@ -111,8 +114,8 @@ public static void MapAllExcept(this ClaimActionCollection collection, params st /// /// Delete all claims from the given ClaimsIdentity with the given ClaimType. /// - /// - /// + /// The . + /// The claim type to delete public static void DeleteClaim(this ClaimActionCollection collection, string claimType) { collection.Add(new DeleteClaimAction(claimType)); @@ -121,8 +124,8 @@ public static void DeleteClaim(this ClaimActionCollection collection, string cla /// /// Delete all claims from the ClaimsIdentity with the given claimTypes. /// - /// - /// + /// The . + /// The claim types to delete. public static void DeleteClaims(this ClaimActionCollection collection, params string[] claimTypes) { if (claimTypes == null) diff --git a/src/Security/Authentication/OAuth/src/Events/OAuthCreatingTicketContext.cs b/src/Security/Authentication/OAuth/src/Events/OAuthCreatingTicketContext.cs index f534fac2f18c..6db92ad1246a 100644 --- a/src/Security/Authentication/OAuth/src/Events/OAuthCreatingTicketContext.cs +++ b/src/Security/Authentication/OAuth/src/Events/OAuthCreatingTicketContext.cs @@ -108,8 +108,16 @@ public TimeSpan? ExpiresIn /// public ClaimsIdentity Identity => Principal?.Identity as ClaimsIdentity; + /// + /// Examines , determine if the requisite data is present, and optionally add it + /// to . + /// public void RunClaimActions() => RunClaimActions(User); + /// + /// Examines the specified , determine if the requisite data is present, and optionally add it + /// to . + /// public void RunClaimActions(JsonElement userData) { foreach (var action in Options.ClaimActions) diff --git a/src/Security/Authentication/OAuth/src/MapAllClaimsAction.cs b/src/Security/Authentication/OAuth/src/MapAllClaimsAction.cs index 46c6f0cb7668..6454cb6931bc 100644 --- a/src/Security/Authentication/OAuth/src/MapAllClaimsAction.cs +++ b/src/Security/Authentication/OAuth/src/MapAllClaimsAction.cs @@ -13,10 +13,14 @@ namespace Microsoft.AspNetCore.Authentication.OAuth.Claims /// public class MapAllClaimsAction : ClaimAction { + /// + /// Initializes a new instance of . + /// public MapAllClaimsAction() : base("All", ClaimValueTypes.String) { } + /// public override void Run(JsonElement userData, ClaimsIdentity identity, string issuer) { foreach (var pair in userData.EnumerateObject()) diff --git a/src/Security/Authentication/OAuth/src/Microsoft.AspNetCore.Authentication.OAuth.csproj b/src/Security/Authentication/OAuth/src/Microsoft.AspNetCore.Authentication.OAuth.csproj index d7855aec1a5b..7b35cfaef5a2 100644 --- a/src/Security/Authentication/OAuth/src/Microsoft.AspNetCore.Authentication.OAuth.csproj +++ b/src/Security/Authentication/OAuth/src/Microsoft.AspNetCore.Authentication.OAuth.csproj @@ -4,7 +4,7 @@ ASP.NET Core middleware that enables an application to support any standard OAuth 2.0 authentication workflow. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security false diff --git a/src/Security/Authentication/OAuth/src/OAuthChallengeProperties.cs b/src/Security/Authentication/OAuth/src/OAuthChallengeProperties.cs index fc768a8ac8f8..2a9905e33097 100644 --- a/src/Security/Authentication/OAuth/src/OAuthChallengeProperties.cs +++ b/src/Security/Authentication/OAuth/src/OAuthChallengeProperties.cs @@ -1,7 +1,10 @@ -using System.Collections.Generic; +using System.Collections.Generic; namespace Microsoft.AspNetCore.Authentication.OAuth { + /// + /// for an OAuth challenge. + /// public class OAuthChallengeProperties : AuthenticationProperties { /// @@ -9,13 +12,24 @@ public class OAuthChallengeProperties : AuthenticationProperties /// public static readonly string ScopeKey = "scope"; + /// + /// Initializes a new instance of . + /// public OAuthChallengeProperties() { } + /// + /// Initializes a new instance of . + /// + /// public OAuthChallengeProperties(IDictionary items) : base(items) { } + /// + /// Initializes a new instance of . + /// + /// public OAuthChallengeProperties(IDictionary items, IDictionary parameters) : base(items, parameters) { } diff --git a/src/Security/Authentication/OAuth/src/OAuthDefaults.cs b/src/Security/Authentication/OAuth/src/OAuthDefaults.cs index 376f8ab01a25..75c70b1c527f 100644 --- a/src/Security/Authentication/OAuth/src/OAuthDefaults.cs +++ b/src/Security/Authentication/OAuth/src/OAuthDefaults.cs @@ -1,10 +1,16 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. namespace Microsoft.AspNetCore.Authentication.OAuth { + /// + /// Defaults for OAuth authentication. + /// public static class OAuthDefaults { + /// + /// The default display name for OAuth authentication. + /// public static readonly string DisplayName = "OAuth"; } } diff --git a/src/Security/Authentication/OAuth/src/OAuthExtensions.cs b/src/Security/Authentication/OAuth/src/OAuthExtensions.cs index aca0634cb1fd..6ed39e8ae2d3 100644 --- a/src/Security/Authentication/OAuth/src/OAuthExtensions.cs +++ b/src/Security/Authentication/OAuth/src/OAuthExtensions.cs @@ -10,19 +10,52 @@ namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods to add OAuth authentication. + /// public static class OAuthExtensions { + /// + /// Adds OAuth 2.0 based authentication to using the specified authentication scheme. + /// + /// The . + /// The authentication scheme. + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddOAuth(this AuthenticationBuilder builder, string authenticationScheme, Action configureOptions) => builder.AddOAuth>(authenticationScheme, configureOptions); + /// + /// Adds OAuth 2.0 based authentication to using the specified authentication scheme. + /// + /// 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 AddOAuth(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action configureOptions) => builder.AddOAuth>(authenticationScheme, displayName, configureOptions); + /// + /// Adds OAuth 2.0 based authentication to using the specified authentication scheme. + /// + /// The . + /// The authentication scheme. + /// A delegate to configure the handler specific options. + /// A reference to after the operation has completed. public static AuthenticationBuilder AddOAuth(this AuthenticationBuilder builder, string authenticationScheme, Action configureOptions) where TOptions : OAuthOptions, new() where THandler : OAuthHandler => builder.AddOAuth(authenticationScheme, OAuthDefaults.DisplayName, configureOptions); + /// + /// Adds OAuth 2.0 based authentication to using the specified authentication scheme. + /// + /// The . + /// The authentication scheme. + /// A display name for the authentication handler. + /// A delegate to configure the handler specific options. + /// A reference to after the operation has completed. public static AuthenticationBuilder AddOAuth(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action configureOptions) where TOptions : OAuthOptions, new() where THandler : OAuthHandler diff --git a/src/Security/Authentication/OAuth/src/OAuthHandler.cs b/src/Security/Authentication/OAuth/src/OAuthHandler.cs index 13d7140fd34a..6541b1e3b940 100644 --- a/src/Security/Authentication/OAuth/src/OAuthHandler.cs +++ b/src/Security/Authentication/OAuth/src/OAuthHandler.cs @@ -20,8 +20,15 @@ namespace Microsoft.AspNetCore.Authentication.OAuth { + /// + /// An authentication handler that supports OAuth. + /// + /// The type of options. public class OAuthHandler : RemoteAuthenticationHandler where TOptions : OAuthOptions, new() { + /// + /// Gets the instance used to communicate with the remote authentication provider. + /// protected HttpClient Backchannel => Options.Backchannel; /// @@ -34,6 +41,10 @@ namespace Microsoft.AspNetCore.Authentication.OAuth set { base.Events = value; } } + /// + /// Initializes a new instance of . + /// + /// public OAuthHandler(IOptionsMonitor options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock) : base(options, logger, encoder, clock) { } @@ -44,6 +55,7 @@ public OAuthHandler(IOptionsMonitor options, ILoggerFactory logger, Ur /// A new instance of the events instance. protected override Task CreateEventsAsync() => Task.FromResult(new OAuthEvents()); + /// protected override async Task HandleRemoteAuthenticateAsync() { var query = Request.Query; @@ -173,6 +185,11 @@ protected override async Task HandleRemoteAuthenticateAsync } } + /// + /// Exchanges the authorization code for a authorization token from the remote provider. + /// + /// The . + /// The response . protected virtual async Task ExchangeCodeAsync(OAuthCodeExchangeContext context) { var tokenRequestParameters = new Dictionary() @@ -219,6 +236,13 @@ private static async Task Display(HttpResponseMessage response) return output.ToString(); } + /// + /// Creates an from the specified . + /// + /// The . + /// The . + /// The . + /// The . protected virtual async Task CreateTicketAsync(ClaimsIdentity identity, AuthenticationProperties properties, OAuthTokenResponse tokens) { using (var user = JsonDocument.Parse("{}")) @@ -229,6 +253,7 @@ protected virtual async Task CreateTicketAsync(ClaimsIdent } } + /// protected override async Task HandleChallengeAsync(AuthenticationProperties properties) { if (string.IsNullOrEmpty(properties.RedirectUri)) @@ -258,6 +283,12 @@ protected override async Task HandleChallengeAsync(AuthenticationProperties prop Logger.HandleChallenge(location, cookie); } + /// + /// Constructs the OAuth challenge url. + /// + /// The . + /// The url to redirect to once the challenge is completed. + /// The challenge url. protected virtual string BuildChallengeUrl(AuthenticationProperties properties, string redirectUri) { var scopeParameter = properties.GetParameter>(OAuthChallengeProperties.ScopeKey); diff --git a/src/Security/Authentication/OAuth/src/OAuthOptions.cs b/src/Security/Authentication/OAuth/src/OAuthOptions.cs index 821425b27452..ca2476522a5b 100644 --- a/src/Security/Authentication/OAuth/src/OAuthOptions.cs +++ b/src/Security/Authentication/OAuth/src/OAuthOptions.cs @@ -14,13 +14,16 @@ namespace Microsoft.AspNetCore.Authentication.OAuth /// public class OAuthOptions : RemoteAuthenticationOptions { + /// + /// Initializes a new instance of . + /// public OAuthOptions() { Events = new OAuthEvents(); } /// - /// Check that the options are valid. Should throw an exception if things are not ok. + /// Check that the options are valid. Should throw an exception if things are not ok. /// public override void Validate() { @@ -75,7 +78,7 @@ public override void Validate() /// /// Gets or sets the URI the middleware will access to obtain the user information. /// This value is not used in the default implementation, it is for use in custom implementations of - /// IOAuthAuthenticationEvents.Authenticated or OAuthAuthenticationHandler.CreateTicketAsync. + /// . /// public string UserInformationEndpoint { get; set; } diff --git a/src/Security/Authentication/OAuth/src/OAuthPostConfigureOptions.cs b/src/Security/Authentication/OAuth/src/OAuthPostConfigureOptions.cs index e97346413c0f..11336726b412 100644 --- a/src/Security/Authentication/OAuth/src/OAuthPostConfigureOptions.cs +++ b/src/Security/Authentication/OAuth/src/OAuthPostConfigureOptions.cs @@ -18,11 +18,16 @@ public class OAuthPostConfigureOptions : IPostConfigureOptio { private readonly IDataProtectionProvider _dp; + /// + /// Initializes the . + /// + /// The . public OAuthPostConfigureOptions(IDataProtectionProvider dataProtection) { _dp = dataProtection; } + /// public void PostConfigure(string name, TOptions options) { options.DataProtectionProvider = options.DataProtectionProvider ?? _dp; diff --git a/src/Security/Authentication/OAuth/src/OAuthTokenResponse.cs b/src/Security/Authentication/OAuth/src/OAuthTokenResponse.cs index 15eaf71eb14b..ea509e65c79b 100644 --- a/src/Security/Authentication/OAuth/src/OAuthTokenResponse.cs +++ b/src/Security/Authentication/OAuth/src/OAuthTokenResponse.cs @@ -6,8 +6,15 @@ namespace Microsoft.AspNetCore.Authentication.OAuth { + /// + /// Response from an provider for an OAuth token request. + /// public class OAuthTokenResponse : IDisposable { + /// + /// Initializes a new isntance . + /// + /// The received JSON payload. private OAuthTokenResponse(JsonDocument response) { Response = response; @@ -23,26 +30,63 @@ private OAuthTokenResponse(Exception error) Error = error; } + /// + /// Creates a successful . + /// + /// The received JSON payload. + /// A instance. public static OAuthTokenResponse Success(JsonDocument response) { return new OAuthTokenResponse(response); } + /// + /// Creates a failed . + /// + /// The error associated with the failure. + /// A instance. public static OAuthTokenResponse Failed(Exception error) { return new OAuthTokenResponse(error); } + /// public void Dispose() { Response?.Dispose(); } + /// + /// Gets or sets the received JSON payload. + /// public JsonDocument Response { get; set; } + + /// + /// Gets or sets the access token issued by the OAuth provider. + /// public string AccessToken { get; set; } + + /// + /// Gets or sets the token type. + /// + /// + /// Typically the string “bearer”. + /// public string TokenType { get; set; } + + /// + /// Gets or sets a refresh token that applications can use to obtain another access token if tokens can expire. + /// public string RefreshToken { get; set; } + + /// + /// Gets or sets the validatity lifetime of the token in seconds. + /// public string ExpiresIn { get; set; } + + /// + /// The exception in the event the response was a failure. + /// public Exception Error { get; set; } } } diff --git a/src/Security/Authentication/OpenIdConnect/src/ClaimActionCollectionUniqueExtensions.cs b/src/Security/Authentication/OpenIdConnect/src/ClaimActionCollectionUniqueExtensions.cs index 4e349579f39e..a9f21c191add 100644 --- a/src/Security/Authentication/OpenIdConnect/src/ClaimActionCollectionUniqueExtensions.cs +++ b/src/Security/Authentication/OpenIdConnect/src/ClaimActionCollectionUniqueExtensions.cs @@ -1,4 +1,4 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Security.Claims; @@ -7,6 +7,9 @@ namespace Microsoft.AspNetCore.Authentication { + /// + /// Extension methods for . + /// public static class ClaimActionCollectionUniqueExtensions { /// diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/AuthenticationFailedContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/AuthenticationFailedContext.cs index 203da93c538e..a606b09720ea 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/AuthenticationFailedContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/AuthenticationFailedContext.cs @@ -7,14 +7,27 @@ namespace Microsoft.AspNetCore.Authentication.OpenIdConnect { + /// + /// A conext for . + /// public class AuthenticationFailedContext : RemoteAuthenticationContext { + /// + /// Initializes a new instance of . + /// + /// public AuthenticationFailedContext(HttpContext context, AuthenticationScheme scheme, OpenIdConnectOptions options) : base(context, scheme, options, new AuthenticationProperties()) { } + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } + /// + /// Gets or sets the exception associated with the failure. + /// public Exception Exception { get; set; } } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/AuthorizationCodeReceivedContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/AuthorizationCodeReceivedContext.cs index bdf6e4a7ff7c..62f099a3cafb 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/AuthorizationCodeReceivedContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/AuthorizationCodeReceivedContext.cs @@ -23,6 +23,9 @@ public AuthorizationCodeReceivedContext( AuthenticationProperties properties) : base(context, scheme, options, properties) { } + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } /// @@ -90,4 +93,4 @@ public void HandleCodeRedemption(OpenIdConnectMessage tokenEndpointResponse) TokenEndpointResponse = tokenEndpointResponse; } } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/MessageReceivedContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/MessageReceivedContext.cs index 7d06e4479964..db0c1385fbe9 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/MessageReceivedContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/MessageReceivedContext.cs @@ -6,8 +6,15 @@ namespace Microsoft.AspNetCore.Authentication.OpenIdConnect { + /// + /// A context for . + /// public class MessageReceivedContext : RemoteAuthenticationContext { + /// + /// Initializes a new instance of . + /// + /// public MessageReceivedContext( HttpContext context, AuthenticationScheme scheme, @@ -15,6 +22,9 @@ public MessageReceivedContext( AuthenticationProperties properties) : base(context, scheme, options, properties) { } + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } /// @@ -22,4 +32,4 @@ public MessageReceivedContext( /// public string Token { get; set; } } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/OpenIdConnectEvents.cs b/src/Security/Authentication/OpenIdConnect/src/Events/OpenIdConnectEvents.cs index 2a48d250bbd7..6871b975c986 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/OpenIdConnectEvents.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/OpenIdConnectEvents.cs @@ -63,24 +63,56 @@ public class OpenIdConnectEvents : RemoteAuthenticationEvents /// public Func OnUserInformationReceived { get; set; } = context => Task.CompletedTask; + /// + /// Invoked if exceptions are thrown during request processing. The exceptions will be re-thrown after this event unless suppressed. + /// public virtual Task AuthenticationFailed(AuthenticationFailedContext context) => OnAuthenticationFailed(context); + /// + /// Invoked if an authorization code is present in the protocol message. + /// public virtual Task AuthorizationCodeReceived(AuthorizationCodeReceivedContext context) => OnAuthorizationCodeReceived(context); + /// + /// Invoked when a protocol message is first received. + /// public virtual Task MessageReceived(MessageReceivedContext context) => OnMessageReceived(context); + /// + /// Invoked before redirecting to the identity provider to authenticate. This can be used to set ProtocolMessage.State + /// that will be persisted through the authentication process. The ProtocolMessage can also be used to add or customize + /// parameters sent to the identity provider. + /// public virtual Task RedirectToIdentityProvider(RedirectContext context) => OnRedirectToIdentityProvider(context); + /// + /// Invoked before redirecting to the identity provider to sign out. + /// public virtual Task RedirectToIdentityProviderForSignOut(RedirectContext context) => OnRedirectToIdentityProviderForSignOut(context); + /// + /// Invoked before redirecting to the at the end of a remote sign-out flow. + /// public virtual Task SignedOutCallbackRedirect(RemoteSignOutContext context) => OnSignedOutCallbackRedirect(context); + /// + /// Invoked when a request is received on the RemoteSignOutPath. + /// public virtual Task RemoteSignOut(RemoteSignOutContext context) => OnRemoteSignOut(context); + /// + /// Invoked after an authorization code is redeemed for tokens at the token endpoint. + /// public virtual Task TokenResponseReceived(TokenResponseReceivedContext context) => OnTokenResponseReceived(context); + /// + /// Invoked when an IdToken has been validated and produced an AuthenticationTicket. + /// public virtual Task TokenValidated(TokenValidatedContext context) => OnTokenValidated(context); + /// + /// Invoked when user information is retrieved from the UserInfoEndpoint. + /// public virtual Task UserInformationReceived(UserInformationReceivedContext context) => OnUserInformationReceived(context); } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/RedirectContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/RedirectContext.cs index 9961c237d48a..1971fb979a05 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/RedirectContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/RedirectContext.cs @@ -8,10 +8,15 @@ namespace Microsoft.AspNetCore.Authentication.OpenIdConnect { /// /// When a user configures the to be notified prior to redirecting to an IdentityProvider - /// an instance of is passed to the 'RedirectToAuthenticationEndpoint' or 'RedirectToEndSessionEndpoint' events. + /// an instance of is passed to the + /// and . /// public class RedirectContext : PropertiesContext { + /// + /// Initializes a new instance of . + /// + /// public RedirectContext( HttpContext context, AuthenticationScheme scheme, @@ -19,6 +24,9 @@ public RedirectContext( AuthenticationProperties properties) : base(context, scheme, options, properties) { } + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } /// @@ -31,4 +39,4 @@ public RedirectContext( /// public void HandleResponse() => Handled = true; } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/RemoteSignoutContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/RemoteSignoutContext.cs index 26720a58f8e7..8bb18ae8160a 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/RemoteSignoutContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/RemoteSignoutContext.cs @@ -6,12 +6,22 @@ namespace Microsoft.AspNetCore.Authentication.OpenIdConnect { + /// + /// A context for event. + /// public class RemoteSignOutContext : RemoteAuthenticationContext { + /// + /// Initializes a new instance of . + /// + /// public RemoteSignOutContext(HttpContext context, AuthenticationScheme scheme, OpenIdConnectOptions options, OpenIdConnectMessage message) : base(context, scheme, options, new AuthenticationProperties()) => ProtocolMessage = message; + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/TokenResponseReceivedContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/TokenResponseReceivedContext.cs index 2bebdb8dc5fe..e2372f0b78e7 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/TokenResponseReceivedContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/TokenResponseReceivedContext.cs @@ -19,6 +19,9 @@ public TokenResponseReceivedContext(HttpContext context, AuthenticationScheme sc : base(context, scheme, options, properties) => Principal = user; + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } /// diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/TokenValidatedContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/TokenValidatedContext.cs index 853857dc7b81..5b998d13b846 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/TokenValidatedContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/TokenValidatedContext.cs @@ -8,21 +8,37 @@ namespace Microsoft.AspNetCore.Authentication.OpenIdConnect { + /// + /// A context for . + /// public class TokenValidatedContext : RemoteAuthenticationContext { /// /// Creates a /// + /// public TokenValidatedContext(HttpContext context, AuthenticationScheme scheme, OpenIdConnectOptions options, ClaimsPrincipal principal, AuthenticationProperties properties) : base(context, scheme, options, properties) => Principal = principal; + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } + /// + /// Gets or sets the validated security token. + /// public JwtSecurityToken SecurityToken { get; set; } + /// + /// Gets or sets the token endpoint response. + /// public OpenIdConnectMessage TokenEndpointResponse { get; set; } + /// + /// Gets or sets the protocol nonce. + /// public string Nonce { get; set; } } -} \ No newline at end of file +} diff --git a/src/Security/Authentication/OpenIdConnect/src/Events/UserInformationReceivedContext.cs b/src/Security/Authentication/OpenIdConnect/src/Events/UserInformationReceivedContext.cs index 29deb9acbe94..bcd12bbc430c 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Events/UserInformationReceivedContext.cs +++ b/src/Security/Authentication/OpenIdConnect/src/Events/UserInformationReceivedContext.cs @@ -8,14 +8,27 @@ namespace Microsoft.AspNetCore.Authentication.OpenIdConnect { + /// + /// A context for . + /// public class UserInformationReceivedContext : RemoteAuthenticationContext { + /// + /// Initializes a new instance of . + /// + /// public UserInformationReceivedContext(HttpContext context, AuthenticationScheme scheme, OpenIdConnectOptions options, ClaimsPrincipal principal, AuthenticationProperties properties) : base(context, scheme, options, properties) => Principal = principal; + /// + /// Gets or sets the . + /// public OpenIdConnectMessage ProtocolMessage { get; set; } + /// + /// Gets or sets the user information payload. + /// public JsonDocument User { get; set; } } } diff --git a/src/Security/Authentication/OpenIdConnect/src/Microsoft.AspNetCore.Authentication.OpenIdConnect.csproj b/src/Security/Authentication/OpenIdConnect/src/Microsoft.AspNetCore.Authentication.OpenIdConnect.csproj index c0c782fac632..2c2e1531c16f 100644 --- a/src/Security/Authentication/OpenIdConnect/src/Microsoft.AspNetCore.Authentication.OpenIdConnect.csproj +++ b/src/Security/Authentication/OpenIdConnect/src/Microsoft.AspNetCore.Authentication.OpenIdConnect.csproj @@ -1,9 +1,9 @@ - + ASP.NET Core middleware that enables an application to support the OpenID Connect authentication workflow. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security diff --git a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectChallengeProperties.cs b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectChallengeProperties.cs index 0ced488debc7..4da0cb37bc99 100644 --- a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectChallengeProperties.cs +++ b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectChallengeProperties.cs @@ -1,10 +1,13 @@ -using System; +using System; using System.Collections.Generic; using Microsoft.AspNetCore.Authentication.OAuth; using Microsoft.IdentityModel.Protocols.OpenIdConnect; namespace Microsoft.AspNetCore.Authentication.OpenIdConnect { + /// + /// for an OpenId Connect challenge. + /// public class OpenIdConnectChallengeProperties : OAuthChallengeProperties { /// @@ -17,13 +20,24 @@ public class OpenIdConnectChallengeProperties : OAuthChallengeProperties /// public static readonly string PromptKey = OpenIdConnectParameterNames.Prompt; + /// + /// Initializes a new instance of . + /// public OpenIdConnectChallengeProperties() { } + /// + /// Initializes a new instance of . + /// + /// public OpenIdConnectChallengeProperties(IDictionary items) : base(items) { } + /// + /// Initializes a new instance of . + /// + /// public OpenIdConnectChallengeProperties(IDictionary items, IDictionary parameters) : base(items, parameters) { } diff --git a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectExtensions.cs b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectExtensions.cs index f427bebaff1b..b9c607ba11ac 100644 --- a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectExtensions.cs +++ b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectExtensions.cs @@ -9,17 +9,64 @@ namespace Microsoft.Extensions.DependencyInjection { + /// + /// Extension methods to configure OpenIdConnect authentication. + /// public static class OpenIdConnectExtensions { + /// + /// Adds OpenId Connect authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It allows clients + /// to request and receive information about authenticated sessions and end-users. + /// + /// + /// The . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddOpenIdConnect(this AuthenticationBuilder builder) => builder.AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, _ => { }); + /// + /// Adds OpenId Connect authentication to using the default scheme. + /// The default scheme is specified by . + /// + /// OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It allows clients + /// to request and receive information about authenticated sessions and end-users. + /// + /// + /// The . + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddOpenIdConnect(this AuthenticationBuilder builder, Action configureOptions) => builder.AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, configureOptions); + /// + /// Adds OpenId Connect authentication to using the specified scheme. + /// + /// OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It allows clients + /// to request and receive information about authenticated sessions and end-users. + /// + /// + /// The . + /// The authentication scheme. + /// A delegate to configure . + /// A reference to after the operation has completed. public static AuthenticationBuilder AddOpenIdConnect(this AuthenticationBuilder builder, string authenticationScheme, Action configureOptions) => builder.AddOpenIdConnect(authenticationScheme, OpenIdConnectDefaults.DisplayName, configureOptions); + /// + /// Adds OpenId Connect authentication to using the specified scheme. + /// + /// OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It allows clients + /// to request and receive information about authenticated sessions and end-users. + /// + /// + /// 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 AddOpenIdConnect(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action configureOptions) { builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton, OpenIdConnectPostConfigureOptions>()); diff --git a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectHandler.cs b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectHandler.cs index 533d419c5d19..306a02cb347a 100644 --- a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectHandler.cs +++ b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectHandler.cs @@ -36,10 +36,24 @@ public class OpenIdConnectHandler : RemoteAuthenticationHandler + /// Gets the used to communicate with the remote identity provider. + /// protected HttpClient Backchannel => Options.Backchannel; + /// + /// Gets the . + /// protected HtmlEncoder HtmlEncoder { get; } + /// + /// Initializes a new instance of . + /// + /// A monitor to observe changes to . + /// The . + /// The . + /// The . + /// The . public OpenIdConnectHandler(IOptionsMonitor options, ILoggerFactory logger, HtmlEncoder htmlEncoder, UrlEncoder encoder, ISystemClock clock) : base(options, logger, encoder, clock) { @@ -56,8 +70,10 @@ public OpenIdConnectHandler(IOptionsMonitor options, ILogg set { base.Events = value; } } + /// protected override Task CreateEventsAsync() => Task.FromResult(new OpenIdConnectEvents()); + /// public override Task HandleRequestAsync() { if (Options.RemoteSignOutPath.HasValue && Options.RemoteSignOutPath == Request.Path) @@ -72,6 +88,7 @@ public override Task HandleRequestAsync() return base.HandleRequestAsync(); } + /// protected virtual async Task HandleRemoteSignOutAsync() { OpenIdConnectMessage message = null; diff --git a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectPostConfigureOptions.cs b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectPostConfigureOptions.cs index f1a39d70815c..2425c8361491 100644 --- a/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectPostConfigureOptions.cs +++ b/src/Security/Authentication/OpenIdConnect/src/OpenIdConnectPostConfigureOptions.cs @@ -18,6 +18,10 @@ public class OpenIdConnectPostConfigureOptions : IPostConfigureOptions + /// Initializes a new instance of . + /// + /// The . public OpenIdConnectPostConfigureOptions(IDataProtectionProvider dataProtection) { _dp = dataProtection;