diff --git a/src/Microsoft.AspNet.Identity/BuilderExtensions.cs b/src/Microsoft.AspNet.Identity/BuilderExtensions.cs index 9fdf0b10a1..f7931f356a 100644 --- a/src/Microsoft.AspNet.Identity/BuilderExtensions.cs +++ b/src/Microsoft.AspNet.Identity/BuilderExtensions.cs @@ -13,7 +13,7 @@ namespace Microsoft.AspNet.Builder public static class BuilderExtensions { /// - /// Enables the ASP.NET identity for the current application. + /// Enables ASP.NET identity for the current application. /// /// The instance this method extends. /// The instance this method extends. diff --git a/src/Microsoft.AspNet.Identity/ClaimsIdentityOptions.cs b/src/Microsoft.AspNet.Identity/ClaimsIdentityOptions.cs index 07f1894401..e6dc1081f4 100644 --- a/src/Microsoft.AspNet.Identity/ClaimsIdentityOptions.cs +++ b/src/Microsoft.AspNet.Identity/ClaimsIdentityOptions.cs @@ -6,12 +6,12 @@ using System.Security.Claims; namespace Microsoft.AspNet.Identity { /// - /// Options for ClaimType names. + /// Options used to configure the claim types used for well known claims. /// public class ClaimsIdentityOptions { /// - /// Gets the ClaimType used for a Role claim. + /// Gets or sets the ClaimType used for a Role claim. /// /// /// This defaults to . @@ -19,7 +19,7 @@ namespace Microsoft.AspNet.Identity public string RoleClaimType { get; set; } = ClaimTypes.Role; /// - /// Gets the ClaimType used for the user name claim. + /// Gets or sets the ClaimType used for the user name claim. /// /// /// This defaults to . @@ -27,7 +27,7 @@ namespace Microsoft.AspNet.Identity public string UserNameClaimType { get; set; } = ClaimTypes.Name; /// - /// Gets the ClaimType used for the user identifier claim. + /// Gets or sets the ClaimType used for the user identifier claim. /// /// /// This defaults to . @@ -35,7 +35,7 @@ namespace Microsoft.AspNet.Identity public string UserIdClaimType { get; set; } = ClaimTypes.NameIdentifier; /// - /// Gets the ClaimType used for the security stamp claim.. + /// Gets or sets the ClaimType used for the security stamp claim.. /// /// /// This defaults to "AspNet.Identity.SecurityStamp". diff --git a/src/Microsoft.AspNet.Identity/DataProtectionTokenProvider.cs b/src/Microsoft.AspNet.Identity/DataProtectionTokenProvider.cs index d10b6f3cc7..90b7821565 100644 --- a/src/Microsoft.AspNet.Identity/DataProtectionTokenProvider.cs +++ b/src/Microsoft.AspNet.Identity/DataProtectionTokenProvider.cs @@ -58,13 +58,12 @@ namespace Microsoft.AspNet.Identity public string Name { get { return Options.Name; } } /// - /// Generates a protected token for the specified . + /// Generates a protected token for the specified as an asynchronous operation. /// /// The purpose the token will be used for. /// The to retrieve user properties from. /// The the token will be generated from. - /// A to observe while waiting for the tasks to complete. - /// A that contains the protected token. + /// A representing the generated token. public virtual async Task GenerateAsync(string purpose, UserManager manager, TUser user) { if (user == null) @@ -90,13 +89,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Validates the protected for the specified and . + /// Validates the protected for the specified and as an asynchronous operation. /// /// The purpose the token was be used for. /// The token to validate. /// The to retrieve user properties from. /// The the token was generated for. - /// A that is true if the token is valid, otherwise false. + /// + /// A that represents the result of the asynchronous validation, + /// containing true if the token is valid, otherwise false. + /// public virtual async Task ValidateAsync(string purpose, string token, UserManager manager, TUser user) { try @@ -146,11 +148,14 @@ namespace Microsoft.AspNet.Identity /// /// Returns a indicating whether a token generated by this instance - /// can be used as a Two Factor Authentication token. + /// can be used as a Two Factor Authentication token as an asynchronous operation. /// /// The to retrieve user properties from. /// The the token was generated for. - /// True if a token generated by this instance can be used as a Two Factor Authentication token, otherwise false. + /// + /// A that represents the result of the asynchronous query, + /// containing true if a token generated by this instance can be used as a Two Factor Authentication token, otherwise false. + /// /// This method will always return false for instances of . public virtual Task CanGenerateTwoFactorTokenAsync(UserManager manager, TUser user) { @@ -158,12 +163,12 @@ namespace Microsoft.AspNet.Identity } /// - /// Creates a notification task for A based on the supplied . + /// Creates a notification for the specified based on the supplied as an asynchronous operation. /// - /// The token to generate notifications for.. + /// The token to generate notifications for. /// The to retrieve user properties from. /// The the token was generated for. - /// A that represents the started task. + /// A that represents the asynchronous notification. public virtual Task NotifyAsync(string token, UserManager manager, TUser user) { return Task.FromResult(0); diff --git a/src/Microsoft.AspNet.Identity/EmailTokenProvider.cs b/src/Microsoft.AspNet.Identity/EmailTokenProvider.cs index 776d1f8e19..31d91de53a 100644 --- a/src/Microsoft.AspNet.Identity/EmailTokenProvider.cs +++ b/src/Microsoft.AspNet.Identity/EmailTokenProvider.cs @@ -4,18 +4,32 @@ using Microsoft.Framework.OptionsModel; namespace Microsoft.AspNet.Identity { + /// + /// Options for the class. + /// public class EmailTokenProviderOptions { + /// + /// Gets or sets the unique name used for an instance of . + /// + /// + /// The unique name used for an instance of . + /// public string Name { get; set; } = "Email"; } /// - /// TokenProvider that generates tokens from the user's security stamp and notifies a user via their email + /// TokenProvider that generates tokens from the user's security stamp and notifies a user via email. /// - /// + /// The type used to represent a user. public class EmailTokenProvider : TotpSecurityStampBasedTokenProvider where TUser : class { + /// + /// Initializes a new instance of the class. + /// + /// The configured . + /// The unique name for this instance of . public EmailTokenProvider(IOptions options, string name = "") { if (options == null) @@ -25,16 +39,28 @@ namespace Microsoft.AspNet.Identity Options = options.GetNamedOptions(name); } + /// + /// Gets the options for this instance of . + /// + /// + /// The options for this instance of . + /// public EmailTokenProviderOptions Options { get; private set; } + /// + /// Gets the unique name for this instance of . + /// + /// + /// The unique name for this instance of . + /// public override string Name { get { return Options.Name; } } /// - /// True if the user has an email set + /// Checks if a two factor authentication token can be generated for the specified . /// - /// - /// - /// + /// The to retrieve the from. + /// The to check for the possibility of generating a two factor authentication token. + /// True if the user has an email address set, otherwise false. public override async Task CanGenerateTwoFactorTokenAsync(UserManager manager, TUser user) { var email = await manager.GetEmailAsync(user); @@ -42,12 +68,12 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns the email of the user for entropy in the token + /// Returns the a value for the user used as entropy in the generated token. /// - /// - /// - /// - /// + /// The purpose of the two factor authentication token. + /// The to retrieve the from. + /// The to check for the possibility of generating a two factor authentication token. + /// A string suitable for use as entropy in token generation. public override async Task GetUserModifierAsync(string purpose, UserManager manager, TUser user) { diff --git a/src/Microsoft.AspNet.Identity/ExternalLoginInfo.cs b/src/Microsoft.AspNet.Identity/ExternalLoginInfo.cs index 21b4c44b33..4d7408799b 100644 --- a/src/Microsoft.AspNet.Identity/ExternalLoginInfo.cs +++ b/src/Microsoft.AspNet.Identity/ExternalLoginInfo.cs @@ -5,14 +5,28 @@ using System.Security.Claims; namespace Microsoft.AspNet.Identity { + /// + /// Represents login information, source and externally source principal for a user record + /// public class ExternalLoginInfo : UserLoginInfo { + /// + /// Creates a new instance of + /// + /// The to associate with this login. + /// The provider associated with this login information. + /// The unique identifier for this user provided by the login provider. + /// The display name for this user provided by the login provider. public ExternalLoginInfo(ClaimsPrincipal externalPrincipal, string loginProvider, string providerKey, string displayName) : base(loginProvider, providerKey, displayName) { ExternalPrincipal = externalPrincipal; } + /// + /// Gets or sets the associated with this login. + /// + /// The associated with this login. public ClaimsPrincipal ExternalPrincipal { get; set; } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/ILookupNormalizer.cs b/src/Microsoft.AspNet.Identity/ILookupNormalizer.cs index 61d69ad101..18be9776c1 100644 --- a/src/Microsoft.AspNet.Identity/ILookupNormalizer.cs +++ b/src/Microsoft.AspNet.Identity/ILookupNormalizer.cs @@ -4,15 +4,15 @@ namespace Microsoft.AspNet.Identity { /// - /// Used to normalize keys for consistent lookups + /// Provides an abstraction for normalizing keys for lookup purposes. /// public interface ILookupNormalizer { /// - /// Returns the normalized key + /// Returns a normalized representation of the specified . /// - /// - /// + /// The key to normalize. + /// A normalized representation of the specified . string Normalize(string key); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IPasswordHasher.cs b/src/Microsoft.AspNet.Identity/IPasswordHasher.cs index 968edfd256..b9afb36388 100644 --- a/src/Microsoft.AspNet.Identity/IPasswordHasher.cs +++ b/src/Microsoft.AspNet.Identity/IPasswordHasher.cs @@ -4,25 +4,27 @@ namespace Microsoft.AspNet.Identity { /// - /// Abstraction for password hashing methods + /// Provides an abstraction for hashing passwords. /// + /// The type used to represent a user. public interface IPasswordHasher where TUser : class { /// - /// Hash a password + /// Returns a hashed representation of the supplied for the specified . /// - /// - /// - /// + /// The user whose password is to be hashed. + /// The password to hash. + /// A hashed representation of the supplied for the specified . string HashPassword(TUser user, string password); /// - /// Verify that a password matches the hashed password + /// Returns a indicating the result of a password hash comparison. /// - /// - /// - /// - /// + /// The user whose password should be verified. + /// The hash value for a user's stored password. + /// The password supplied for comparison. + /// A indicating the result of a password hash comparison. + /// Implementations of this method should be time consistent. PasswordVerificationResult VerifyHashedPassword(TUser user, string hashedPassword, string providedPassword); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IPasswordValidator.cs b/src/Microsoft.AspNet.Identity/IPasswordValidator.cs index 3eab8ca9e0..c9d9b1bb64 100644 --- a/src/Microsoft.AspNet.Identity/IPasswordValidator.cs +++ b/src/Microsoft.AspNet.Identity/IPasswordValidator.cs @@ -7,14 +7,18 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Used to validate passwords + /// Provides an abstraction for validating passwords. /// + /// The type that represents a user. public interface IPasswordValidator where TUser : class { /// - /// Validate the password for the user + /// Validates a password as an asynchronous operation. /// - /// + /// The to retrieve the properties from. + /// The user whose password should be validated. + /// The password supplied for validation + /// The task object representing the asynchronous operation. Task ValidateAsync(UserManager manager, TUser user, string password); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IQueryableRoleStore.cs b/src/Microsoft.AspNet.Identity/IQueryableRoleStore.cs index 4c936d84c9..04f439e89b 100644 --- a/src/Microsoft.AspNet.Identity/IQueryableRoleStore.cs +++ b/src/Microsoft.AspNet.Identity/IQueryableRoleStore.cs @@ -6,14 +6,15 @@ using System.Linq; namespace Microsoft.AspNet.Identity { /// - /// Interface that exposes an IQueryable roles + /// Provides an abstraction for querying roles in a Role store. /// - /// + /// The type encapsulating a role. public interface IQueryableRoleStore : IRoleStore where TRole : class { /// - /// IQueryable roles + /// Returns an collection of roles. /// + /// An collection of roles. IQueryable Roles { get; } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IQueryableUserStore.cs b/src/Microsoft.AspNet.Identity/IQueryableUserStore.cs index 4f42eeb366..8bb4c2ba36 100644 --- a/src/Microsoft.AspNet.Identity/IQueryableUserStore.cs +++ b/src/Microsoft.AspNet.Identity/IQueryableUserStore.cs @@ -6,14 +6,15 @@ using System.Linq; namespace Microsoft.AspNet.Identity { /// - /// Interface that exposes an IQueryable users + /// Provides an abstraction for querying roles in a User store. /// - /// + /// The type encapsulating a user. public interface IQueryableUserStore : IUserStore where TUser : class { /// - /// IQueryable users + /// Returns an collection of users. /// + /// An collection of users. IQueryable Users { get; } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IRoleClaimStore.cs b/src/Microsoft.AspNet.Identity/IRoleClaimStore.cs index bb62892bac..ff8bb1515f 100644 --- a/src/Microsoft.AspNet.Identity/IRoleClaimStore.cs +++ b/src/Microsoft.AspNet.Identity/IRoleClaimStore.cs @@ -9,37 +9,37 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores role specific claims + /// Provides an abstraction for a store of role specific claims. /// - /// + /// The type encapsulating a role. public interface IRoleClaimStore : IRoleStore where TRole : class { /// - /// Returns the claims for the role + /// Gets a list of s to be belonging to the specified as an asynchronous operation. /// - /// - /// - /// - Task> GetClaimsAsync(TRole role, - CancellationToken cancellationToken = default(CancellationToken)); + /// The role whose claims to retrieve. + /// The used to propagate notifications that the operation should be canceled. + /// + /// A that represents the result of the asynchronous query, a list of s. + /// + Task> GetClaimsAsync(TRole role, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Add a new role claim + /// Add a new claim to a role as an asynchronous operation. /// - /// - /// - /// - /// + /// The role to add a claim to. + /// The to add. + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. Task AddClaimAsync(TRole role, Claim claim, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Remove a role claim + /// Remove a claim from a role as an asynchronous operation. /// - /// - /// - /// - /// - Task RemoveClaimAsync(TRole role, Claim claim, - CancellationToken cancellationToken = default(CancellationToken)); + /// The role to remove the claim from. + /// The to remove. + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. + Task RemoveClaimAsync(TRole role, Claim claim, CancellationToken cancellationToken = default(CancellationToken)); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IRoleStore.cs b/src/Microsoft.AspNet.Identity/IRoleStore.cs index d45ad59777..024121290a 100644 --- a/src/Microsoft.AspNet.Identity/IRoleStore.cs +++ b/src/Microsoft.AspNet.Identity/IRoleStore.cs @@ -8,92 +8,92 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Interface that exposes basic role management + /// Provides an abstraction for a storage and management of roles. /// - /// + /// The type that represents a role. public interface IRoleStore : IDisposable where TRole : class { /// - /// Insert a new role + /// Creates a new role in a store as an asynchronous operation. /// - /// - /// - /// + /// The role to create in the store. + /// The used to propagate notifications that the operation should be canceled. + /// A that represents the of the asynchronous query. Task CreateAsync(TRole role, CancellationToken cancellationToken); /// - /// Update a role + /// Updates a role in a store as an asynchronous operation. /// - /// - /// - /// + /// The role to update in the store. + /// The used to propagate notifications that the operation should be canceled. + /// A that represents the of the asynchronous query. Task UpdateAsync(TRole role, CancellationToken cancellationToken); /// - /// DeleteAsync a role + /// Deletes a role from the store as an asynchronous operation. /// - /// - /// - /// + /// The role to delete from the store. + /// The used to propagate notifications that the operation should be canceled. + /// A that represents the of the asynchronous query. Task DeleteAsync(TRole role, CancellationToken cancellationToken); /// - /// Returns a role's id + /// Gets the ID for a role from the store as an asynchronous operation. /// - /// - /// - /// + /// The role whose ID should be returned. + /// The used to propagate notifications that the operation should be canceled. + /// A that contains the ID of the role. Task GetRoleIdAsync(TRole role, CancellationToken cancellationToken); /// - /// Returns a role's name + /// Gets the name of a role from the store as an asynchronous operation. /// - /// - /// - /// + /// The role whose name should be returned. + /// The used to propagate notifications that the operation should be canceled. + /// A that contains the name of the role. Task GetRoleNameAsync(TRole role, CancellationToken cancellationToken); /// - /// Set a role's name + /// Sets the name of a role in the store as an asynchronous operation. /// - /// - /// - /// - /// + /// The role whose name should be set. + /// The name of the role. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetRoleNameAsync(TRole role, string roleName, CancellationToken cancellationToken); /// - /// Get a role's normalized name + /// Get a role's normalized name as an asynchronous operation. /// - /// - /// - /// + /// The role whose normalized name should be retrieved. + /// The used to propagate notifications that the operation should be canceled. + /// A that contains the name of the role. Task GetNormalizedRoleNameAsync(TRole role, CancellationToken cancellationToken); /// - /// Set a role's normalized name + /// Set a role's normalized name as an asynchronous operation. /// - /// - /// - /// - /// + /// The role whose normalized name should be set. + /// The normalized name to set + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetNormalizedRoleNameAsync(TRole role, string normalizedName, CancellationToken cancellationToken); /// - /// Finds a role by id + /// Finds the role who has the specified ID as an asynchronous operation. /// - /// - /// - /// + /// The role ID to look for. + /// The used to propagate notifications that the operation should be canceled. + /// A that result of the look up. Task FindByIdAsync(string roleId, CancellationToken cancellationToken); /// - /// Find a role by normalized name + /// Finds the role who has the specified normalized name as an asynchronous operation. /// - /// - /// - /// + /// The normalized role name to look for. + /// The used to propagate notifications that the operation should be canceled. + /// A that result of the look up. Task FindByNameAsync(string normalizedRoleName, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IRoleValidator.cs b/src/Microsoft.AspNet.Identity/IRoleValidator.cs index a519ab3a71..6659b60470 100644 --- a/src/Microsoft.AspNet.Identity/IRoleValidator.cs +++ b/src/Microsoft.AspNet.Identity/IRoleValidator.cs @@ -1,23 +1,22 @@ // 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.Threading; using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Used to validate a role + /// Provides an abstraction for a validating a role. /// - /// + /// The type encapsulating a role. public interface IRoleValidator where TRole : class { /// - /// ValidateAsync the user + /// Validates a role as an asynchronous operation. /// - /// - /// - /// + /// The managing the role store. + /// The role to validate. + /// A that represents the of the asynchronous validation. Task ValidateAsync(RoleManager manager, TRole role); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/ISecurityStampValidator.cs b/src/Microsoft.AspNet.Identity/ISecurityStampValidator.cs index 646c62742a..1e68470681 100644 --- a/src/Microsoft.AspNet.Identity/ISecurityStampValidator.cs +++ b/src/Microsoft.AspNet.Identity/ISecurityStampValidator.cs @@ -6,8 +6,19 @@ using Microsoft.AspNet.Authentication.Cookies; namespace Microsoft.AspNet.Identity { + /// + /// Provides an abstraction for a validating a security stamp of an incoming identity, and regenerating or rejecting the + /// identity based on the validation result. + /// public interface ISecurityStampValidator { + /// + /// Validates a security stamp of an identity as an asynchronous operation, and rebuilds the identity if the validation succeeds, otherwise rejects + /// the identity. + /// + /// The context containing the and to validate. + /// The that represents the asynchronous validation operation. Task ValidateAsync(CookieValidatePrincipalContext context); } -} \ No newline at end of file +} + diff --git a/src/Microsoft.AspNet.Identity/IUserClaimStore.cs b/src/Microsoft.AspNet.Identity/IUserClaimStore.cs index d7cd5d39bd..f139b2f1e0 100644 --- a/src/Microsoft.AspNet.Identity/IUserClaimStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserClaimStore.cs @@ -9,53 +9,58 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores user specific claims + /// Provides an abstraction for a store of claims for a user. /// - /// + /// The type encapsulating a user. public interface IUserClaimStore : IUserStore where TUser : class { /// - /// Returns the claims for the user + /// Gets a list of s to be belonging to the specified as an asynchronous operation. /// - /// - /// - /// + /// The role whose claims to retrieve. + /// The used to propagate notifications that the operation should be canceled. + /// + /// A that represents the result of the asynchronous query, a list of s. + /// Task> GetClaimsAsync(TUser user, CancellationToken cancellationToken); /// - /// Add a new user claim + /// Add claims to a user as an asynchronous operation. /// - /// - /// - /// - /// + /// The user to add the claim to. + /// The collection of s to add. + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. Task AddClaimsAsync(TUser user, IEnumerable claims, CancellationToken cancellationToken); /// - /// Updates the give claim information with the given new claim information + /// Replaces the given on the specified with the /// - /// - /// - /// - /// - /// + /// The user to replace the claim on. + /// The claim to replace. + /// The new claim to replace the existing with. + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. Task ReplaceClaimAsync(TUser user, Claim claim, Claim newClaim, CancellationToken cancellationToken); /// - /// Remove a user claim + /// Removes the specified from the given . /// - /// - /// - /// - /// + /// The user to remove the specified from. + /// A collection of s to remove. + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. Task RemoveClaimsAsync(TUser user, IEnumerable claims, CancellationToken cancellationToken); /// - /// Get users having a specific claim + /// Returns a list of users who contain the specified . /// - /// Claim to look up - /// - /// + /// The claim to look for. + /// The used to propagate notifications that the operation should be canceled. + /// + /// A that represents the result of the asynchronous query, a list of who + /// contain the specified claim. + /// Task> GetUsersForClaimAsync(Claim claim, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserClaimsPrincipalFactory.cs b/src/Microsoft.AspNet.Identity/IUserClaimsPrincipalFactory.cs index bca67c18ed..d4c05a8ab8 100644 --- a/src/Microsoft.AspNet.Identity/IUserClaimsPrincipalFactory.cs +++ b/src/Microsoft.AspNet.Identity/IUserClaimsPrincipalFactory.cs @@ -7,18 +7,18 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Interface for creating a ClaimsPrincipal from an user + /// Provides an abstraction for a factory to create a from a user. /// - /// + /// The type encapsulating a user. public interface IUserClaimsPrincipalFactory where TUser : class { /// - /// Create a ClaimsPrincipal from an user + /// Creates a from an user asynchronously. /// - /// - /// - /// + /// The user to create a from. + /// The name of the authentication method the was sourced from. + /// The that represents the asynchronous creation operation, containing the created . Task CreateAsync(TUser user); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserEmailStore.cs b/src/Microsoft.AspNet.Identity/IUserEmailStore.cs index 8461377cd9..5ac801a5d3 100644 --- a/src/Microsoft.AspNet.Identity/IUserEmailStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserEmailStore.cs @@ -7,68 +7,76 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores a user's email + /// Provides an abstraction for the storage and management of user email addresses. /// - /// + /// The type encapsulating a user. public interface IUserEmailStore : IUserStore where TUser : class { /// - /// Set the user email + /// Sets the address for a , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose email should be set. + /// The email to set. + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. Task SetEmailAsync(TUser user, string email, CancellationToken cancellationToken); /// - /// Get the user email + /// Gets the email address for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose email should be returned. + /// The used to propagate notifications that the operation should be canceled. + /// The task object containing the results of the asynchronous operation, the email address for the specified . Task GetEmailAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns true if the user email is confirmed + /// Gets a flag indicating whether the email address for the specified has been verified, true if the email address is verified otherwise + /// false, as an asynchronous operation. /// - /// - /// - /// + /// The user whose email confirmation status should be returned. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The task object containing the results of the asynchronous operation, a flag indicating whether the email address for the specified + /// has been confirmed or not. + /// Task GetEmailConfirmedAsync(TUser user, CancellationToken cancellationToken); /// - /// Sets whether the user email is confirmed + /// Sets the flag indicating whether the specified 's email address has been confirmed or not, as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose email confirmation status should be set. + /// A flag indicating if the email address has been confirmed, true if the address is confirmed otherwise false. + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. Task SetEmailConfirmedAsync(TUser user, bool confirmed, CancellationToken cancellationToken); /// - /// Returns the user associated with this email + /// Gets the user, if any, associated with the specified, normalized email address, as an asynchronous operation. /// - /// - /// - /// + /// The normalized email address to return the user for. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The task object containing the results of the asynchronous lookup operation, the user if any associated with the specified normalized email address. + /// Task FindByEmailAsync(string normalizedEmail, CancellationToken cancellationToken); /// - /// Returns the normalized email + /// Returns the normalized email for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose email address to retrieve. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The task object containing the results of the asynchronous lookup operation, the normalized email address if any associated with the specified user. + /// Task GetNormalizedEmailAsync(TUser user, CancellationToken cancellationToken); /// - /// Set the normalized email + /// Sets the normalized email for the specified , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose email address to set. + /// The normalized email to set for the specified . + /// The used to propagate notifications that the operation should be canceled. + /// The task object representing the asynchronous operation. Task SetNormalizedEmailAsync(TUser user, string normalizedEmail, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserLockoutStore.cs b/src/Microsoft.AspNet.Identity/IUserLockoutStore.cs index e7b346593b..b72ab31014 100644 --- a/src/Microsoft.AspNet.Identity/IUserLockoutStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserLockoutStore.cs @@ -8,69 +8,75 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores information which can be used to implement account lockout, including access failures and lockout status + /// Provides an abstraction for a storing information which can be used to implement account lockout, + /// including access failures and lockout status /// - /// + /// The type that represents a user. public interface IUserLockoutStore : IUserStore where TUser : class { /// - /// Returns the DateTimeOffset that represents the end of a user's lockout, any time in the past should be - /// considered not locked out. + /// Gets the last a user's last lockout expired, if any, as an asynchronous operation. + /// Any time in the past should be indicates a user is not locked out. /// - /// - /// - /// + /// The user whose lockout date should be retrieved. + /// The used to propagate notifications that the operation should be canceled. + /// + /// A that represents the result of the asynchronous query, a containing the last time + /// a user's lockout expired, if any. + /// Task GetLockoutEndDateAsync(TUser user, CancellationToken cancellationToken); /// - /// Locks a user out until the specified end date (set to a past date, to unlock a user) + /// Locks out a user until the specified end date has passed, as an asynchronous operation. Setting a end date in the past immediately unlocks a user. /// - /// - /// - /// - /// + /// The user whose lockout date should be set. + /// The after which the 's lockout should end. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetLockoutEndDateAsync(TUser user, DateTimeOffset? lockoutEnd, CancellationToken cancellationToken); /// - /// Used to record when an attempt to access the user has failed + /// Records that a failed access has occurred, incrementing the failed access count, as an asynchronous operation. /// - /// - /// - /// + /// The user whose cancellation count should be incremented. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the incremented failed access count. Task IncrementAccessFailedCountAsync(TUser user, CancellationToken cancellationToken); /// - /// Used to reset the account access count, typically after the account is successfully accessed + /// Resets a user's failed access count, as an asynchronous operation. /// - /// - /// - /// + /// The user whose failed access count should be reset. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. + /// This is typically called after the account is successfully accessed. Task ResetAccessFailedCountAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns the current number of failed access attempts. This number usually will be reset whenever the - /// password is verified or the account is locked out. + /// Retrieves the current failed access count for the specified , as an asynchronous operation.. /// - /// - /// - /// + /// The user whose failed access count should be retrieved. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the failed access count. Task GetAccessFailedCountAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns whether the user can be locked out. + /// Retrieves a flag indicating whether user lockout can enabled for the specified user, as an asynchronous operation. /// - /// - /// - /// + /// The user whose ability to be locked out should be returned. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, true if a user can be locked out, otherwise false. + /// Task GetLockoutEnabledAsync(TUser user, CancellationToken cancellationToken); /// - /// Sets whether the user can be locked out. + /// Set the flag indicating if the specified can be locked out, as an asynchronous operation.. /// - /// - /// - /// - /// + /// The user whose ability to be locked out should be set. + /// A flag indicating if lock out can be enabled for the specified . + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetLockoutEnabledAsync(TUser user, bool enabled, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserLoginStore.cs b/src/Microsoft.AspNet.Identity/IUserLoginStore.cs index a794ca35ba..e6e6e32bdd 100644 --- a/src/Microsoft.AspNet.Identity/IUserLoginStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserLoginStore.cs @@ -8,45 +8,54 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Interface that maps users to login providers, i.e. Google, Facebook, Twitter, Microsoft + /// Provides an abstraction for storing information that maps external login information provided + /// by Microsoft Account, Facebook etc. to a user account. /// - /// + /// The type that represents a user. public interface IUserLoginStore : IUserStore where TUser : class { /// - /// Adds a user login with the specified provider and key + /// Adds an external to the specified , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user to add the login to. + /// The external to add to the specified . + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task AddLoginAsync(TUser user, UserLoginInfo login, CancellationToken cancellationToken); /// - /// Removes the user login with the specified combination if it exists, returns true if found and removed + /// Attempts to remove the provided login information from the specified , as an asynchronous operation. + /// and returns a flag indicating whether the removal succeed or not. /// - /// - /// - /// - /// - /// + /// The user to remove the login information from. + /// The login provide whose information should be removed. + /// The key given by the external login provider for the specified user. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that contains a flag the result of the asynchronous removing operation. The flag will be true if + /// the login information was existed and removed, otherwise false. + /// Task RemoveLoginAsync(TUser user, string loginProvider, string providerKey, CancellationToken cancellationToken); /// - /// Returns the linked accounts for this user + /// Retrieves the associated logins for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose associated logins to retrieve. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The for the asynchronous operation, containing a list of for the specified , if any. + /// Task> GetLoginsAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns the user associated with this login + /// Retrieves the user associated with the specified login provider and login provider key, as an asynchronous operation.. /// - /// - /// - /// - /// + /// The login provider who provided the . + /// The key provided by the to identify a user. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The for the asynchronous operation, containing the user, if any which matched the specified login provider and key. + /// Task FindByLoginAsync(string loginProvider, string providerKey, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserPasswordStore.cs b/src/Microsoft.AspNet.Identity/IUserPasswordStore.cs index 399fb6ed36..087b7c56eb 100644 --- a/src/Microsoft.AspNet.Identity/IUserPasswordStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserPasswordStore.cs @@ -7,34 +7,37 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores a user's password hash + /// Provides an abstraction for a store containing users' password hashes.. /// - /// + /// The type encapsulating a user. public interface IUserPasswordStore : IUserStore where TUser : class { /// - /// Set the user password hash + /// Sets the password hash for the specified , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose password hash to set. + /// The password hash to set. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetPasswordHashAsync(TUser user, string passwordHash, CancellationToken cancellationToken); /// - /// Get the user password hash + /// Gets the password hash for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose password hash to retrieve. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, returning the password hash for the specified . Task GetPasswordHashAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns true if a user has a password set + /// Gets a flag indicating whether the specified has a password, as an asynchronous operation. /// - /// - /// - /// + /// The user to return a flag for, indicating whether they have a password or not. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, returning true if the specified has a password + /// otherwise false. + /// Task HasPasswordAsync(TUser user, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserPhoneNumberStore.cs b/src/Microsoft.AspNet.Identity/IUserPhoneNumberStore.cs index 6a1aba9f6b..5a5403a3df 100644 --- a/src/Microsoft.AspNet.Identity/IUserPhoneNumberStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserPhoneNumberStore.cs @@ -7,43 +7,46 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores a user's phoneNumber + /// Provides an abstraction for a store containing users' telephone numbers. /// - /// + /// The type encapsulating a user. public interface IUserPhoneNumberStore : IUserStore where TUser : class { /// - /// Set the user PhoneNumber + /// Sets the telephone number for the specified , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose telephone number should be set. + /// The telephone number to set. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetPhoneNumberAsync(TUser user, string phoneNumber, CancellationToken cancellationToken); /// - /// Get the user phoneNumber + /// Gets the telephone number, if any, for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose telephone number should be retrieved. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the user's telephone number, if any. Task GetPhoneNumberAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns true if the user phone number is confirmed + /// Gets a flag indicating whether the specified 's telephone number has been confirmed, as an asynchronous operation. /// - /// - /// - /// + /// The user to return a flag for, indicating whether their telephone number is confirmed. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, returning true if the specified has a confirmed + /// telephone number otherwise false. + /// Task GetPhoneNumberConfirmedAsync(TUser user, CancellationToken cancellationToken); /// - /// Sets whether the user phone number is confirmed + /// Sets a flag indicating if the specified 's phone number has been confirmed, as an asynchronous operation.. /// - /// - /// - /// - /// + /// The user whose telephone number confirmation status should be set. + /// A flag indicating whether the user's telephone number has been confirmed. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetPhoneNumberConfirmedAsync(TUser user, bool confirmed, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserRoleStore.cs b/src/Microsoft.AspNet.Identity/IUserRoleStore.cs index d437b556c2..32ac944b41 100644 --- a/src/Microsoft.AspNet.Identity/IUserRoleStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserRoleStore.cs @@ -8,52 +8,57 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Interface that maps users to their roles + /// Provides an abstraction for a store which maps users to roles. /// - /// + /// The type encapsulating a user. public interface IUserRoleStore : IUserStore where TUser : class { /// - /// Adds a user to role + /// Add a the specified to the named role, as an asynchronous operation. /// - /// - /// - /// - /// + /// The user to add to the named role. + /// The name of the role to add the user to. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task AddToRoleAsync(TUser user, string roleName, CancellationToken cancellationToken); /// - /// Removes the role for the user + /// Add a the specified from the named role, as an asynchronous operation. /// - /// - /// - /// - /// + /// The user to remove the named role from. + /// The name of the role to remove. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task RemoveFromRoleAsync(TUser user, string roleName, CancellationToken cancellationToken); /// - /// Returns the roles for this user + /// Gets a list of role names the specified belongs to, as an asynchronous operation. /// - /// - /// - /// + /// The user whose role names to retrieve. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing a list of role names. Task> GetRolesAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns true if a user is in a role + /// Returns a flag indicating whether the specified is a member of the give named role, as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose role membership should be checked. + /// The name of the role to be checked. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing a flag indicating whether the specified is + /// a member of the named role. + /// Task IsInRoleAsync(TUser user, string roleName, CancellationToken cancellationToken); /// - /// Returns all users in given role + /// Returns a list of Users who are members of the named role. /// - /// - /// - /// + /// The name of the role whose membership should be returned. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing a list of users who are in the named role. + /// Task> GetUsersInRoleAsync(string roleName, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserSecurityStampStore.cs b/src/Microsoft.AspNet.Identity/IUserSecurityStampStore.cs index 00f2b83882..b66a4a5ca4 100644 --- a/src/Microsoft.AspNet.Identity/IUserSecurityStampStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserSecurityStampStore.cs @@ -7,26 +7,26 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores a user's security stamp + /// Provides an abstraction for a store which stores a user's security stamp. /// - /// + /// The type encapsulating a user. public interface IUserSecurityStampStore : IUserStore where TUser : class { /// - /// Set the security stamp for the user + /// Sets the provided security for the specified , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose security stamp should be set. + /// The security stamp to set. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetSecurityStampAsync(TUser user, string stamp, CancellationToken cancellationToken); /// - /// Get the user security stamp + /// Get the security stamp for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose security stamp should be set. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the security stamp for the specified . Task GetSecurityStampAsync(TUser user, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserStore.cs b/src/Microsoft.AspNet.Identity/IUserStore.cs index 8373c8b31d..3643464ccb 100644 --- a/src/Microsoft.AspNet.Identity/IUserStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserStore.cs @@ -8,93 +8,95 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Interface that exposes basic user management apis + /// Provides an abstraction for a store which manages user accounts. /// - /// + /// The type encapsulating a user. public interface IUserStore : IDisposable where TUser : class { /// - /// Returns the user id for a user + /// Gets the user identifier for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose identifier should be retrieved. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the identifier for the specified . Task GetUserIdAsync(TUser user, CancellationToken cancellationToken); /// - /// Returns the user's name + /// Gets the user name for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose name should be retrieved. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the name for the specified . Task GetUserNameAsync(TUser user, CancellationToken cancellationToken); /// - /// Set the user name + /// Sets the given for the specified , as an asynchronous operation. /// - /// - /// - /// - /// - Task SetUserNameAsync(TUser user, string userName, - CancellationToken cancellationToken); + /// The user whose name should be set. + /// The user name to set. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. + Task SetUserNameAsync(TUser user, string userName, CancellationToken cancellationToken); /// - /// Returns the normalized user name + /// Gets the normalized user name for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose normalized name should be retrieved. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the normalized user name for the specified . Task GetNormalizedUserNameAsync(TUser user, CancellationToken cancellationToken); /// - /// Set the normalized user name + /// Sets the given normalized name for the specified , as an asynchronous operation. /// - /// - /// - /// - /// - Task SetNormalizedUserNameAsync(TUser user, string normalizedName, - CancellationToken cancellationToken); + /// The user whose name should be set. + /// The normalized name to set. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. + Task SetNormalizedUserNameAsync(TUser user, string normalizedName, CancellationToken cancellationToken); /// - /// Insert a new user + /// Creates the specified in the user store, as an asynchronous operation. /// - /// - /// - /// + /// The user to create. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the of the creation operation. Task CreateAsync(TUser user, CancellationToken cancellationToken); /// - /// UpdateAsync a user + /// Updates the specified in the user store, as an asynchronous operation. /// - /// - /// - /// + /// The user to update. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the of the update operation. Task UpdateAsync(TUser user, CancellationToken cancellationToken); /// - /// DeleteAsync a user + /// Deletes the specified from the user store, as an asynchronous operation. /// - /// - /// - /// + /// The user to delete. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation, containing the of the update operation. Task DeleteAsync(TUser user, CancellationToken cancellationToken); /// - /// Finds a user + /// Finds and returns a user, if any, who has the specified . /// - /// - /// - /// + /// The user ID to search for. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing the user matching the specified if it exists. + /// Task FindByIdAsync(string userId, CancellationToken cancellationToken); /// - /// Returns the user associated with this normalized user name + /// Finds and returns a user, if any, who has the specified normalized user name. /// - /// - /// - /// + /// The normalized user name to search for. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing the user matching the specified if it exists. + /// Task FindByNameAsync(string normalizedUserName, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserTokenProvider.cs b/src/Microsoft.AspNet.Identity/IUserTokenProvider.cs index 1de8d0f1e4..ce9ee317be 100644 --- a/src/Microsoft.AspNet.Identity/IUserTokenProvider.cs +++ b/src/Microsoft.AspNet.Identity/IUserTokenProvider.cs @@ -6,40 +6,64 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Interface to generate user tokens + /// Provides an abstraction for token generators. /// + /// The type encapsulating a user. public interface IUserTokenProvider where TUser : class { /// - /// Name of the token provider + /// Gets the name of the token provider. /// + /// The name of the token provider. string Name { get; } /// - /// Generate a token for a user + /// Generates a token for the specified and , as an asynchronous operation. /// - /// - /// - /// - /// + /// The purpose the token will be used for. + /// The that can be used to retrieve user properties. + /// The user a token should be generated for. + /// + /// The that represents the asynchronous operation, containing the token for the specified + /// and . + /// + /// + /// The parameter allows a token generator to be used for multiple types of token whilst + /// insuring a token for one purpose cannot be used for another. For example if you specified a purpose of "Email" + /// and validated it with the same purpose a token with the purpose of TOTP would not pass the heck even if it was + /// for the same user. + /// + /// Implementations of should validate that purpose is not null or empty to + /// help with token separation. + /// Task GenerateAsync(string purpose, UserManager manager, TUser user); /// - /// ValidateAsync and unprotect a token, returns null if invalid + /// Returns a flag indicating whether the specified is valid for the given + /// and , as an asynchronous operation. /// - /// - /// - /// - /// - /// + /// The purpose the token will be used for. + /// The token to validate. + /// The that can be used to retrieve user properties. + /// The user a token should be validated for. + /// + /// The that represents the asynchronous operation, containing the a flag indicating the result + /// of validating the for the specified and . + /// The task will return true if the token is valid, otherwise false. + /// Task ValidateAsync(string purpose, string token, UserManager manager, TUser user); /// - /// Returns true if provider can be used for this user to generate two factor tokens, i.e. could require a user to have an email + /// Returns a flag indicating whether the token provider can generate a token suitable for two factor authentication token for + /// the specified . /// - /// - /// - /// + /// The that can be used to retrieve user properties. + /// The user a token could be generated for. + /// + /// The that represents the asynchronous operation, containing the a flag indicating if a two + /// factor token could be generated by this provider for the specified and . + /// The task will return true if a two factor authentication token could be generated, otherwise false. + /// Task CanGenerateTwoFactorTokenAsync(UserManager manager, TUser user); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserTwoFactorStore.cs b/src/Microsoft.AspNet.Identity/IUserTwoFactorStore.cs index f170820792..6afd18488c 100644 --- a/src/Microsoft.AspNet.Identity/IUserTwoFactorStore.cs +++ b/src/Microsoft.AspNet.Identity/IUserTwoFactorStore.cs @@ -7,26 +7,31 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Stores whether two factor is enabled for a user + /// Provides an abstraction to store a flag indicating whether a user has two factor authentication enabled. /// - /// + /// The type encapsulating a user. public interface IUserTwoFactorStore : IUserStore where TUser : class { /// - /// Sets whether two factor is enabled for the user + /// Sets a flag indicating whether the specified has two factor authentication enabled or not, + /// as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose two factor authentication enabled status should be set. + /// A flag indicating whether the specified has two factor authentication enabled. + /// The used to propagate notifications that the operation should be canceled. + /// The that represents the asynchronous operation. Task SetTwoFactorEnabledAsync(TUser user, bool enabled, CancellationToken cancellationToken); /// - /// Returns whether two factor is enabled for the user + /// Returns a flag indicating whether the specified has two factor authentication enabled or not, + /// as an asynchronous operation. /// - /// - /// - /// + /// The user whose two factor authentication enabled status should be set. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing a flag indicating whether the specified + /// has two factor authentication enabled or not. + /// Task GetTwoFactorEnabledAsync(TUser user, CancellationToken cancellationToken); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IUserValidator.cs b/src/Microsoft.AspNet.Identity/IUserValidator.cs index 0e2a6656ee..dc4511e9e2 100644 --- a/src/Microsoft.AspNet.Identity/IUserValidator.cs +++ b/src/Microsoft.AspNet.Identity/IUserValidator.cs @@ -7,18 +7,17 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Used to validate a user + /// Provides an abstraction for user validation. /// - /// + /// The type encapsulating a user. public interface IUserValidator where TUser : class { /// - /// ValidateAsync the user + /// Validates the specified as an asynchronous operation. /// - /// - /// - /// - /// + /// The that can be used to retrieve user properties. + /// The user to validate. + /// The that represents the asynchronous operation, containing the of the validation operation. Task ValidateAsync(UserManager manager, TUser user); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IdentityBuilder.cs b/src/Microsoft.AspNet.Identity/IdentityBuilder.cs index 14bff378cf..bfbbbcb78d 100644 --- a/src/Microsoft.AspNet.Identity/IdentityBuilder.cs +++ b/src/Microsoft.AspNet.Identity/IdentityBuilder.cs @@ -6,8 +6,17 @@ using Microsoft.Framework.DependencyInjection; namespace Microsoft.AspNet.Identity { + /// + /// Helper functions for configuring identity services. + /// public class IdentityBuilder { + /// + /// Creates a new instance of . + /// + /// The to use for the users. + /// The to use for the roles. + /// The to attach to. public IdentityBuilder(Type user, Type role, IServiceCollection services) { UserType = user; @@ -15,8 +24,29 @@ namespace Microsoft.AspNet.Identity Services = services; } + /// + /// Gets the used for users. + /// + /// + /// The used for users. + /// public Type UserType { get; private set; } + + + /// + /// Gets the used for roles. + /// + /// + /// The used for roles. + /// public Type RoleType { get; private set; } + + /// + /// Gets the services are attached to. + /// + /// + /// The services are attached to. + /// public IServiceCollection Services { get; private set; } private IdentityBuilder AddScoped(Type serviceType, Type concreteType) @@ -25,47 +55,91 @@ namespace Microsoft.AspNet.Identity return this; } + /// + /// Adds an for the . + /// + /// The user type to validate. + /// The . public virtual IdentityBuilder AddUserValidator() where T : class { return AddScoped(typeof(IUserValidator<>).MakeGenericType(UserType), typeof(T)); } + /// + /// Adds an for the . + /// + /// The role type to validate. + /// The . public virtual IdentityBuilder AddRoleValidator() where T : class { return AddScoped(typeof(IRoleValidator<>).MakeGenericType(RoleType), typeof(T)); } + /// + /// Adds an . + /// + /// The type of the error describer. + /// The . public virtual IdentityBuilder AddErrorDescriber() where TDescriber : IdentityErrorDescriber { Services.AddScoped(); return this; } + /// + /// Adds an for the . + /// + /// The user type whose password will be validated. + /// The . public virtual IdentityBuilder AddPasswordValidator() where T : class { return AddScoped(typeof(IPasswordValidator<>).MakeGenericType(UserType), typeof(T)); } + /// + /// Adds an for the . + /// + /// The user type whose password will be validated. + /// The . public virtual IdentityBuilder AddUserStore() where T : class { return AddScoped(typeof(IUserStore<>).MakeGenericType(UserType), typeof(T)); } + /// + /// Adds a for the . + /// + /// The role type held in the store. + /// The . public virtual IdentityBuilder AddRoleStore() where T : class { return AddScoped(typeof(IRoleStore<>).MakeGenericType(RoleType), typeof(T)); } + /// + /// Adds a token provider. + /// + /// The type of the token provider to add. + /// The . public virtual IdentityBuilder AddTokenProvider() where TProvider : class { return AddTokenProvider(typeof(TProvider)); } + /// + /// Adds a token provider for the . + /// + /// The type of the to add. + /// The . public virtual IdentityBuilder AddTokenProvider(Type provider) { return AddScoped(typeof(IUserTokenProvider<>).MakeGenericType(UserType), provider); } + /// + /// Adds the default token providers. + /// + /// The . public virtual IdentityBuilder AddDefaultTokenProviders() { Services.Configure(options => @@ -78,11 +152,21 @@ namespace Microsoft.AspNet.Identity .AddTokenProvider(typeof(EmailTokenProvider<>).MakeGenericType(UserType)); } + /// + /// Adds a for the . + /// + /// The type of the user manager to add. + /// The . public virtual IdentityBuilder AddUserManager() where TUserManager : class { return AddScoped(typeof(UserManager<>).MakeGenericType(UserType), typeof(TUserManager)); } + /// + /// Adds a for the . + /// + /// The type of the role manager to add. + /// The . public virtual IdentityBuilder AddRoleManager() where TRoleManager : class { return AddScoped(typeof(RoleManager<>).MakeGenericType(RoleType), typeof(TRoleManager)); diff --git a/src/Microsoft.AspNet.Identity/IdentityError.cs b/src/Microsoft.AspNet.Identity/IdentityError.cs index d129ae70f0..8e6e377a10 100644 --- a/src/Microsoft.AspNet.Identity/IdentityError.cs +++ b/src/Microsoft.AspNet.Identity/IdentityError.cs @@ -3,9 +3,25 @@ namespace Microsoft.AspNet.Identity { + /// + /// Encapsulates an error from the identity subsystem. + /// public class IdentityError { + /// + /// Gets or sets the code for this error. + /// + /// + /// The code for this error. + /// public string Code { get; set; } + + /// + /// Gets or sets the description for this error. + /// + /// + /// The description for this error. + /// public string Description { get; set; } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IdentityErrorDescriber.cs b/src/Microsoft.AspNet.Identity/IdentityErrorDescriber.cs index 1561a34ddb..dc56166056 100644 --- a/src/Microsoft.AspNet.Identity/IdentityErrorDescriber.cs +++ b/src/Microsoft.AspNet.Identity/IdentityErrorDescriber.cs @@ -3,8 +3,18 @@ namespace Microsoft.AspNet.Identity { + /// + /// Service to enable localization for application facing identity errors. + /// + /// + /// These errors are returned to controllers and are generally used as display messages to end users. + /// public class IdentityErrorDescriber { + /// + /// Returns the default . + /// + /// The default , public virtual IdentityError DefaultError() { return new IdentityError @@ -13,6 +23,11 @@ namespace Microsoft.AspNet.Identity Description = Resources.DefaultError }; } + + /// + /// Returns an indicating a concurrency failure. + /// + /// An indicating a concurrency failure. public virtual IdentityError ConcurrencyFailure() { return new IdentityError @@ -22,6 +37,10 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a password mismatch. + /// + /// An indicating a password mismatch. public virtual IdentityError PasswordMismatch() { return new IdentityError @@ -31,6 +50,10 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating an invalid token. + /// + /// An indicating an invalid token. public virtual IdentityError InvalidToken() { return new IdentityError @@ -40,6 +63,10 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating an external login is already associated with an account. + /// + /// An indicating an external login is already associated with an account. public virtual IdentityError LoginAlreadyAssociated() { return new IdentityError @@ -49,15 +76,25 @@ namespace Microsoft.AspNet.Identity }; } - public virtual IdentityError InvalidUserName(string name) + /// + /// Returns an indicating the specified user is invalid. + /// + /// The user name that is invalid. + /// An indicating the specified user is invalid. + public virtual IdentityError InvalidUserName(string userName) { return new IdentityError { Code = nameof(InvalidUserName), - Description = Resources.FormatInvalidUserName(name) + Description = Resources.FormatInvalidUserName(userName) }; } + /// + /// Returns an indicating the specified is invalid. + /// + /// The email that is invalid. + /// An indicating the specified is invalid. public virtual IdentityError InvalidEmail(string email) { return new IdentityError @@ -67,15 +104,25 @@ namespace Microsoft.AspNet.Identity }; } - public virtual IdentityError DuplicateUserName(string name) + /// + /// Returns an indicating the specified already exists. + /// + /// The user name that already exists. + /// An indicating the specified already exists. + public virtual IdentityError DuplicateUserName(string userName) { return new IdentityError { Code = nameof(DuplicateUserName), - Description = Resources.FormatDuplicateUserName(name) + Description = Resources.FormatDuplicateUserName(userName) }; } + /// + /// Returns an indicating the specified is already associated with an account. + /// + /// The email that is already associated with an account. + /// An indicating the specified is already associated with an account. public virtual IdentityError DuplicateEmail(string email) { return new IdentityError @@ -85,24 +132,38 @@ namespace Microsoft.AspNet.Identity }; } - public virtual IdentityError InvalidRoleName(string name) + /// + /// Returns an indicating the specified name is invalid. + /// + /// The invalid role. + /// An indicating the specific role name is invalid. + public virtual IdentityError InvalidRoleName(string role) { return new IdentityError { Code = nameof(InvalidRoleName), - Description = Resources.FormatInvalidRoleName(name) + Description = Resources.FormatInvalidRoleName(role) }; } - public virtual IdentityError DuplicateRoleName(string name) + /// + /// Returns an indicating the specified name already exists. + /// + /// The duplicate role. + /// An indicating the specific role name already exists. + public virtual IdentityError DuplicateRoleName(string role) { return new IdentityError { Code = nameof(DuplicateRoleName), - Description = Resources.FormatDuplicateRoleName(name) + Description = Resources.FormatDuplicateRoleName(role) }; } + /// + /// Returns an indicating a user already has a password. + /// + /// An indicating a user already has a password. public virtual IdentityError UserAlreadyHasPassword() { return new IdentityError @@ -112,6 +173,10 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating user lockout is not enabled. + /// + /// An indicating user lockout is not enabled.. public virtual IdentityError UserLockoutNotEnabled() { return new IdentityError @@ -121,6 +186,11 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a user is already in the specified . + /// + /// The duplicate role. + /// An indicating a user is already in the specified . public virtual IdentityError UserAlreadyInRole(string role) { return new IdentityError @@ -130,6 +200,11 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a user is not in the specified . + /// + /// The duplicate role. + /// An indicating a user is not in the specified . public virtual IdentityError UserNotInRole(string role) { return new IdentityError @@ -139,6 +214,11 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a password of the specified does not meet the minimum length requirements. + /// + /// The length that is not long enough. + /// An indicating a password of the specified does not meet the minimum length requirements. public virtual IdentityError PasswordTooShort(int length) { return new IdentityError @@ -148,6 +228,11 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a password entered does not contain a non-alphanumeric character, which is required by the password policy. + /// + /// The length that is not long enough. + /// An indicating a password entered does not contain a non-alphanumeric character. public virtual IdentityError PasswordRequiresNonLetterAndDigit() { return new IdentityError @@ -157,6 +242,11 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a password entered does not contain a numeric character, which is required by the password policy. + /// + /// The length that is not long enough. + /// An indicating a password entered does not contain a numeric character. public virtual IdentityError PasswordRequiresDigit() { return new IdentityError @@ -166,6 +256,11 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a password entered does not contain a lower case letter, which is required by the password policy. + /// + /// The length that is not long enough. + /// An indicating a password entered does not contain a lower case letter. public virtual IdentityError PasswordRequiresLower() { return new IdentityError @@ -175,6 +270,11 @@ namespace Microsoft.AspNet.Identity }; } + /// + /// Returns an indicating a password entered does not contain an upper case letter, which is required by the password policy. + /// + /// The length that is not long enough. + /// An indicating a password entered does not contain an upper case letter. public virtual IdentityError PasswordRequiresUpper() { return new IdentityError diff --git a/src/Microsoft.AspNet.Identity/IdentityLogger.cs b/src/Microsoft.AspNet.Identity/IdentityLogger.cs index cc9f8ada71..84210620ee 100644 --- a/src/Microsoft.AspNet.Identity/IdentityLogger.cs +++ b/src/Microsoft.AspNet.Identity/IdentityLogger.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; @@ -7,6 +7,12 @@ using Microsoft.Framework.Logging; namespace Microsoft.AspNet.Identity.Logging { + /// + /// Extensions to make logging easier. + /// + /// + /// To be deleted before RTM. + /// public static class IdentityLoggerExtensions { private static TResult Log(this ILogger logger, TResult result, Func getLevel, diff --git a/src/Microsoft.AspNet.Identity/IdentityOptions.cs b/src/Microsoft.AspNet.Identity/IdentityOptions.cs index 31ef2bfd1b..932d4e6b1c 100644 --- a/src/Microsoft.AspNet.Identity/IdentityOptions.cs +++ b/src/Microsoft.AspNet.Identity/IdentityOptions.cs @@ -6,37 +6,129 @@ using System; namespace Microsoft.AspNet.Identity { /// - /// Configuration for identity + /// Represents all the options you can used to configure the identity system. /// public class IdentityOptions { + /// + /// Gets or sets the for the identity system. + /// + /// + /// The for the identity system. + /// public ClaimsIdentityOptions ClaimsIdentity { get; set; } = new ClaimsIdentityOptions(); + /// + /// Gets or sets the for the identity system. + /// + /// + /// The for the identity system. + /// public UserOptions User { get; set; } = new UserOptions(); + /// + /// Gets or sets the for the identity system. + /// + /// + /// The for the identity system. + /// public PasswordOptions Password { get; set; } = new PasswordOptions(); + /// + /// Gets or sets the for the identity system. + /// + /// + /// The for the identity system. + /// public LockoutOptions Lockout { get; set; } = new LockoutOptions(); + /// + /// Gets or sets the for the identity system. + /// + /// + /// The for the identity system. + /// public SignInOptions SignIn { get; set; } = new SignInOptions(); + /// + /// Gets or sets the after which security stamps are re-validated. + /// + /// + /// The after which security stamps are re-validated. + /// public TimeSpan SecurityStampValidationInterval { get; set; } = TimeSpan.FromMinutes(30); + /// + /// Gets or sets the used to generate tokens used in account confirmation emails. + /// + /// + /// The used to generate tokens used in account confirmation emails. + /// public string EmailConfirmationTokenProvider { get; set; } = Resources.DefaultTokenProvider; + /// + /// Gets or sets the used to generate tokens used in password reset emails. + /// + /// + /// The used to generate tokens used in password reset emails. + /// public string PasswordResetTokenProvider { get; set; } = Resources.DefaultTokenProvider; + /// + /// Gets or sets the used to generate tokens used in email change confirmation emails. + /// + /// + /// The used to generate tokens used in email change confirmation emails. + /// public string ChangeEmailTokenProvider { get; set; } = Resources.DefaultTokenProvider; + /// + /// Gets or sets the scheme used to identify application authentication cookies. + /// + /// The scheme used to identify application authentication cookies. public static string ApplicationCookieAuthenticationScheme { get; set; } = typeof(IdentityOptions).Namespace + ".Application"; + + /// + /// Gets or sets the scheme used to identify external authentication cookies. + /// + /// The scheme used to identify external authentication cookies. public static string ExternalCookieAuthenticationScheme { get; set; } = typeof(IdentityOptions).Namespace + ".External"; + + /// + /// Gets or sets the scheme used to identify Two Factor authentication cookies for round tripping user identities. + /// + /// The scheme used to identify user identity 2fa authentication cookies. public static string TwoFactorUserIdCookieAuthenticationScheme { get; set; } = typeof(IdentityOptions).Namespace + ".TwoFactorUserId"; - public static string TwoFactorRememberMeCookieAuthenticationScheme { get; set; } = typeof(IdentityOptions).Namespace + ".TwoFactorRemeberMe"; + + /// + /// Gets or sets the scheme used to identify Two Factor authentication cookies for saving the Remember Me state. + /// + /// The scheme used to identify remember me application authentication cookies. + public static string TwoFactorRememberMeCookieAuthenticationScheme { get; set; } = typeof(IdentityOptions).Namespace + ".TwoFactorRememberMe"; + + /// + /// Gets or sets the authentication type used when constructing an from an application cookie. + /// + /// The authentication type used when constructing an from an application cookie. public static string ApplicationCookieAuthenticationType { get; set; } = typeof(IdentityOptions).Namespace + ".Application.AuthType"; - public static string ExternalCookieAuthenticationType { get; set; } = typeof(IdentityOptions).Namespace + ".External.AuthType"; - public static string TwoFactorUserIdCookieAuthenticationType { get; set; } = typeof(IdentityOptions).Namespace + ".TwoFactorUserId.AuthType"; - public static string TwoFactorRememberMeCookieAuthenticationType { get; set; } = typeof(IdentityOptions).Namespace + ".TwoFactorRemeberMe.AuthType"; + /// + /// Gets or sets the authentication type used when constructing an from an external identity cookie. + /// + /// The authentication type used when constructing an from an external identity cookie. + public static string ExternalCookieAuthenticationType { get; set; } = typeof(IdentityOptions).Namespace + ".External.AuthType"; + + /// + /// Gets or sets the authentication type used when constructing an from an two factor authentication cookie. + /// + /// The authentication type used when constructing an from an two factor authentication cookie. + public static string TwoFactorUserIdCookieAuthenticationType { get; set; } = typeof(IdentityOptions).Namespace + ".TwoFactorUserId.AuthType"; + + /// + /// Gets or sets the authentication type used when constructing an from an two factor remember me authentication cookie. + /// + /// The authentication type used when constructing an from an two factor remember me authentication cookie. + public static string TwoFactorRememberMeCookieAuthenticationType { get; set; } = typeof(IdentityOptions).Namespace + ".TwoFactorRemeberMe.AuthType"; } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/IdentityResult.cs b/src/Microsoft.AspNet.Identity/IdentityResult.cs index 55148d1667..1b5c9a89be 100644 --- a/src/Microsoft.AspNet.Identity/IdentityResult.cs +++ b/src/Microsoft.AspNet.Identity/IdentityResult.cs @@ -8,33 +8,37 @@ using Microsoft.Framework.Logging; namespace Microsoft.AspNet.Identity { /// - /// Represents the result of an identity operation + /// Represents the result of an identity operation. /// public class IdentityResult { private static readonly IdentityResult _success = new IdentityResult { Succeeded = true }; private List _errors = new List(); + /// - /// True if the operation was successful + /// Flag indicating whether if the operation succeeded or not. /// + /// True if the operation succeeded, otherwise false. public bool Succeeded { get; protected set; } /// - /// List of errors + /// An of s containing an errors + /// that occurred during the identity operation. /// + /// An of s. public IEnumerable Errors => _errors; /// - /// Static success result + /// Returns an indicating a successful identity operation. /// - /// + /// An indicating a successful operation. public static IdentityResult Success => _success; /// - /// Failed helper method + /// Creates an indicating a failed identity operation, with a list of if applicable. /// - /// - /// + /// An optional array of s which caused the operation to fail. + /// An indicating a failed identity operation, with a list of if applicable. public static IdentityResult Failed(params IdentityError[] errors) { var result = new IdentityResult { Succeeded = false }; @@ -46,9 +50,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Return string representation of IdentityResult + /// Converts the value of the current object to its equivalent string representation. /// - /// "Succedded", if result is suceeded else "Failed:error codes" + /// A string representation of the current object. + /// + /// If the operation was successful the ToString() will return "Succeeded" otherwise it returned + /// "Failed : " followed by a comma delimited list of error codes from its collection, if any. + /// public override string ToString() { return Succeeded ? @@ -57,9 +65,9 @@ namespace Microsoft.AspNet.Identity } /// - /// Get the level to log this result + /// Gets the for use with any instance. /// - /// LogLevel to log + /// The for this result. public virtual LogLevel GetLogLevel() { return Succeeded ? LogLevel.Verbose : LogLevel.Warning; diff --git a/src/Microsoft.AspNet.Identity/IdentityServiceCollectionExtensions.cs b/src/Microsoft.AspNet.Identity/IdentityServiceCollectionExtensions.cs index a78b6fd253..639d87bb9a 100644 --- a/src/Microsoft.AspNet.Identity/IdentityServiceCollectionExtensions.cs +++ b/src/Microsoft.AspNet.Identity/IdentityServiceCollectionExtensions.cs @@ -11,34 +11,70 @@ using Microsoft.Framework.Configuration; namespace Microsoft.Framework.DependencyInjection { + /// + /// Contains extension methods to for configuring identity services. + /// public static class IdentityServiceCollectionExtensions { - public static IServiceCollection ConfigureIdentity(this IServiceCollection services, Action configure) + /// + /// Configures a set of for the application + /// + /// The services available in the application. + /// An action to configure the . + /// The instance this method extends. + public static IServiceCollection ConfigureIdentity(this IServiceCollection services, Action setupAction) { - return services.Configure(configure); + return services.Configure(setupAction); } + /// + /// Configures a set of for the application + /// + /// The services available in the application. + /// The configuration for the . + /// The instance this method extends. public static IServiceCollection ConfigureIdentity(this IServiceCollection services, IConfiguration config) { return services.Configure(config); } - public static IServiceCollection ConfigureIdentityApplicationCookie(this IServiceCollection services, Action configureOptions) + /// + /// Configures a set of for the application + /// + /// The services available in the application. + /// An action to configure the . + /// The instance this method extends. + public static IServiceCollection ConfigureIdentityApplicationCookie(this IServiceCollection services, Action setupAction) { - return services.ConfigureCookieAuthentication(configureOptions, IdentityOptions.ApplicationCookieAuthenticationScheme); + return services.ConfigureCookieAuthentication(setupAction, IdentityOptions.ApplicationCookieAuthenticationScheme); } + /// + /// Adds the default identity system configuration for the specified User and Role types. + /// + /// The type representing a User in the system. + /// The type representing a Role in the system. + /// The services available in the application. + /// An for creating and configuring the identity system. public static IdentityBuilder AddIdentity( this IServiceCollection services) where TUser : class where TRole : class { - return services.AddIdentity(configureOptions: null); + return services.AddIdentity(setupAction: null); } + /// + /// Adds and configures the identity system for the specified User and Role types. + /// + /// The type representing a User in the system. + /// The type representing a Role in the system. + /// The services available in the application. + /// An action to configure the . + /// An for creating and configuring the identity system. public static IdentityBuilder AddIdentity( this IServiceCollection services, - Action configureOptions) + Action setupAction) where TUser : class where TRole : class { @@ -60,9 +96,9 @@ namespace Microsoft.Framework.DependencyInjection services.TryAdd(ServiceDescriptor.Scoped, SignInManager>()); services.TryAdd(ServiceDescriptor.Scoped, RoleManager>()); - if (configureOptions != null) + if (setupAction != null) { - services.ConfigureIdentity(configureOptions); + services.ConfigureIdentity(setupAction); } services.Configure(options => { diff --git a/src/Microsoft.AspNet.Identity/LockoutOptions.cs b/src/Microsoft.AspNet.Identity/LockoutOptions.cs index 89d9a879a7..f8951105a5 100644 --- a/src/Microsoft.AspNet.Identity/LockoutOptions.cs +++ b/src/Microsoft.AspNet.Identity/LockoutOptions.cs @@ -5,21 +5,37 @@ using System; namespace Microsoft.AspNet.Identity { + /// + /// Options for configuring user lockout. + /// public class LockoutOptions { /// - /// If true, will enable user lockout when users are created + /// Gets or sets a flag indicating whether users are locked out upon creation. /// + /// + /// True if a newly created user is locked out, otherwise false. + /// + /// + /// Defaults to false. + /// public bool EnabledByDefault { get; set; } = false; /// - /// Number of access attempts allowed for a user before lockout (if enabled) + /// Gets or sets the number of failed access attempts allowed before a user is locked out, + /// assuming lock out is enabled. /// + /// + /// The number of failed access attempts allowed before a user is locked out, if lockout is enabled. + /// + /// Defaults to 5 failed attempts before an account is locked out. public int MaxFailedAccessAttempts { get; set; } = 5; /// - /// Default amount of time an user is locked out for after MaxFailedAccessAttempsBeforeLockout is reached + /// Gets or sets the a user is locked out for when a lockout occurs. /// + /// The a user is locked out for when a lockout occurs. + /// Defaults to 5 minutes. public TimeSpan DefaultLockoutTimeSpan { get; set; } = TimeSpan.FromMinutes(5); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/PasswordHasher.cs b/src/Microsoft.AspNet.Identity/PasswordHasher.cs index ed5c3db325..31397802d9 100644 --- a/src/Microsoft.AspNet.Identity/PasswordHasher.cs +++ b/src/Microsoft.AspNet.Identity/PasswordHasher.cs @@ -10,8 +10,9 @@ using Microsoft.Framework.OptionsModel; namespace Microsoft.AspNet.Identity { /// - /// Implements password hashing methods + /// Implements the standard Identity password hashing. /// + /// The type used to represent a user. public class PasswordHasher : IPasswordHasher where TUser : class { /* ======================= @@ -34,9 +35,9 @@ namespace Microsoft.AspNet.Identity private readonly RandomNumberGenerator _rng; /// - /// Constructs a PasswordHasher using the specified options + /// Creates a new instance of . /// - /// + /// The options for this instance. public PasswordHasher(IOptions optionsAccessor = null) { var options = optionsAccessor?.Options ?? new PasswordHasherOptions(); @@ -84,11 +85,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Hash a password + /// Returns a hashed representation of the supplied for the specified . /// - /// - /// - /// + /// The user whose password is to be hashed. + /// The password to hash. + /// A hashed representation of the supplied for the specified . public virtual string HashPassword(TUser user, string password) { if (password == null) @@ -160,12 +161,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Verify that a password matches the hashedPassword + /// Returns a indicating the result of a password hash comparison. /// - /// - /// - /// - /// + /// The user whose password should be verified. + /// The hash value for a user's stored password. + /// The password supplied for comparison. + /// A indicating the result of a password hash comparison. + /// Implementations of this method should be time consistent. public virtual PasswordVerificationResult VerifyHashedPassword(TUser user, string hashedPassword, string providedPassword) { if (hashedPassword == null) diff --git a/src/Microsoft.AspNet.Identity/PasswordHasherCompatibilityMode.cs b/src/Microsoft.AspNet.Identity/PasswordHasherCompatibilityMode.cs index 7d4c1e4ae3..a7f03e998e 100644 --- a/src/Microsoft.AspNet.Identity/PasswordHasherCompatibilityMode.cs +++ b/src/Microsoft.AspNet.Identity/PasswordHasherCompatibilityMode.cs @@ -4,17 +4,17 @@ namespace Microsoft.AspNet.Identity { /// - /// An enum that describes the format used for hashing passwords. + /// Specifies the format used for hashing passwords. /// public enum PasswordHasherCompatibilityMode { /// - /// Hashes passwords in a way that is compatible with ASP.NET Identity versions 1 and 2. + /// Indicates hashing passwords in a way that is compatible with ASP.NET Identity versions 1 and 2. /// IdentityV2, /// - /// Hashes passwords in a way that is compatible with ASP.NET Identity version 3. + /// Indicates hashing passwords in a way that is compatible with ASP.NET Identity version 3. /// IdentityV3 } diff --git a/src/Microsoft.AspNet.Identity/PasswordHasherOptions.cs b/src/Microsoft.AspNet.Identity/PasswordHasherOptions.cs index 25794f9f85..44a96ef33a 100644 --- a/src/Microsoft.AspNet.Identity/PasswordHasherOptions.cs +++ b/src/Microsoft.AspNet.Identity/PasswordHasherOptions.cs @@ -6,25 +6,31 @@ using System.Security.Cryptography; namespace Microsoft.AspNet.Identity { /// - /// Allows configuring how passwords are hashed. + /// Specifies options for password hashing. /// public class PasswordHasherOptions { private static readonly RandomNumberGenerator _defaultRng = RandomNumberGenerator.Create(); // secure PRNG /// - /// Specifies the compatibility mode to use when hashing passwords. + /// Gets or sets the compatibility mode used when hashing passwords. /// + /// + /// The compatibility mode used when hashing passwords. + /// /// /// The default compatibility mode is 'ASP.NET Identity version 3'. /// public PasswordHasherCompatibilityMode CompatibilityMode { get; set; } = PasswordHasherCompatibilityMode.IdentityV3; /// - /// Specifies the number of iterations to use when hashing passwords using PBKDF2. + /// Gets or sets the number of iterations used when hashing passwords using PBKDF2. /// + /// + /// The number of iterations used when hashing passwords using PBKDF2. + /// /// - /// This value is only used when the compatibiliy mode is set to 'V3'. + /// This value is only used when the compatibility mode is set to 'V3'. /// The value must be a positive integer. The default value is 10,000. /// public int IterationCount { get; set; } = 10000; diff --git a/src/Microsoft.AspNet.Identity/PasswordOptions.cs b/src/Microsoft.AspNet.Identity/PasswordOptions.cs index 39e7808b8c..ef61fbd252 100644 --- a/src/Microsoft.AspNet.Identity/PasswordOptions.cs +++ b/src/Microsoft.AspNet.Identity/PasswordOptions.cs @@ -3,31 +3,53 @@ namespace Microsoft.AspNet.Identity { + /// + /// Specifies options for password requirements. + /// public class PasswordOptions { /// - /// Minimum required length + /// Gets or sets the minimum length a password must be. /// + /// + /// This defaults to 6. + /// public int RequiredLength { get; set; } = 6; /// - /// Require a non letter or digit character + /// Gets or sets a flag indicating if passwords must contain a digit or other non-alphabetical character. /// + /// True if passwords must contain a digit or other non-alphabetical character, otherwise false. + /// + /// This defaults to true. + /// public bool RequireNonLetterOrDigit { get; set; } = true; /// - /// Require a lower case letter ('a' - 'z') + /// Gets or sets a flag indicating if passwords must contain a lower case ASCII character. /// + /// True if passwords must contain a lower case ASCII character. + /// + /// This defaults to true. + /// public bool RequireLowercase { get; set; } = true; /// - /// Require an upper case letter ('A' - 'Z') + /// Gets or sets a flag indicating if passwords must contain a upper case ASCII character. /// + /// True if passwords must contain a upper case ASCII character. + /// + /// This defaults to true. + /// public bool RequireUppercase { get; set; } = true; /// - /// Require a digit ('0' - '9') + /// Gets or sets a flag indicating if passwords must contain a digit. /// + /// True if passwords must contain a digit. + /// + /// This defaults to true. + /// public bool RequireDigit { get; set; } = true; } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/PasswordValidator.cs b/src/Microsoft.AspNet.Identity/PasswordValidator.cs index 8efb067027..6cf08804bf 100644 --- a/src/Microsoft.AspNet.Identity/PasswordValidator.cs +++ b/src/Microsoft.AspNet.Identity/PasswordValidator.cs @@ -4,30 +4,38 @@ using System; using System.Collections.Generic; using System.Linq; -using System.Threading; using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Used to validate some basic password policy like length and number of non alphanumerics + /// Provides the default password policy for Identity. /// + /// The type that represents a user. public class PasswordValidator : IPasswordValidator where TUser : class { + /// + /// Constructions a new instance of . + /// + /// The to retrieve error text from. public PasswordValidator(IdentityErrorDescriber errors = null) { Describer = errors ?? new IdentityErrorDescriber(); } + /// + /// Gets the used to supply error text. + /// + /// The used to supply error text. public IdentityErrorDescriber Describer { get; private set; } /// - /// Ensures that the password is of the required length and meets the configured requirements + /// Validates a password as an asynchronous operation. /// - /// - /// - /// - /// + /// The to retrieve the properties from. + /// The user whose password should be validated. + /// The password supplied for validation + /// The task object representing the asynchronous operation. public virtual Task ValidateAsync(UserManager manager, TUser user, string password) { if (password == null) @@ -67,40 +75,40 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the character is a digit between '0' and '9' + /// Returns a flag indicting whether the supplied character is a digit. /// - /// - /// + /// The character to check if it is a digit. + /// True if the character is a digit, otherwise false. public virtual bool IsDigit(char c) { return c >= '0' && c <= '9'; } /// - /// Returns true if the character is between 'a' and 'z' + /// Returns a flag indicting whether the supplied character is a lower case ASCII letter. /// - /// - /// + /// The character to check if it is a lower case ASCII letter. + /// True if the character is a lower case ASCII letter, otherwise false. public virtual bool IsLower(char c) { return c >= 'a' && c <= 'z'; } /// - /// Returns true if the character is between 'A' and 'Z' + /// Returns a flag indicting whether the supplied character is an upper case ASCII letter. /// - /// - /// + /// The character to check if it is an upper case ASCII letter. + /// True if the character is an upper case ASCII letter, otherwise false. public virtual bool IsUpper(char c) { return c >= 'A' && c <= 'Z'; } /// - /// Returns true if the character is upper, lower, or a digit + /// Returns a flag indicting whether the supplied character is an ASCII letter or digit. /// - /// - /// + /// The character to check if it is an ASCII letter or digit. + /// True if the character is an ASCII letter or digit, otherwise false. public virtual bool IsLetterOrDigit(char c) { return IsUpper(c) || IsLower(c) || IsDigit(c); diff --git a/src/Microsoft.AspNet.Identity/PasswordVerificationResult.cs b/src/Microsoft.AspNet.Identity/PasswordVerificationResult.cs index 76485708ee..c998d8e219 100644 --- a/src/Microsoft.AspNet.Identity/PasswordVerificationResult.cs +++ b/src/Microsoft.AspNet.Identity/PasswordVerificationResult.cs @@ -4,22 +4,23 @@ namespace Microsoft.AspNet.Identity { /// - /// Return result for IPasswordHasher + /// Specifies the results for password verification. /// public enum PasswordVerificationResult { /// - /// Password verification failed + /// Indicates password verification failed. /// Failed = 0, /// - /// Success + /// Indicates password verification was successful. /// Success = 1, /// - /// Success but should update and rehash the password + /// Indicates password verification was successful however the password was encoded using a deprecated algorithm + /// and should be rehashed and updated. /// SuccessRehashNeeded = 2 } diff --git a/src/Microsoft.AspNet.Identity/PhoneNumberTokenProvider.cs b/src/Microsoft.AspNet.Identity/PhoneNumberTokenProvider.cs index abf084de8d..f90b3a02f3 100644 --- a/src/Microsoft.AspNet.Identity/PhoneNumberTokenProvider.cs +++ b/src/Microsoft.AspNet.Identity/PhoneNumberTokenProvider.cs @@ -1,22 +1,35 @@ using System; -using System.Globalization; using System.Threading.Tasks; using Microsoft.Framework.OptionsModel; namespace Microsoft.AspNet.Identity { + /// + /// Encapsulations options for a . + /// public class PhoneNumberTokenProviderOptions { + /// + /// Gets or sets the name for the . + /// + /// + /// The name for the . + /// public string Name { get; set; } = "Phone"; } /// - /// TokenProvider that generates tokens from the user's security stamp and notifies a user via their phone number + /// Represents a token provider that generates tokens from a user's security stamp and + /// sends them to the user via their phone number. /// - /// + /// The type encapsulating a user. public class PhoneNumberTokenProvider : TotpSecurityStampBasedTokenProvider where TUser : class { + /// + /// Creates a new instance of with the specified . + /// + /// The options to use for the created instance of a . public PhoneNumberTokenProvider(IOptions options) { if (options == null || options.Options == null) @@ -26,16 +39,30 @@ namespace Microsoft.AspNet.Identity Options = options.Options; } + /// + /// Gets the options for this instance of . + /// + /// The options for this instance of . public PhoneNumberTokenProviderOptions Options { get; private set; } + /// + /// Gets the name for this instance of . + /// + /// The name for this instance of . public override string Name { get { return Options.Name; } } /// - /// Returns true if the user has a phone number set + /// Returns a flag indicating whether the token provider can generate a token suitable for two factor authentication token for + /// the specified . /// - /// - /// - /// + /// The that can be used to retrieve user properties. + /// The user a token could be generated for. + /// + /// The that represents the asynchronous operation, containing the a flag indicating if a two + /// factor token could be generated by this provider for the specified and . + /// The task will return true if a two factor authentication token could be generated as the user has + /// a telephone number, otherwise false. + /// public override async Task CanGenerateTwoFactorTokenAsync(UserManager manager, TUser user) { if (manager == null) @@ -47,12 +74,15 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns the phone number of the user for entropy in the token + /// Returns a constant, provider and user unique modifier used for entropy in generated tokens from user information, as an asynchronous operation. /// - /// - /// - /// - /// + /// The purpose the token will be generated for. + /// The that can be used to retrieve user properties. + /// The user a token should be generated for. + /// + /// The that represents the asynchronous operation, containing a constant modifier for the specified + /// and . + /// public override async Task GetUserModifierAsync(string purpose, UserManager manager, TUser user) { if (manager == null) diff --git a/src/Microsoft.AspNet.Identity/PrincipalExtensions.cs b/src/Microsoft.AspNet.Identity/PrincipalExtensions.cs index 229e27e048..73ab8d1537 100644 --- a/src/Microsoft.AspNet.Identity/PrincipalExtensions.cs +++ b/src/Microsoft.AspNet.Identity/PrincipalExtensions.cs @@ -16,7 +16,7 @@ namespace System.Security.Claims /// /// The instance this method extends. /// The Name claim value, or null if the claim is not present. - /// The name claim is identified by . + /// The Name claim is identified by . public static string GetUserName(this ClaimsPrincipal principal) { if (principal == null) @@ -31,7 +31,7 @@ namespace System.Security.Claims /// /// The instance this method extends. /// The User ID claim value, or null if the claim is not present. - /// The name claim is identified by . + /// The User ID claim is identified by . public static string GetUserId(this ClaimsPrincipal principal) { if (principal == null) @@ -59,9 +59,9 @@ namespace System.Security.Claims /// /// Returns the value for the first claim of the specified type otherwise null the claim is not present. /// - /// The instance this method extends. + /// The instance this method extends. /// The claim type whose first value should be returned. - /// The value of the first instance of the specifed claim type, or null if the claim is not present. + /// The value of the first instance of the specified claim type, or null if the claim is not present. public static string FindFirstValue(this ClaimsPrincipal principal, string claimType) { if (principal == null) diff --git a/src/Microsoft.AspNet.Identity/RoleManager.cs b/src/Microsoft.AspNet.Identity/RoleManager.cs index 0aafbca555..2587bf0d86 100644 --- a/src/Microsoft.AspNet.Identity/RoleManager.cs +++ b/src/Microsoft.AspNet.Identity/RoleManager.cs @@ -16,23 +16,24 @@ using Microsoft.Framework.Logging; namespace Microsoft.AspNet.Identity { /// - /// Exposes role related api which will automatically save changes to the RoleStore + /// Provides the APIs for managing roles in a persistence store. /// - /// + /// The type encapsulating a role. public class RoleManager : IDisposable where TRole : class { private bool _disposed; private readonly HttpContext _context; + private CancellationToken CancellationToken => _context?.RequestAborted ?? CancellationToken.None; /// - /// Constructor + /// Constructs a new instance of . /// - /// The IRoleStore commits changes via the UpdateAsync/CreateAsync methods - /// IEnumerable of role validators - /// user property normalizers - /// IdentityErrorDescribers - /// Logger for RoleManager - /// HttpContext accessor object + /// The persistence store the manager will operate over. + /// A collection of validators for roles. + /// The normalizer to use when normalizing role names to keys. + /// The used to provider error messages. + /// The logger used to log messages, warnings and errors. + /// The accessor used to access the . public RoleManager(IRoleStore store, IEnumerable> roleValidators, ILookupNormalizer keyNormalizer, @@ -60,33 +61,51 @@ namespace Microsoft.AspNet.Identity } /// - /// Persistence abstraction that the Manager operates against + /// Gets the persistence store this instance operates over. /// + /// The persistence store this instance operates over. protected IRoleStore Store { get; private set; } /// - /// Used for logging results + /// Gets the used to log messages from the manager. /// + /// + /// The used to log messages from the manager. + /// protected internal virtual ILogger Logger { get; set; } /// - /// Used to validate roles before persisting changes + /// Gets a list of validators for roles to call before persistence. /// + /// A list of validators for roles to call before persistence. internal IList> RoleValidators { get; } = new List>(); /// - /// Used to generate public API error messages + /// Gets the used to provider error messages. /// + /// + /// The used to provider error messages. + /// internal IdentityErrorDescriber ErrorDescriber { get; set; } /// - /// Used to normalize user names, role names, emails for uniqueness + /// Gets the normalizer to use when normalizing role names to keys. /// + /// + /// The normalizer to use when normalizing role names to keys. + /// internal ILookupNormalizer KeyNormalizer { get; set; } /// - /// Returns an IQueryable of roles if the store is an IQueryableRoleStore + /// Gets an IQueryable collection of Roles if the persistence store is an , + /// otherwise throws a . /// + /// An IQueryable collection of Roles if the persistence store is an . + /// Thrown if the persistence store is not an . + /// + /// Callers to this property should use to ensure the backing role store supports + /// returning an IQueryable list of roles. + /// public virtual IQueryable Roles { get @@ -101,8 +120,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IQueryableRoleStore + /// Gets a flag indicating whether the underlying persistence store supports returning an collection of roles. /// + /// + /// true if the underlying persistence store supports returning an collection of roles, otherwise false. + /// public virtual bool SupportsQueryableRoles { get @@ -113,8 +135,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserClaimStore + /// Gets a flag indicating whether the underlying persistence store supports s for roles. /// + /// + /// true if the underlying persistence store supports s for roles, otherwise false. + /// public virtual bool SupportsRoleClaims { get @@ -124,36 +149,13 @@ namespace Microsoft.AspNet.Identity } } - private CancellationToken CancellationToken => _context?.RequestAborted ?? CancellationToken.None; - /// - /// Dispose this object + /// Creates the specified in the persistence store, as an asynchronous operation. /// - public void Dispose() - { - Dispose(true); - GC.SuppressFinalize(this); - } - - private async Task ValidateRoleInternal(TRole role) - { - var errors = new List(); - foreach (var v in RoleValidators) - { - var result = await v.ValidateAsync(this, role); - if (!result.Succeeded) - { - errors.AddRange(result.Errors); - } - } - return errors.Count > 0 ? IdentityResult.Failed(errors.ToArray()) : IdentityResult.Success; - } - - /// - /// Create a role - /// - /// - /// + /// The role to create. + /// + /// The that represents the asynchronous operation. + /// public virtual async Task CreateAsync(TRole role) { ThrowIfDisposed(); @@ -175,22 +177,25 @@ namespace Microsoft.AspNet.Identity } /// - /// Update the user's normalized user name + /// Updates the normalized name for the specified , as an asynchronous operation. /// - /// - /// + /// The role whose normalized name needs to be updated. + /// + /// The that represents the asynchronous operation. + /// public virtual async Task UpdateNormalizedRoleNameAsync(TRole role) { var name = await GetRoleNameAsync(role); await Store.SetNormalizedRoleNameAsync(role, NormalizeKey(name), CancellationToken); } - /// - /// Update an existing role + /// Updates the specified , as an asynchronous operation. /// - /// - /// + /// The role to updated. + /// + /// The that represents the asynchronous operation, containing the for the update. + /// public virtual async Task UpdateAsync(TRole role) { ThrowIfDisposed(); @@ -205,22 +210,13 @@ namespace Microsoft.AspNet.Identity } } - private async Task UpdateRoleAsync(TRole role) - { - var result = await ValidateRoleInternal(role); - if (!result.Succeeded) - { - return result; - } - await UpdateNormalizedRoleNameAsync(role); - return await Store.UpdateAsync(role, CancellationToken); - } - /// - /// Delete a role + /// Deletes the specified , as an asynchronous operation. /// - /// - /// + /// The role to delete. + /// + /// The that represents the asynchronous operation, containing the for the delete. + /// public virtual async Task DeleteAsync(TRole role) { ThrowIfDisposed(); @@ -236,10 +232,12 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the role exists + /// Gets a flag indicating whether the specified exists, as an asynchronous operation. /// - /// - /// + /// The role name whose existence should be checked. + /// + /// The that represents the asynchronous operation, containing true if the role name exists, otherwise false. + /// public virtual async Task RoleExistsAsync(string roleName) { ThrowIfDisposed(); @@ -252,21 +250,23 @@ namespace Microsoft.AspNet.Identity } /// - /// Normalize a key (role name) for uniqueness comparisons + /// Gets a normalized representation of the specified . /// - /// - /// + /// The value to normalize. + /// A normalized representation of the specified . public virtual string NormalizeKey(string key) { return (KeyNormalizer == null) ? key : KeyNormalizer.Normalize(key); } - /// - /// Find a role by id + /// Finds the role associated with the specified if any, as an asynchronous operation. /// - /// - /// + /// The role ID whose role should be returned. + /// + /// The that represents the asynchronous operation, containing the role + /// associated with the specified + /// public virtual async Task FindByIdAsync(string roleId) { ThrowIfDisposed(); @@ -274,10 +274,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Return the name of the role + /// Gets the name of the specified , as an asynchronous operation. /// - /// - /// + /// The role whose name should be retrieved. + /// + /// The that represents the asynchronous operation, containing the name of the + /// specified . + /// public virtual async Task GetRoleNameAsync(TRole role) { ThrowIfDisposed(); @@ -285,11 +288,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Set the name of the role + /// Sets the name of the specified , as an asynchronous operation. /// - /// - /// - /// + /// The role whose name should be set. + /// The name to set. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task SetRoleNameAsync(TRole role, string name) { ThrowIfDisposed(); @@ -303,10 +309,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Return the role id for a role + /// Gets the ID of the specified , as an asynchronous operation. /// - /// - /// + /// The role whose ID should be retrieved. + /// + /// The that represents the asynchronous operation, containing the ID of the + /// specified . + /// public virtual async Task GetRoleIdAsync(TRole role) { ThrowIfDisposed(); @@ -314,10 +323,13 @@ namespace Microsoft.AspNet.Identity } /// - /// FindByLoginAsync a role by name + /// Finds the role associated with the specified if any, as an asynchronous operation. /// - /// - /// + /// The name of the role to be returned. + /// + /// The that represents the asynchronous operation, containing the role + /// associated with the specified + /// public virtual async Task FindByNameAsync(string roleName) { ThrowIfDisposed(); @@ -329,23 +341,15 @@ namespace Microsoft.AspNet.Identity return await Store.FindByNameAsync(NormalizeKey(roleName), CancellationToken); } - // IRoleClaimStore methods - private IRoleClaimStore GetClaimStore() - { - var cast = Store as IRoleClaimStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIRoleClaimStore); - } - return cast; - } - /// - /// Add a user claim + /// Adds a claim to a role, as an asynchronous operation. /// - /// - /// - /// + /// The role to add the claim to. + /// The claim to add. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task AddClaimAsync(TRole role, Claim claim) { ThrowIfDisposed(); @@ -367,11 +371,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Remove a user claim + /// Removes a claim from a role, as an asynchronous operation. /// - /// - /// - /// + /// The role to remove the claim from. + /// The claim to add. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task RemoveClaimAsync(TRole role, Claim claim) { ThrowIfDisposed(); @@ -389,10 +396,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Get a role's claims + /// Gets a list of claims associated with the specified , as an asynchronous operation. /// - /// - /// + /// The role whose claims should be returned. + /// + /// The that represents the asynchronous operation, containing the list of s + /// associated with the specified . + /// public virtual async Task> GetClaimsAsync(TRole role) { ThrowIfDisposed(); @@ -404,25 +414,19 @@ namespace Microsoft.AspNet.Identity return await claimStore.GetClaimsAsync(role, CancellationToken); } - protected virtual async Task BeginLoggingScopeAsync(TRole role, [CallerMemberName] string methodName = null) + /// + /// Releases all resources used by the role manager. + /// + public void Dispose() { - var state = Resources.FormatLoggingResultMessageForRole(methodName, await GetRoleIdAsync(role)); - return Logger?.BeginScope(state); - } - - - private void ThrowIfDisposed() - { - if (_disposed) - { - throw new ObjectDisposedException(GetType().Name); - } + Dispose(true); + GC.SuppressFinalize(this); } /// - /// When disposing, actually dipose the store + /// Releases the unmanaged resources used by the role manager and optionally releases the managed resources. /// - /// + /// true to release both managed and unmanaged resources; false to release only unmanaged resources. protected virtual void Dispose(bool disposing) { if (disposing && !_disposed) @@ -431,5 +435,55 @@ namespace Microsoft.AspNet.Identity } _disposed = true; } + + protected virtual async Task BeginLoggingScopeAsync(TRole role, [CallerMemberName] string methodName = null) + { + var state = Resources.FormatLoggingResultMessageForRole(methodName, await GetRoleIdAsync(role)); + return Logger?.BeginScope(state); + } + + private async Task ValidateRoleInternal(TRole role) + { + var errors = new List(); + foreach (var v in RoleValidators) + { + var result = await v.ValidateAsync(this, role); + if (!result.Succeeded) + { + errors.AddRange(result.Errors); + } + } + return errors.Count > 0 ? IdentityResult.Failed(errors.ToArray()) : IdentityResult.Success; + } + + private async Task UpdateRoleAsync(TRole role) + { + var result = await ValidateRoleInternal(role); + if (!result.Succeeded) + { + return result; + } + await UpdateNormalizedRoleNameAsync(role); + return await Store.UpdateAsync(role, CancellationToken); + } + + // IRoleClaimStore methods + private IRoleClaimStore GetClaimStore() + { + var cast = Store as IRoleClaimStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIRoleClaimStore); + } + return cast; + } + + private void ThrowIfDisposed() + { + if (_disposed) + { + throw new ObjectDisposedException(GetType().Name); + } + } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/RoleValidator.cs b/src/Microsoft.AspNet.Identity/RoleValidator.cs index 424642fa49..0f4c94e8b6 100644 --- a/src/Microsoft.AspNet.Identity/RoleValidator.cs +++ b/src/Microsoft.AspNet.Identity/RoleValidator.cs @@ -8,11 +8,15 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// Validates roles before they are saved + /// Provides the default validation of roles. /// - /// + /// The type encapsulating a role. public class RoleValidator : IRoleValidator where TRole : class { + /// + /// Creates a new instance of / + /// + /// The used to provider error messages. public RoleValidator(IdentityErrorDescriber errors = null) { Describer = errors ?? new IdentityErrorDescriber(); @@ -21,12 +25,11 @@ namespace Microsoft.AspNet.Identity private IdentityErrorDescriber Describer { get; set; } /// - /// Validates a role before saving + /// Validates a role as an asynchronous operation. /// - /// - /// - /// - /// + /// The managing the role store. + /// The role to validate. + /// A that represents the of the asynchronous validation. public virtual async Task ValidateAsync(RoleManager manager, TRole role) { if (manager == null) diff --git a/src/Microsoft.AspNet.Identity/SecurityStampValidator.cs b/src/Microsoft.AspNet.Identity/SecurityStampValidator.cs index 5588e8f7b6..62c2ce5565 100644 --- a/src/Microsoft.AspNet.Identity/SecurityStampValidator.cs +++ b/src/Microsoft.AspNet.Identity/SecurityStampValidator.cs @@ -11,13 +11,18 @@ using Microsoft.Framework.OptionsModel; namespace Microsoft.AspNet.Identity { + /// + /// Provides default implementation of validation functions for security stamps. + /// + /// The type encapsulating a user. public class SecurityStampValidator : ISecurityStampValidator where TUser : class { /// - /// Rejects the identity if the stamp changes, and otherwise will sign in a new - /// ClaimsIdentity + /// Validates a security stamp of an identity as an asynchronous operation, and rebuilds the identity if the validation succeeds, otherwise rejects + /// the identity. /// - /// + /// The context containing the and to validate. + /// The that represents the asynchronous validation operation. public virtual async Task ValidateAsync(CookieValidatePrincipalContext context) { var manager = context.HttpContext.RequestServices.GetRequiredService>(); @@ -36,11 +41,17 @@ namespace Microsoft.AspNet.Identity } /// - /// Static helper class used to configure a CookieAuthenticationNotifications to validate a cookie against a user's security - /// stamp + /// Static helper class used to configure a CookieAuthenticationNotifications to validate a cookie against a user's security + /// stamp. /// public static class SecurityStampValidator { + /// + /// Validates a principal against a user's stored security stamp. + /// the identity. + /// + /// The context containing the and to validate. + /// The that represents the asynchronous validation operation. public static Task ValidatePrincipalAsync(CookieValidatePrincipalContext context) { var currentUtc = DateTimeOffset.UtcNow; diff --git a/src/Microsoft.AspNet.Identity/SignInManager.cs b/src/Microsoft.AspNet.Identity/SignInManager.cs index 11bddeb610..39c154a05b 100644 --- a/src/Microsoft.AspNet.Identity/SignInManager.cs +++ b/src/Microsoft.AspNet.Identity/SignInManager.cs @@ -17,11 +17,22 @@ using Microsoft.Framework.OptionsModel; namespace Microsoft.AspNet.Identity { /// - /// Interface that manages SignIn operations for a user + /// Provides the APIs for user sign in. /// - /// + /// The type encapsulating a user. public class SignInManager where TUser : class { + private const string LoginProviderKey = "LoginProvider"; + private const string XsrfKey = "XsrfId"; + + /// + /// Creates a new instance of . + /// + /// An instance of used to retrieve users from and persist users. + /// The accessor used to access the . + /// The factory to use to create claims principals for a user. + /// The accessor used to access the . + /// The logger used to log messages, warnings and errors. public SignInManager(UserManager userManager, IHttpContextAccessor contextAccessor, IUserClaimsPrincipalFactory claimsFactory, @@ -48,15 +59,33 @@ namespace Microsoft.AspNet.Identity Logger = logger; } + /// + /// Gets the used to log messages from the manager. + /// + /// + /// The used to log messages from the manager. + /// protected internal virtual ILogger Logger { get; set; } internal UserManager UserManager { get; set; } internal HttpContext Context { get; set; } internal IUserClaimsPrincipalFactory ClaimsFactory { get; set; } internal IdentityOptions Options { get; set; } - - // Should this be a func? + + /// + /// Creates a for the specified , as an asynchronous operation. + /// + /// The user to create a for. + /// The task object representing the asynchronous operation, containing the ClaimsPrincipal for the specified user. public virtual async Task CreateUserPrincipalAsync(TUser user) => await ClaimsFactory.CreateAsync(user); + /// + /// Returns a flag indicating whether the specified user can sign in. + /// + /// The user whose sign-in status should be returned. + /// + /// The task object representing the asynchronous operation, containing a flag that is true + /// if the specified user can sign-in, otherwise false. + /// public virtual async Task CanSignInAsync(TUser user) { if (Options.SignIn.RequireConfirmedEmail && !(await UserManager.IsEmailConfirmedAsync(user))) @@ -72,11 +101,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Called to regenerate the ApplicationCookie for the user, preserving the existing - /// AuthenticationProperties like rememberMe + /// Regenerates the user's application cookie, whilst preserving the existing + /// AuthenticationProperties like rememberMe, as an asynchronous operation. /// - /// - /// + /// The user whose sign-in cookie should be refreshed. + /// The task object representing the asynchronous operation. public virtual async Task RefreshSignInAsync(TUser user) { var authResult = await Context.Authentication.AuthenticateAsync(IdentityOptions.ApplicationCookieAuthenticationScheme); @@ -85,11 +114,25 @@ namespace Microsoft.AspNet.Identity await SignInAsync(user, properties, authenticationMethod); } + /// + /// Signs in the specified . + /// + /// The user to sign-in. + /// Flag indicating whether the sign-in cookie should persist after the browser is closed. + /// Name of the method used to authenticate the user. + /// The task object representing the asynchronous operation. public virtual Task SignInAsync(TUser user, bool isPersistent, string authenticationMethod = null) { return SignInAsync(user, new AuthenticationProperties { IsPersistent = isPersistent }, authenticationMethod); } + /// + /// Signs in the specified . + /// + /// The user to sign-in. + /// Properties applied to the login and authentication cookie. + /// Name of the method used to authenticate the user. + /// The task object representing the asynchronous operation. public virtual async Task SignInAsync(TUser user, AuthenticationProperties authenticationProperties, string authenticationMethod = null) { var userPrincipal = await CreateUserPrincipalAsync(user); @@ -103,6 +146,9 @@ namespace Microsoft.AspNet.Identity authenticationProperties ?? new AuthenticationProperties()); } + /// + /// Signs the current user out of the application. + /// public virtual void SignOut() { Context.Authentication.SignOut(IdentityOptions.ApplicationCookieAuthenticationScheme); @@ -110,40 +156,14 @@ namespace Microsoft.AspNet.Identity Context.Authentication.SignOut(IdentityOptions.TwoFactorUserIdCookieAuthenticationScheme); } - private async Task IsLockedOut(TUser user) - { - return UserManager.SupportsUserLockout && await UserManager.IsLockedOutAsync(user); - } - - private async Task PreSignInCheck(TUser user) - { - if (!await CanSignInAsync(user)) - { - return SignInResult.NotAllowed; - } - if (await IsLockedOut(user)) - { - return SignInResult.LockedOut; - } - return null; - } - - private Task ResetLockout(TUser user) - { - if (UserManager.SupportsUserLockout) - { - return UserManager.ResetAccessFailedCountAsync(user); - } - return Task.FromResult(0); - } - /// - /// Validates that the claims identity has a security stamp matching the users - /// Returns the user if it matches, null otherwise + /// Validates the security stamp for the specified against + /// the persisted stamp for the , as an asynchronous operation. /// - /// - /// - /// + /// The principal whose stamp should be validated. + /// The ID for the user. + /// The task object representing the asynchronous operation. The task will contain the + /// if the stamp matches the persisted value, otherwise it will return false. public virtual async Task ValidateSecurityStampAsync(ClaimsPrincipal principal, string userId) { var user = await UserManager.FindByIdAsync(userId); @@ -159,6 +179,16 @@ namespace Microsoft.AspNet.Identity return null; } + /// + /// Attempts to sign in the specified and combination + /// as an asynchronous operation. + /// + /// The user to sign in. + /// The password to attempt to sign in with. + /// Flag indicating whether the sign-in cookie should persist after the browser is closed. + /// Flag indicating if the user account should be locked if the sign in fails. + /// The task object representing the asynchronous operation containing the + /// for the sign-in attempt. public virtual async Task PasswordSignInAsync(TUser user, string password, bool isPersistent, bool shouldLockout) { @@ -197,6 +227,16 @@ namespace Microsoft.AspNet.Identity } } + /// + /// Attempts to sign in the specified and combination + /// as an asynchronous operation. + /// + /// The user name to sign in. + /// The password to attempt to sign in with. + /// Flag indicating whether the sign-in cookie should persist after the browser is closed. + /// Flag indicating if the user account should be locked if the sign in fails. + /// The task object representing the asynchronous operation containing the + /// for the sign-in attempt. public virtual async Task PasswordSignInAsync(string userName, string password, bool isPersistent, bool shouldLockout) { @@ -209,21 +249,15 @@ namespace Microsoft.AspNet.Identity return await PasswordSignInAsync(user, password, isPersistent, shouldLockout); } - private static ClaimsIdentity CreateIdentity(TwoFactorAuthenticationInfo info) - { - if (info == null) - { - return null; - } - var identity = new ClaimsIdentity(IdentityOptions.TwoFactorUserIdCookieAuthenticationType); - identity.AddClaim(new Claim(ClaimTypes.Name, info.UserId)); - if (info.LoginProvider != null) - { - identity.AddClaim(new Claim(ClaimTypes.AuthenticationMethod, info.LoginProvider)); - } - return identity; - } - + /// + /// Returns a flag indicating if the current client browser has been remembered by two factor authentication + /// for the user attempting to login, as an asynchronous operation. + /// + /// The user attempting to login. + /// + /// The task object representing the asynchronous operation containing true if the browser has been remembered + /// for the current user. + /// public virtual async Task IsTwoFactorClientRememberedAsync(TUser user) { var userId = await UserManager.GetUserIdAsync(user); @@ -231,6 +265,12 @@ namespace Microsoft.AspNet.Identity return (result?.Principal != null && result.Principal.FindFirstValue(ClaimTypes.Name) == userId); } + /// + /// Sets a flag on the browser to indicate the user has selected "Remember this browser" for two factor authentication purposes, + /// as an asynchronous operation. + /// + /// The user who choose "remember this browser". + /// The task object representing the asynchronous operation. public virtual async Task RememberTwoFactorClientAsync(TUser user) { var userId = await UserManager.GetUserIdAsync(user); @@ -241,12 +281,26 @@ namespace Microsoft.AspNet.Identity new AuthenticationProperties { IsPersistent = true }); } + /// + /// Clears the "Remember this browser flag" from the current browser, as an asynchronous operation. + /// + /// The task object representing the asynchronous operation. public virtual Task ForgetTwoFactorClientAsync() { Context.Authentication.SignOut(IdentityOptions.TwoFactorRememberMeCookieAuthenticationScheme); return Task.FromResult(0); } + /// + /// Validates the two faction sign in code and creates and signs in the user, as an asynchronous operation. + /// + /// The two factor authentication provider to validate the code against. + /// The two factor authentication code to validate. + /// Flag indicating whether the sign-in cookie should persist after the browser is closed. + /// Flag indicating whether the current browser should be remember, suppressing all further + /// two factor authentication prompts. + /// The task object representing the asynchronous operation containing the + /// for the sign-in attempt. public virtual async Task TwoFactorSignInAsync(string provider, string code, bool isPersistent, bool rememberClient) { @@ -292,9 +346,10 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns the user who has started the two factor authentication process + /// Gets the for the current two factor authentication login, as an asynchronous operation. /// - /// + /// The task object representing the asynchronous operation containing the + /// for the sign-in attempt. public virtual async Task GetTwoFactorAuthenticationUserAsync() { var info = await RetrieveTwoFactorInfoAsync(); @@ -306,6 +361,14 @@ namespace Microsoft.AspNet.Identity return await UserManager.FindByIdAsync(info.UserId); } + /// + /// Signs in a user via a previously registered third party login, as an asynchronous operation. + /// + /// The login provider to use. + /// The unique provider identifier for the user. + /// Flag indicating whether the sign-in cookie should persist after the browser is closed. + /// The task object representing the asynchronous operation containing the + /// for the sign-in attempt. public virtual async Task ExternalLoginSignInAsync(string loginProvider, string providerKey, bool isPersistent) { var user = await UserManager.FindByLoginAsync(loginProvider, providerKey); @@ -325,14 +388,21 @@ namespace Microsoft.AspNet.Identity } } - private const string LoginProviderKey = "LoginProvider"; - private const string XsrfKey = "XsrfId"; - + /// + /// Gets a collection of s for the known external login providers. + /// + /// A collection of s for the known external login providers. public virtual IEnumerable GetExternalAuthenticationSchemes() { return Context.Authentication.GetAuthenticationSchemes().Where(d => !string.IsNullOrEmpty(d.Caption)); } + /// + /// Gets the external login information for the current login, as an asynchronous operation. + /// + /// Flag indication whether a Cross Site Request Forgery token was expected in the current request. + /// The task object representing the asynchronous operation containing the + /// for the sign-in attempt. public virtual async Task GetExternalLoginInfoAsync(string expectedXsrf = null) { var auth = await Context.Authentication.AuthenticateAsync(IdentityOptions.ExternalCookieAuthenticationScheme); @@ -362,7 +432,14 @@ namespace Microsoft.AspNet.Identity } return new ExternalLoginInfo(auth.Principal, provider, providerKey, auth.Description.Caption); } - + + /// + /// Configures the redirect URL and user identifier for the specified external login . + /// + /// The provider to configure. + /// The external login URL users should be redirected to during the login glow. + /// The current user's identifier, which will be used to provide CSRF protection. + /// A configured . public virtual AuthenticationProperties ConfigureExternalAuthenticationProperties(string provider, string redirectUrl, string userId = null) { var properties = new AuthenticationProperties { RedirectUri = redirectUrl }; @@ -374,6 +451,51 @@ namespace Microsoft.AspNet.Identity return properties; } + /// + /// Starts a scope for wrapping log messages, as an asynchronous operation. + /// + /// The current user. + /// The method that called this method. + /// The task object representing the asynchronous operation. + protected virtual async Task BeginLoggingScopeAsync(TUser user, [CallerMemberName] string methodName = null) + { + var state = Resources.FormatLoggingResultMessageForUser(methodName, await UserManager.GetUserIdAsync(user)); + return Logger?.BeginScope(state); + } + + /// + /// Creates a claims principal for the specified 2fa information. + /// + /// The user whose is logging in via 2fa. + /// The 2fa provider. + /// A containing the user 2fa information. + internal static ClaimsPrincipal StoreTwoFactorInfo(string userId, string loginProvider) + { + var identity = new ClaimsIdentity(IdentityOptions.TwoFactorUserIdCookieAuthenticationType); + identity.AddClaim(new Claim(ClaimTypes.Name, userId)); + if (loginProvider != null) + { + identity.AddClaim(new Claim(ClaimTypes.AuthenticationMethod, loginProvider)); + } + return new ClaimsPrincipal(identity); + } + + private static ClaimsIdentity CreateIdentity(TwoFactorAuthenticationInfo info) + { + if (info == null) + { + return null; + } + var identity = new ClaimsIdentity(IdentityOptions.TwoFactorUserIdCookieAuthenticationType); + identity.AddClaim(new Claim(ClaimTypes.Name, info.UserId)); + if (info.LoginProvider != null) + { + identity.AddClaim(new Claim(ClaimTypes.AuthenticationMethod, info.LoginProvider)); + } + return identity; + } + + private async Task SignInOrTwoFactorAsync(TUser user, bool isPersistent, string loginProvider = null) { if (UserManager.SupportsUserTwoFactor && @@ -411,22 +533,33 @@ namespace Microsoft.AspNet.Identity return null; } - protected virtual async Task BeginLoggingScopeAsync(TUser user, [CallerMemberName] string methodName = null) + private async Task IsLockedOut(TUser user) { - var state = Resources.FormatLoggingResultMessageForUser(methodName, await UserManager.GetUserIdAsync(user)); - return Logger?.BeginScope(state); + return UserManager.SupportsUserLockout && await UserManager.IsLockedOutAsync(user); } - internal static ClaimsPrincipal StoreTwoFactorInfo(string userId, string loginProvider) + private async Task PreSignInCheck(TUser user) { - var identity = new ClaimsIdentity(IdentityOptions.TwoFactorUserIdCookieAuthenticationType); - identity.AddClaim(new Claim(ClaimTypes.Name, userId)); - if (loginProvider != null) + if (!await CanSignInAsync(user)) { - identity.AddClaim(new Claim(ClaimTypes.AuthenticationMethod, loginProvider)); + return SignInResult.NotAllowed; } - return new ClaimsPrincipal(identity); + if (await IsLockedOut(user)) + { + return SignInResult.LockedOut; + } + return null; } + + private Task ResetLockout(TUser user) + { + if (UserManager.SupportsUserLockout) + { + return UserManager.ResetAccessFailedCountAsync(user); + } + return Task.FromResult(0); + } + internal class TwoFactorAuthenticationInfo { public string UserId { get; set; } diff --git a/src/Microsoft.AspNet.Identity/SignInOptions.cs b/src/Microsoft.AspNet.Identity/SignInOptions.cs index 441ec55051..6f4530f5c1 100644 --- a/src/Microsoft.AspNet.Identity/SignInOptions.cs +++ b/src/Microsoft.AspNet.Identity/SignInOptions.cs @@ -3,16 +3,21 @@ namespace Microsoft.AspNet.Identity { + /// + /// Options for configuring sign in.. + /// public class SignInOptions { /// - /// If set, requires a confirmed email to sign in + /// Gets or sets a flag indicating whether a confirmed email address is required to sign in. /// + /// True if a user must have a confirmed email address before they can sign in, otherwise false. public bool RequireConfirmedEmail { get; set; } /// - /// If set, requires a confirmed phone number to sign in + /// Gets or sets a flag indicating whether a confirmed telephone number is required to sign in. /// + /// True if a user must have a confirmed telephone number before they can sign in, otherwise false. public bool RequireConfirmedPhoneNumber { get; set; } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/SignInResult.cs b/src/Microsoft.AspNet.Identity/SignInResult.cs index 82bb2ccefa..e03215fe18 100644 --- a/src/Microsoft.AspNet.Identity/SignInResult.cs +++ b/src/Microsoft.AspNet.Identity/SignInResult.cs @@ -6,7 +6,7 @@ using Microsoft.Framework.Logging; namespace Microsoft.AspNet.Identity { /// - /// Represents the result of an sign in operation + /// Represents the result of a sign-in operation. /// public class SignInResult { @@ -17,59 +17,69 @@ namespace Microsoft.AspNet.Identity private static readonly SignInResult _twoFactorRequired = new SignInResult { RequiresTwoFactor = true }; /// - /// True if the operation was successful + /// Returns a flag indication whether the sign-in was successful. /// + /// True if the sign-in was successful, otherwise false. public bool Succeeded { get; protected set; } /// - /// True if the user is locked out + /// Returns a flag indication whether the user attempting to sign-in is locked out. /// + /// True if the user attempting to sign-in is locked out, otherwise false. public bool IsLockedOut { get; protected set; } /// - /// True if the user is not allowed to sign in + /// Returns a flag indication whether the user attempting to sign-in is not allowed to sign-in. /// + /// True if the user attempting to sign-in is not allowed to sign-in, otherwise false. public bool IsNotAllowed { get; protected set; } /// - /// True if the sign in requires two factor + /// Returns a flag indication whether the user attempting to sign-in requires two factor authentication. /// + /// True if the user attempting to sign-in requires two factor authentication, otherwise false. public bool RequiresTwoFactor { get; protected set; } /// - /// Static success result + /// Returns a that represents a successful sign-in. /// - /// + /// A that represents a successful sign-in. public static SignInResult Success => _success; /// - /// Static failure result + /// Returns a that represents a failed sign-in. /// - /// + /// A that represents a failed sign-in. public static SignInResult Failed => _failed; /// - /// Static locked out result + /// Returns a that represents a sign-in attempt that failed because + /// the user was logged out. /// - /// + /// A that represents sign-in attempt that failed due to the + /// user being locked out. public static SignInResult LockedOut => _lockedOut; /// - /// Static not allowed result + /// Returns a that represents a sign-in attempt that failed because + /// the user is not allowed to sign-in. /// - /// + /// A that represents sign-in attempt that failed due to the + /// user is not allowed to sign-in. public static SignInResult NotAllowed => _notAllowed; /// - /// Static two factor required result + /// Returns a that represents a sign-in attempt that needs two-factor + /// authentication. /// - /// + /// A that represents sign-in attempt that needs two-factor + /// authentication. public static SignInResult TwoFactorRequired => _twoFactorRequired; /// - /// Returns string representation of the result. + /// Converts the value of the current object to its equivalent string representation. /// - /// + /// A string representation of value of the current object. public override string ToString() { return IsLockedOut ? "Lockedout" : @@ -79,9 +89,9 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns the level at which this result should be logged + /// Gets the log level for the current object. /// - /// + /// The log level for the current object. public virtual LogLevel GetLogLevel() { return Succeeded || RequiresTwoFactor ? LogLevel.Verbose : LogLevel.Warning; diff --git a/src/Microsoft.AspNet.Identity/TotpSecurityStampBasedTokenProvider.cs b/src/Microsoft.AspNet.Identity/TotpSecurityStampBasedTokenProvider.cs index 57a516b427..d77872a449 100644 --- a/src/Microsoft.AspNet.Identity/TotpSecurityStampBasedTokenProvider.cs +++ b/src/Microsoft.AspNet.Identity/TotpSecurityStampBasedTokenProvider.cs @@ -6,22 +6,37 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Identity { /// - /// TokenProvider that generates time based codes using the user's security stamp + /// Represents a token provider that generates time based codes using the user's security stamp. /// - /// - /// + /// The type encapsulating a user. public abstract class TotpSecurityStampBasedTokenProvider : IUserTokenProvider where TUser : class { + /// + /// Gets the name of the token provider. + /// + /// The name of the token provider. public abstract string Name { get; } /// - /// Generate a token for the user using their security stamp + /// Generates a token for the specified and , as an asynchronous operation. /// - /// - /// - /// - /// + /// The purpose the token will be used for. + /// The that can be used to retrieve user properties. + /// The user a token should be generated for. + /// + /// The that represents the asynchronous operation, containing the token for the specified + /// and . + /// + /// + /// The parameter allows a token generator to be used for multiple types of token whilst + /// insuring a token for one purpose cannot be used for another. For example if you specified a purpose of "Email" + /// and validated it with the same purpose a token with the purpose of TOTP would not pass the heck even if it was + /// for the same user. + /// + /// Implementations of should validate that purpose is not null or empty to + /// help with token separation. + /// public virtual async Task GenerateAsync(string purpose, UserManager manager, TUser user) { if (manager == null) @@ -34,13 +49,18 @@ namespace Microsoft.AspNet.Identity } /// - /// Validate the token for the user + /// Returns a flag indicating whether the specified is valid for the given + /// and , as an asynchronous operation. /// - /// - /// - /// - /// - /// + /// The purpose the token will be used for. + /// The token to validate. + /// The that can be used to retrieve user properties. + /// The user a token should be validated for. + /// + /// The that represents the asynchronous operation, containing the a flag indicating the result + /// of validating the for the specified and . + /// The task will return true if the token is valid, otherwise false. + /// public virtual async Task ValidateAsync(string purpose, string token, UserManager manager, TUser user) { if (manager == null) @@ -58,12 +78,15 @@ namespace Microsoft.AspNet.Identity } /// - /// Used for entropy in the token, uses the user.Id by default + /// Returns a constant, provider and user unique modifier used for entropy in generated tokens from user information, as an asynchronous operation. /// - /// - /// - /// - /// + /// The purpose the token will be generated for. + /// The that can be used to retrieve user properties. + /// The user a token should be generated for. + /// + /// The that represents the asynchronous operation, containing a constant modifier for the specified + /// and . + /// public virtual async Task GetUserModifierAsync(string purpose, UserManager manager, TUser user) { if (manager == null) @@ -74,6 +97,17 @@ namespace Microsoft.AspNet.Identity return "Totp:" + purpose + ":" + userId; } + /// + /// Returns a flag indicating whether the token provider can generate a token suitable for two factor authentication token for + /// the specified . + /// + /// The that can be used to retrieve user properties. + /// The user a token could be generated for. + /// + /// The that represents the asynchronous operation, containing the a flag indicating if a two + /// factor token could be generated by this provider for the specified and . + /// The task will return true if a two factor authentication token could be generated, otherwise false. + /// public abstract Task CanGenerateTwoFactorTokenAsync(UserManager manager, TUser user); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/UpperInvariantLookupNormalizer.cs b/src/Microsoft.AspNet.Identity/UpperInvariantLookupNormalizer.cs index 6aed8ea0ba..96ff3fbdb7 100644 --- a/src/Microsoft.AspNet.Identity/UpperInvariantLookupNormalizer.cs +++ b/src/Microsoft.AspNet.Identity/UpperInvariantLookupNormalizer.cs @@ -6,15 +6,16 @@ using System; namespace Microsoft.AspNet.Identity { /// - /// Normalizes via ToUpperInvariant() + /// Implements by converting keys to their upper cased invariant culture representation. /// public class UpperInvariantLookupNormalizer : ILookupNormalizer { /// - /// Normalizes via ToUpperInvariant() + /// Returns a normalized representation of the specified + /// by converting keys to their upper cased invariant culture representation. /// - /// - /// + /// The key to normalize. + /// A normalized representation of the specified . public virtual string Normalize(string key) { if (key == null) diff --git a/src/Microsoft.AspNet.Identity/UserClaimsPrincipalFactory.cs b/src/Microsoft.AspNet.Identity/UserClaimsPrincipalFactory.cs index 3893cb52bd..9f6f3a5a77 100644 --- a/src/Microsoft.AspNet.Identity/UserClaimsPrincipalFactory.cs +++ b/src/Microsoft.AspNet.Identity/UserClaimsPrincipalFactory.cs @@ -72,10 +72,11 @@ namespace Microsoft.AspNet.Identity public IdentityOptions Options { get; private set; } /// - /// Creates a populated for the specified . + /// Creates a from an user asynchronously. /// - /// The user instance to create claims on. - /// A that represents the started task. + /// The user to create a from. + /// The name of the authentication method the was sourced from. + /// The that represents the asynchronous creation operation, containing the created . public virtual async Task CreateAsync(TUser user) { if (user == null) diff --git a/src/Microsoft.AspNet.Identity/UserLoginInfo.cs b/src/Microsoft.AspNet.Identity/UserLoginInfo.cs index 625fc136e9..5bf56a90e7 100644 --- a/src/Microsoft.AspNet.Identity/UserLoginInfo.cs +++ b/src/Microsoft.AspNet.Identity/UserLoginInfo.cs @@ -4,10 +4,16 @@ namespace Microsoft.AspNet.Identity { /// - /// Represents a linked login for a user (i.e. a local username/password or a facebook/google account + /// Represents login information and source for a user record. /// public class UserLoginInfo { + /// + /// Creates a new instance of + /// + /// The provider associated with this login information. + /// The unique identifier for this user provided by the login provider. + /// The display name for this user provided by the login provider. public UserLoginInfo(string loginProvider, string providerKey, string displayName) { LoginProvider = loginProvider; @@ -16,18 +22,31 @@ namespace Microsoft.AspNet.Identity } /// - /// Provider for the linked login, i.e. Local, Facebook, Google, etc. + /// Gets or sets the provider for this instance of . /// + /// The provider for the this instance of + /// + /// Examples of the provider may be Local, Facebook, Google, etc. + /// public string LoginProvider { get; set; } /// - /// Key for the linked login at the provider + /// Gets or sets the unique identifier for the user identity user provided by the login provider. /// + /// + /// The unique identifier for the user identity user provided by the login provider. + /// + /// + /// This would be unique per provider, examples may be @microsoft as a Twitter provider key. + /// public string ProviderKey { get; set; } /// - /// Display name for the provider + /// Gets or sets the display name for the provider. /// + /// + /// The display name for the provider. + /// public string ProviderDisplayName { get; set; } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/UserManager.cs b/src/Microsoft.AspNet.Identity/UserManager.cs index 661f78a4d4..0612283173 100644 --- a/src/Microsoft.AspNet.Identity/UserManager.cs +++ b/src/Microsoft.AspNet.Identity/UserManager.cs @@ -19,9 +19,9 @@ using Microsoft.Framework.OptionsModel; namespace Microsoft.AspNet.Identity { /// - /// Exposes user related api which will automatically save changes to the UserStore + /// Provides the APIs for managing user in a persistence store. /// - /// + /// The type encapsulating a user. public class UserManager : IDisposable where TUser : class { private readonly Dictionary> _tokenProviders = @@ -30,20 +30,21 @@ namespace Microsoft.AspNet.Identity private TimeSpan _defaultLockout = TimeSpan.Zero; private bool _disposed; private readonly HttpContext _context; + private CancellationToken CancellationToken => _context?.RequestAborted ?? CancellationToken.None; /// - /// Constructor + /// Constructs a new instance of . /// - /// - /// - /// - /// - /// - /// - /// + /// The persistence store the manager will operate over. + /// The accessor used to access the . + /// The password hashing implementation to use when saving passwords. + /// A collection of to validate users against. + /// A collection of to validate passwords against. + /// The to use when generating index keys for users. + /// The used to provider error messages. /// - /// - /// + /// The logger used to log messages, warnings and errors. + /// The accessor used to access the . public UserManager(IUserStore store, IOptions optionsAccessor, IPasswordHasher passwordHasher, @@ -92,13 +93,17 @@ namespace Microsoft.AspNet.Identity } /// - /// Persistence abstraction that the Manager operates against + /// Gets or sets the persistence store the manager operates over. /// + /// The persistence store the manager operates over. protected internal IUserStore Store { get; set; } /// - /// Used to log messages + /// Gets the used to log messages from the manager. /// + /// + /// The used to log messages from the manager. + /// protected internal virtual ILogger Logger { get; set; } internal IPasswordHasher PasswordHasher { get; set; } @@ -114,8 +119,11 @@ namespace Microsoft.AspNet.Identity internal IdentityOptions Options { get; set; } /// - /// Returns true if the store is an IUserTwoFactorStore + /// Gets a flag indicating whether the backing user store supports two factor authentication. /// + /// + /// true if the backing user store supports user two factor authentication, otherwise false. + /// public virtual bool SupportsUserTwoFactor { get @@ -126,8 +134,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserPasswordStore + /// Gets a flag indicating whether the backing user store supports user passwords. /// + /// + /// true if the backing user store supports user passwords, otherwise false. + /// public virtual bool SupportsUserPassword { get @@ -138,8 +149,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserSecurityStore + /// Gets a flag indicating whether the backing user store supports security stamps. /// + /// + /// true if the backing user store supports user security stamps, otherwise false. + /// public virtual bool SupportsUserSecurityStamp { get @@ -150,8 +164,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserRoleStore + /// Gets a flag indicating whether the backing user store supports user roles. /// + /// + /// true if the backing user store supports user roles, otherwise false. + /// public virtual bool SupportsUserRole { get @@ -162,8 +179,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserLoginStore + /// Gets a flag indicating whether the backing user store supports external logins. /// + /// + /// true if the backing user store supports external logins, otherwise false. + /// public virtual bool SupportsUserLogin { get @@ -174,8 +194,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserEmailStore + /// Gets a flag indicating whether the backing user store supports user emails. /// + /// + /// true if the backing user store supports user emails, otherwise false. + /// public virtual bool SupportsUserEmail { get @@ -186,8 +209,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserPhoneNumberStore + /// Gets a flag indicating whether the backing user store supports user telephone numbers. /// + /// + /// true if the backing user store supports user telephone numbers, otherwise false. + /// public virtual bool SupportsUserPhoneNumber { get @@ -198,8 +224,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserClaimStore + /// Gets a flag indicating whether the backing user store supports user claims. /// + /// + /// true if the backing user store supports user claims, otherwise false. + /// public virtual bool SupportsUserClaim { get @@ -210,8 +239,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IUserLockoutStore + /// Gets a flag indicating whether the backing user store supports user lock-outs. /// + /// + /// true if the backing user store supports user lock-outs, otherwise false. + /// public virtual bool SupportsUserLockout { get @@ -222,8 +254,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the store is an IQueryableUserStore + /// Gets a flag indicating whether the backing user store supports returning + /// collections of information. /// + /// + /// true if the backing user store supports returning collections of + /// information, otherwise false. + /// public virtual bool SupportsQueryableUsers { get @@ -249,10 +286,8 @@ namespace Microsoft.AspNet.Identity } } - private CancellationToken CancellationToken => _context?.RequestAborted ?? CancellationToken.None; - /// - /// Dispose the store context + /// Releases all resources used by the user manager. /// public void Dispose() { @@ -260,61 +295,28 @@ namespace Microsoft.AspNet.Identity GC.SuppressFinalize(this); } - private async Task ValidateUserInternal(TUser user) - { - var errors = new List(); - foreach (var v in UserValidators) - { - var result = await v.ValidateAsync(this, user); - if (!result.Succeeded) - { - errors.AddRange(result.Errors); - } - } - return errors.Count > 0 ? IdentityResult.Failed(errors.ToArray()) : IdentityResult.Success; - } - - private async Task ValidatePasswordInternal(TUser user, string password) - { - var errors = new List(); - foreach (var v in PasswordValidators) - { - var result = await v.ValidateAsync(this, user, password); - if (!result.Succeeded) - { - errors.AddRange(result.Errors); - } - } - return errors.Count > 0 ? IdentityResult.Failed(errors.ToArray()) : IdentityResult.Success; - } - + /// + /// Generates a value suitable for use in concurrency tracking, as an asynchronous operation. + /// + /// The user to generate the stamp for. + /// + /// The that represents the asynchronous operation, containing the security + /// stamp for the specified . + /// public virtual Task GenerateConcurrencyStampAsync(TUser user) { return Task.FromResult(Guid.NewGuid().ToString()); } /// - /// Validate user and update. Called by other UserManager methods + /// Creates the specified in the backing store with no password, + /// as an asynchronous operation. /// - /// - /// - private async Task UpdateUserAsync(TUser user) - { - var result = await ValidateUserInternal(user); - if (!result.Succeeded) - { - return result; - } - await UpdateNormalizedUserNameAsync(user); - await UpdateNormalizedEmailAsync(user); - return await Store.UpdateAsync(user, CancellationToken); - } - - /// - /// Create a user with no password - /// - /// - /// + /// The user to create. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task CreateAsync(TUser user) { ThrowIfDisposed(); @@ -339,10 +341,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Update a user + /// Updates the specified in the backing store, as an asynchronous operation. /// - /// - /// + /// The user to update. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task UpdateAsync(TUser user) { ThrowIfDisposed(); @@ -358,10 +363,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Delete a user + /// Deletes the specified from the backing store, as an asynchronous operation. /// - /// - /// + /// The user to delete. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task DeleteAsync(TUser user) { ThrowIfDisposed(); @@ -377,11 +385,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Find a user by id + /// Finds and returns a user, if any, who has the specified . /// - /// - - /// + /// The user ID to search for. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing the user matching the specified if it exists. + /// public virtual Task FindByIdAsync(string userId) { ThrowIfDisposed(); @@ -389,10 +399,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Find a user by name + /// Finds and returns a user, if any, who has the specified normalized user name. /// - /// - /// + /// The normalized user name to search for. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing the user matching the specified if it exists. + /// public virtual Task FindByNameAsync(string userName) { ThrowIfDisposed(); @@ -404,23 +417,16 @@ namespace Microsoft.AspNet.Identity return Store.FindByNameAsync(userName, CancellationToken); } - // IUserPasswordStore methods - private IUserPasswordStore GetPasswordStore() - { - var cast = Store as IUserPasswordStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserPasswordStore); - } - return cast; - } - /// - /// Create a user and associates it with the given password + /// Creates the specified in the backing store with given password, + /// as an asynchronous operation. /// - /// - /// - /// + /// The user to create. + /// The password for the user to hash and store. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task CreateAsync(TUser user, string password) { ThrowIfDisposed(); @@ -442,20 +448,20 @@ namespace Microsoft.AspNet.Identity } /// - /// Normalize a key (user name, email) for uniqueness comparisons + /// Normalize a key (user name, email) for consistent comparisons. /// - /// - /// + /// The key to normalize. + /// A normalized value representing the specified . public virtual string NormalizeKey(string key) { return (KeyNormalizer == null) ? key : KeyNormalizer.Normalize(key); } /// - /// Update the user's normalized user name + /// Updates the normalized user name for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose user name should be normalized and updated. + /// The that represents the asynchronous operation. public virtual async Task UpdateNormalizedUserNameAsync(TUser user) { var normalizedName = NormalizeKey(await GetUserNameAsync(user)); @@ -463,10 +469,10 @@ namespace Microsoft.AspNet.Identity } /// - /// Get the user's name + /// Gets the user name for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose name should be retrieved. + /// The that represents the asynchronous operation, containing the name for the specified . public virtual async Task GetUserNameAsync(TUser user) { ThrowIfDisposed(); @@ -478,11 +484,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Set the user's name + /// Sets the given for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose name should be set. + /// The user name to set. + /// The that represents the asynchronous operation. public virtual async Task SetUserNameAsync(TUser user, string userName) { ThrowIfDisposed(); @@ -500,10 +506,10 @@ namespace Microsoft.AspNet.Identity } /// - /// Get the user's id + /// Gets the user identifier for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose identifier should be retrieved. + /// The that represents the asynchronous operation, containing the identifier for the specified . public virtual async Task GetUserIdAsync(TUser user) { ThrowIfDisposed(); @@ -511,11 +517,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the password combination is valid for the user + /// Returns a flag indicating whether the given is valid for the + /// specified , as an asynchronous operation. /// - /// - /// - /// + /// The user whose password should be validated. + /// The password to validate + /// The that represents the asynchronous operation, containing true if + /// the specified matches the one store for the , + /// otherwise false. public virtual async Task CheckPasswordAsync(TUser user, string password) { ThrowIfDisposed(); @@ -539,10 +548,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the user has a password + /// Gets a flag indicating whether the specified has a password, as an asynchronous operation. /// - /// - /// + /// The user to return a flag for, indicating whether they have a password or not. + /// + /// The that represents the asynchronous operation, returning true if the specified has a password + /// otherwise false. + /// public virtual async Task HasPasswordAsync(TUser user) { ThrowIfDisposed(); @@ -559,11 +571,15 @@ namespace Microsoft.AspNet.Identity } /// - /// Add a user password only if one does not already exist + /// Adds the to the specified only if the user + /// does not already have a password, as an asynchronous operation. /// - /// - /// - /// + /// The user whose password should be set. + /// The password to set. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task AddPasswordAsync(TUser user, string password) { ThrowIfDisposed(); @@ -590,12 +606,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Change a user password + /// Changes a user's password after confirming the specified is correct, + /// as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose password should be set. + /// The current password to validate before changing. + /// The new password to set for the specified . + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task ChangePasswordAsync(TUser user, string currentPassword, string newPassword) { ThrowIfDisposed(); @@ -621,10 +641,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Remove a user's password + /// Removes a user's password, as an asynchronous operation. /// - /// - /// + /// The user whose password should be removed. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task RemovePasswordAsync(TUser user, CancellationToken cancellationToken = default(CancellationToken)) { @@ -642,30 +666,16 @@ namespace Microsoft.AspNet.Identity } } - internal async Task UpdatePasswordHash(IUserPasswordStore passwordStore, - TUser user, string newPassword, bool validatePassword = true) - { - if (validatePassword) - { - var validate = await ValidatePasswordInternal(user, newPassword); - if (!validate.Succeeded) - { - return validate; - } - } - var hash = newPassword != null ? PasswordHasher.HashPassword(user, newPassword) : null; - await passwordStore.SetPasswordHashAsync(user, hash, CancellationToken); - await UpdateSecurityStampInternal(user); - return IdentityResult.Success; - } - /// - /// By default, retrieves the hashed password from the user store and calls PasswordHasher.VerifyHashPassword + /// Returns a indicating the result of a password hash comparison. /// - /// - /// - /// - /// + /// The store containing a user's password. + /// The user whose password should be verified. + /// The password to verify. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// protected virtual async Task VerifyPasswordAsync(IUserPasswordStore store, TUser user, string password) { var hash = await store.GetPasswordHashAsync(user, CancellationToken); @@ -676,22 +686,11 @@ namespace Microsoft.AspNet.Identity return PasswordHasher.VerifyHashedPassword(user, hash, password); } - // IUserSecurityStampStore methods - private IUserSecurityStampStore GetSecurityStore() - { - var cast = Store as IUserSecurityStampStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserSecurityStampStore); - } - return cast; - } - /// - /// Returns the current security stamp for a user + /// Get the security stamp for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose security stamp should be set. + /// The that represents the asynchronous operation, containing the security stamp for the specified . public virtual async Task GetSecurityStampAsync(TUser user) { ThrowIfDisposed(); @@ -704,10 +703,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Generate a new security stamp for a user, used for SignOutEverywhere functionality + /// Regenerates the security stamp for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose security stamp should be regenerated. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// + /// + /// Regenerating a security stamp will sign out any saved login for the user. + /// public virtual async Task UpdateSecurityStampAsync(TUser user) { ThrowIfDisposed(); @@ -725,10 +730,12 @@ namespace Microsoft.AspNet.Identity } /// - /// GenerateAsync a password reset token for the user using the UserTokenProvider + /// Generates a password reset token for the specified , using + /// the configured password reset token provider, as an asynchronous operation. /// - /// - /// + /// The user to generate a password reset token for. + /// The that represents the asynchronous operation, + /// containing a password reset token for the specified . public virtual async Task GeneratePasswordResetTokenAsync(TUser user) { ThrowIfDisposed(); @@ -742,12 +749,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Reset a user's password using a reset password token + /// Resets the 's password to the specified after + /// validating the given password reset , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user whose password should be reset. + /// The password reset token to verify. + /// The new password to set if reset token verification fails. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task ResetPasswordAsync(TUser user, string token, string newPassword) { ThrowIfDisposed(); @@ -773,37 +784,14 @@ namespace Microsoft.AspNet.Identity } } - // Update the security stamp if the store supports it - internal async Task UpdateSecurityStampInternal(TUser user) - { - if (SupportsUserSecurityStamp) - { - await GetSecurityStore().SetSecurityStampAsync(user, NewSecurityStamp(), CancellationToken); - } - } - - private static string NewSecurityStamp() - { - return Guid.NewGuid().ToString(); - } - - // IUserLoginStore methods - private IUserLoginStore GetLoginStore() - { - var cast = Store as IUserLoginStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserLoginStore); - } - return cast; - } - /// - /// Returns the user associated with this login + /// Retrieves the user associated with the specified external login provider and login provider key, as an asynchronous operation.. /// - /// - /// - /// + /// The login provider who provided the . + /// The key provided by the to identify a user. + /// + /// The for the asynchronous operation, containing the user, if any which matched the specified login provider and key. + /// public virtual Task FindByLoginAsync(string loginProvider, string providerKey) { ThrowIfDisposed(); @@ -820,12 +808,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Remove a user login + /// Attempts to remove the provided external login information from the specified , as an asynchronous operation. + /// and returns a flag indicating whether the removal succeed or not. /// - /// - /// - /// - /// + /// The user to remove the login information from. + /// The login provide whose information should be removed. + /// The key given by the external login provider for the specified user. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task RemoveLoginAsync(TUser user, string loginProvider, string providerKey) { ThrowIfDisposed(); @@ -852,11 +844,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Associate a login with a user + /// Adds an external to the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user to add the login to. + /// The external to add to the specified . + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task AddLoginAsync(TUser user, UserLoginInfo login) { ThrowIfDisposed(); @@ -883,10 +878,12 @@ namespace Microsoft.AspNet.Identity } /// - /// Gets the logins for a user. + /// Retrieves the associated logins for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose associated logins to retrieve. + /// + /// The for the asynchronous operation, containing a list of for the specified , if any. + /// public virtual async Task> GetLoginsAsync(TUser user) { ThrowIfDisposed(); @@ -898,23 +895,15 @@ namespace Microsoft.AspNet.Identity return await loginStore.GetLoginsAsync(user, CancellationToken); } - // IUserClaimStore methods - private IUserClaimStore GetClaimStore() - { - var cast = Store as IUserClaimStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserClaimStore); - } - return cast; - } - /// - /// Add a user claim + /// Adds the specified to the , as an asynchronous operation. /// - /// - /// - /// + /// The user to add the claim to. + /// The claim to add. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual Task AddClaimAsync(TUser user, Claim claim) { ThrowIfDisposed(); @@ -931,11 +920,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Add claims for a user + /// Adds the specified to the , as an asynchronous operation. /// - /// - /// - /// + /// The user to add the claim to. + /// The claims to add. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task AddClaimsAsync(TUser user, IEnumerable claims) { ThrowIfDisposed(); @@ -957,12 +949,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Updates the give claim information with the given new claim information + /// Replaces the given on the specified with the /// - /// - /// - /// - /// + /// The user to replace the claim on. + /// The claim to replace. + /// The new claim to replace the existing with. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task ReplaceClaimAsync(TUser user, Claim claim, Claim newClaim) { ThrowIfDisposed(); @@ -988,11 +984,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Remove a user claim + /// Removes the specified from the given . /// - /// - /// - /// + /// The user to remove the specified from. + /// The to remove. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual Task RemoveClaimAsync(TUser user, Claim claim) { ThrowIfDisposed(); @@ -1009,11 +1008,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Remove a user claim + /// Removes the specified from the given . /// - /// - /// - /// + /// The user to remove the specified from. + /// A collection of s to remove. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task RemoveClaimsAsync(TUser user, IEnumerable claims) { ThrowIfDisposed(); @@ -1035,10 +1037,12 @@ namespace Microsoft.AspNet.Identity } /// - /// Get a users's claims + /// Gets a list of s to be belonging to the specified as an asynchronous operation. /// - /// - /// + /// The role whose claims to retrieve. + /// + /// A that represents the result of the asynchronous query, a list of s. + /// public virtual async Task> GetClaimsAsync(TUser user) { ThrowIfDisposed(); @@ -1050,22 +1054,15 @@ namespace Microsoft.AspNet.Identity return await claimStore.GetClaimsAsync(user, CancellationToken); } - private IUserRoleStore GetUserRoleStore() - { - var cast = Store as IUserRoleStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserRoleStore); - } - return cast; - } - /// - /// Add a user to a role + /// Add the specified to the named role, as an asynchronous operation. /// - /// - /// - /// + /// The user to add to the named role. + /// The name of the role to add the user to. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task AddToRoleAsync(TUser user, string role) { ThrowIfDisposed(); @@ -1088,11 +1085,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Add a user to roles + /// Add the specified to the named roles, as an asynchronous operation. /// - /// - /// - /// + /// The user to add to the named roles. + /// The name of the roles to add the user to. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task AddToRolesAsync(TUser user, IEnumerable roles) { ThrowIfDisposed(); @@ -1122,11 +1122,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Remove a user from a role. + /// Removes the specified from the named role, as an asynchronous operation. /// - /// - /// - /// + /// The user to remove from the named role. + /// The name of the role to remove the user from. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task RemoveFromRoleAsync(TUser user, string role) { ThrowIfDisposed(); @@ -1148,11 +1151,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Remove a user from a specified roles. + /// Removes the specified from the named roles, as an asynchronous operation. /// - /// - /// - /// + /// The user to remove from the named roles. + /// The name of the roles to remove the user from. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task RemoveFromRolesAsync(TUser user, IEnumerable roles) { ThrowIfDisposed(); @@ -1181,10 +1187,10 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns the roles for the user + /// Gets a list of role names the specified belongs to, as an asynchronous operation. /// - /// - /// + /// The user whose role names to retrieve. + /// The that represents the asynchronous operation, containing a list of role names. public virtual async Task> GetRolesAsync(TUser user) { ThrowIfDisposed(); @@ -1197,11 +1203,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the user is in the specified role + /// Returns a flag indicating whether the specified is a member of the give named role, as an asynchronous operation. /// - /// - /// - /// + /// The user whose role membership should be checked. + /// The name of the role to be checked. + /// + /// The that represents the asynchronous operation, containing a flag indicating whether the specified is + /// a member of the named role. + /// public virtual async Task IsInRoleAsync(TUser user, string role) { ThrowIfDisposed(); @@ -1212,23 +1221,13 @@ namespace Microsoft.AspNet.Identity } return await userRoleStore.IsInRoleAsync(user, role, CancellationToken); } - - // IUserEmailStore methods - internal IUserEmailStore GetEmailStore(bool throwOnFail = true) - { - var cast = Store as IUserEmailStore; - if (throwOnFail && cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserEmailStore); - } - return cast; - } - + /// - /// Get a user's email + /// Gets the email address for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose email should be returned. + /// The used to propagate notifications that the operation should be canceled. + /// The task object containing the results of the asynchronous operation, the email address for the specified . public virtual async Task GetEmailAsync(TUser user) { ThrowIfDisposed(); @@ -1241,11 +1240,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Set a user's email + /// Sets the address for a , as an asynchronous operation. /// - /// - /// - /// + /// The user whose email should be set. + /// The email to set. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task SetEmailAsync(TUser user, string email) { ThrowIfDisposed(); @@ -1265,10 +1267,13 @@ namespace Microsoft.AspNet.Identity } /// - /// FindByLoginAsync a user by his email + /// Gets the user, if any, associated with the specified, normalized email address. /// - /// - /// + /// The normalized email address to return the user for. + /// The used to propagate notifications that the operation should be canceled. + /// + /// The task object containing the results of the asynchronous lookup operation, the user if any associated with the specified normalized email address. + /// public virtual Task FindByEmailAsync(string email) { ThrowIfDisposed(); @@ -1281,10 +1286,10 @@ namespace Microsoft.AspNet.Identity } /// - /// Update the user's normalized email + /// Updates the normalized email for the specified . /// - /// - /// + /// The user whose email address should be normalized and updated. + /// The task object representing the asynchronous operation. public virtual async Task UpdateNormalizedEmailAsync(TUser user) { var store = GetEmailStore(throwOnFail: false); @@ -1295,12 +1300,13 @@ namespace Microsoft.AspNet.Identity } } - /// - /// Get the confirmation token for the user + /// Generates an email confirmation token for the specified user, as an asynchronous operation. /// - /// - /// + /// The user to generate an email confirmation token for. + /// + /// The that represents the asynchronous operation, an email confirmation token. + /// public async virtual Task GenerateEmailConfirmationTokenAsync(TUser user) { ThrowIfDisposed(); @@ -1314,11 +1320,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Confirm the user with confirmation token + /// Validates that an email confirmation token matches the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user to validate the token against. + /// The email confirmation token to validate. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task ConfirmEmailAsync(TUser user, string token) { ThrowIfDisposed(); @@ -1340,10 +1349,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the user's email has been confirmed + /// Gets a flag indicating whether the email address for the specified has been verified, true if the email address is verified otherwise + /// false, as an asynchronous operation. /// - /// - /// + /// The user whose email confirmation status should be returned. + /// + /// The task object containing the results of the asynchronous operation, a flag indicating whether the email address for the specified + /// has been confirmed or not. + /// public virtual async Task IsEmailConfirmedAsync(TUser user) { ThrowIfDisposed(); @@ -1355,17 +1368,13 @@ namespace Microsoft.AspNet.Identity return await store.GetEmailConfirmedAsync(user, CancellationToken); } - private static string GetChangeEmailPurpose(string newEmail) - { - return "ChangeEmail:" + newEmail; - } - /// - /// Generate a change email token for the user using the UserTokenProvider + /// Generates an email change token for the specified user, as an asynchronous operation. /// - /// - /// - /// + /// The user to generate an email change token for. + /// + /// The that represents the asynchronous operation, an email change token. + /// public virtual async Task GenerateChangeEmailTokenAsync(TUser user, string newEmail) { ThrowIfDisposed(); @@ -1379,12 +1388,15 @@ namespace Microsoft.AspNet.Identity } /// - /// Change a user's email using a change email token + /// Updates a users emails if the specified email change is valid for the user. /// - /// - /// - /// - /// + /// The user whose email should be updated. + /// The new email address. + /// The change email token to be verified. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task ChangeEmailAsync(TUser user, string newEmail, string token) { ThrowIfDisposed(); @@ -1408,22 +1420,11 @@ namespace Microsoft.AspNet.Identity } } - // IUserPhoneNumberStore methods - internal IUserPhoneNumberStore GetPhoneNumberStore() - { - var cast = Store as IUserPhoneNumberStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserPhoneNumberStore); - } - return cast; - } - /// - /// Get a user's phoneNumber + /// Gets the telephone number, if any, for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose telephone number should be retrieved. + /// The that represents the asynchronous operation, containing the user's telephone number, if any. public virtual async Task GetPhoneNumberAsync(TUser user) { ThrowIfDisposed(); @@ -1436,11 +1437,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Set a user's phoneNumber + /// Sets the phone number for the specified . /// - /// - /// - /// + /// The user whose phone number to set. + /// The phone number to set. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task SetPhoneNumberAsync(TUser user, string phoneNumber) { ThrowIfDisposed(); @@ -1460,12 +1464,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Set a user's phoneNumber with the verification token + /// Sets the phone number for the specified if the specified + /// change is valid. /// - /// - /// - /// - /// + /// The user whose phone number to set. + /// The phone number to set. + /// The phone number confirmation token to validate. + /// + /// The that represents the asynchronous operation, containing the + /// of the operation. + /// public virtual async Task ChangePhoneNumberAsync(TUser user, string phoneNumber, string token) { ThrowIfDisposed(); @@ -1489,10 +1497,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns true if the user's phone number has been confirmed + /// Gets a flag indicating whether the specified 's telephone number has been confirmed, as an asynchronous operation. /// - /// - /// + /// The user to return a flag for, indicating whether their telephone number is confirmed. + /// + /// The that represents the asynchronous operation, returning true if the specified has a confirmed + /// telephone number otherwise false. + /// public virtual async Task IsPhoneNumberConfirmedAsync(TUser user) { ThrowIfDisposed(); @@ -1504,18 +1515,14 @@ namespace Microsoft.AspNet.Identity return await store.GetPhoneNumberConfirmedAsync(user, CancellationToken); } - // Two factor APIS - internal async Task CreateSecurityTokenAsync(TUser user) - { - return Encoding.Unicode.GetBytes(await GetSecurityStampAsync(user)); - } - /// - /// Get a phone number code for a user and phone number + /// Generates a telephone number change token for the specified user, as an asynchronous operation. /// - /// - /// - /// + /// The user to generate a telephone number token for. + /// The new phone number the validation token should be sent to. + /// + /// The that represents the asynchronous operation, containing the telephone change number token. + /// public virtual async Task GenerateChangePhoneNumberTokenAsync(TUser user, string phoneNumber) { ThrowIfDisposed(); @@ -1531,12 +1538,16 @@ namespace Microsoft.AspNet.Identity } /// - /// Verify a phone number code for a specific user and phone number + /// Returns a flag indicating whether the specified 's phone number change verification + /// token is valid for the given , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user to validate the token against. + /// The telephone number change token to validate. + /// The telephone number the token was generated for. + /// + /// The that represents the asynchronous operation, returning true if the + /// is valid, otherwise false. + /// public virtual async Task VerifyChangePhoneNumberTokenAsync(TUser user, string token, string phoneNumber) { ThrowIfDisposed(); @@ -1559,13 +1570,17 @@ namespace Microsoft.AspNet.Identity } /// - /// Verify a user token with the specified purpose + /// Returns a flag indicating whether the specified is valid for + /// the given and , as an asynchronous operation. /// - /// - /// - /// - /// - /// + /// The user to validate the token against. + /// The token provider used to generate the token. + /// The purpose the token should be generated for. + /// The token to validate + /// + /// The that represents the asynchronous operation, returning true if the + /// is valid, otherwise false. + /// public virtual async Task VerifyUserTokenAsync(TUser user, string tokenProvider, string purpose, string token) { ThrowIfDisposed(); @@ -1601,12 +1616,15 @@ namespace Microsoft.AspNet.Identity } /// - /// Get a user token for a specific purpose + /// Generates a token for the given and , as an asynchronous operation. /// - /// - /// - /// - /// + /// The purpose the token will be for. + /// The user the token will be for. + /// The provider which will generate the token. + /// + /// The that represents result of the asynchronous operation, a token for + /// the given user and purpose. + /// public virtual async Task GenerateUserTokenAsync(TUser user, string tokenProvider, string purpose) { ThrowIfDisposed(); @@ -1630,9 +1648,9 @@ namespace Microsoft.AspNet.Identity } /// - /// Register a user token provider + /// Registers a token provider. /// - /// + /// The provider to register. public virtual void RegisterTokenProvider(IUserTokenProvider provider) { ThrowIfDisposed(); @@ -1644,10 +1662,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns a list of valid two factor providers for a user + /// Gets a list of valid two factor token providers for the specified , + /// as an asynchronous operation. /// - /// - /// + /// The user the whose two factor authentication providers will be returned. + /// + /// The that represents result of the asynchronous operation, a list of two + /// factor authentication providers for the specified user. + /// public virtual async Task> GetValidTwoFactorProvidersAsync(TUser user) { ThrowIfDisposed(); @@ -1667,12 +1689,15 @@ namespace Microsoft.AspNet.Identity } /// - /// Verify a user token with the specified provider + /// Verifies the specified two factor authentication against the , as an asynchronous operation. /// - /// - /// - /// - /// + /// The user the token is supposed to be for. + /// The provider which will verify the token. + /// The token to verify. + /// + /// The that represents result of the asynchronous operation, true if the token is valid, + /// otherwise false. + /// public virtual async Task VerifyTwoFactorTokenAsync(TUser user, string tokenProvider, string token) { ThrowIfDisposed(); @@ -1703,11 +1728,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Get a user token for a specific user factor provider + /// Gets a two factor authentication token for the specified , as an asynchronous operation. /// - /// - /// - /// + /// The user the token is for. + /// The provider which will generate the token. + /// + /// The that represents result of the asynchronous operation, a two factor authentication token + /// for the user. + /// public virtual async Task GenerateTwoFactorTokenAsync(TUser user, string tokenProvider) { ThrowIfDisposed(); @@ -1729,22 +1757,15 @@ namespace Microsoft.AspNet.Identity } } - // IUserFactorStore methods - internal IUserTwoFactorStore GetUserTwoFactorStore() - { - var cast = Store as IUserTwoFactorStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserTwoFactorStore); - } - return cast; - } - /// - /// Get a user's two factor provider + /// Returns a flag indicating whether the specified has two factor authentication enabled or not, + /// as an asynchronous operation. /// - /// - /// + /// The user whose two factor authentication enabled status should be retrieved. + /// + /// The that represents the asynchronous operation, true if the specified + /// has two factor authentication enabled, otherwise false. + /// public virtual async Task GetTwoFactorEnabledAsync(TUser user) { ThrowIfDisposed(); @@ -1757,11 +1778,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Set whether a user has two factor enabled or not + /// Sets a flag indicating whether the specified has two factor authentication enabled or not, + /// as an asynchronous operation. /// - /// - /// - /// + /// The user whose two factor authentication enabled status should be set. + /// + /// The that represents the asynchronous operation, the of the operation + /// public virtual async Task SetTwoFactorEnabledAsync(TUser user, bool enabled) { ThrowIfDisposed(); @@ -1779,22 +1802,15 @@ namespace Microsoft.AspNet.Identity } } - // IUserLockoutStore methods - internal IUserLockoutStore GetUserLockoutStore() - { - var cast = Store as IUserLockoutStore; - if (cast == null) - { - throw new NotSupportedException(Resources.StoreNotIUserLockoutStore); - } - return cast; - } - /// - /// Returns true if the user is locked out + /// Returns a flag indicating whether the specified his locked out, + /// as an asynchronous operation. /// - /// - /// + /// The user whose locked out status should be retrieved. + /// + /// The that represents the asynchronous operation, true if the specified + /// is locked out, otherwise false. + /// public virtual async Task IsLockedOutAsync(TUser user) { ThrowIfDisposed(); @@ -1812,11 +1828,14 @@ namespace Microsoft.AspNet.Identity } /// - /// Sets whether the user allows lockout + /// Sets a flag indicating whether the specified is locked out, + /// as an asynchronous operation. /// - /// - /// - /// + /// The user whose locked out status should be set. + /// Flag indicating whether the user is locked out or not. + /// + /// The that represents the asynchronous operation, the of the operation + /// public virtual async Task SetLockoutEnabledAsync(TUser user, bool enabled) { ThrowIfDisposed(); @@ -1834,10 +1853,12 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns whether the user allows lockout + /// Retrieves a flag indicating whether user lockout can enabled for the specified user, as an asynchronous operation. /// - /// - /// + /// The user whose ability to be locked out should be returned. + /// + /// The that represents the asynchronous operation, true if a user can be locked out, otherwise false. + /// public virtual async Task GetLockoutEnabledAsync(TUser user) { ThrowIfDisposed(); @@ -1850,10 +1871,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns the user lockout end date + /// Gets the last a user's last lockout expired, if any, as an asynchronous operation. + /// Any time in the past should be indicates a user is not locked out. /// - /// - /// + /// The user whose lockout date should be retrieved. + /// + /// A that represents the lookup, a containing the last time a user's lockout expired, if any. + /// public virtual async Task GetLockoutEndDateAsync(TUser user) { ThrowIfDisposed(); @@ -1866,11 +1890,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Sets the user lockout end date + /// Locks out a user until the specified end date has passed, as an asynchronous operation. Setting a end date in the past immediately unlocks a user. /// - /// - /// - /// + /// The user whose lockout date should be set. + /// The after which the 's lockout should end. + /// The that represents the asynchronous operation, containing the of the operation. public virtual async Task SetLockoutEndDateAsync(TUser user, DateTimeOffset? lockoutEnd) { ThrowIfDisposed(); @@ -1892,12 +1916,12 @@ namespace Microsoft.AspNet.Identity } /// - /// Increments the access failed count for the user and if the failed access account is greater than or equal - /// to the MaxFailedAccessAttempsBeforeLockout, the user will be locked out for the next - /// DefaultAccountLockoutTimeSpan and the AccessFailedCount will be reset to 0. + /// Increments the access failed count for the user as an asynchronous operation. + /// If the failed access account is greater than or equal to the configured maximum number of attempts, + /// the user will be locked out for the configured lockout time span. /// - /// - /// + /// The user whose failed access count to increment. + /// The that represents the asynchronous operation, containing the of the operation. public virtual async Task AccessFailedAsync(TUser user) { ThrowIfDisposed(); @@ -1923,10 +1947,10 @@ namespace Microsoft.AspNet.Identity } /// - /// Resets the access failed count for the user to 0 + /// Resets the access failed count for the specified , as an asynchronous operation. /// - /// - /// + /// The user whose failed access count should be reset. + /// The that represents the asynchronous operation, containing the of the operation. public virtual async Task ResetAccessFailedCountAsync(TUser user) { ThrowIfDisposed(); @@ -1948,10 +1972,11 @@ namespace Microsoft.AspNet.Identity } /// - /// Returns the number of failed access attempts for the user + /// Retrieves the current number of failed accesses for the given , as an asynchronous operation. /// - /// - /// + /// The user whose access failed count should be retrieved for. + /// The that contains the result the asynchronous operation, the current failed access count + /// for the user.. public virtual async Task GetAccessFailedCountAsync(TUser user) { ThrowIfDisposed(); @@ -1975,10 +2000,13 @@ namespace Microsoft.AspNet.Identity } /// - /// Get all the users in a role + /// Returns a list of users from the user store who have the specified . /// - /// - /// + /// The claim to look for. + /// + /// A that represents the result of the asynchronous query, a list of s who + /// have the specified claim. + /// public virtual Task> GetUsersInRoleAsync(string roleName) { ThrowIfDisposed(); @@ -1991,12 +2019,215 @@ namespace Microsoft.AspNet.Identity return store.GetUsersInRoleAsync(roleName, CancellationToken); } + /// + /// Starts a logging scope to contain the logging messages for an operation, as an asynchronous operation. + /// + /// The user the operation is acting on. + /// The method that called this method. + /// A containing the logging scope. protected virtual async Task BeginLoggingScopeAsync(TUser user, [CallerMemberName] string methodName = null) { var state = Resources.FormatLoggingResultMessageForUser(methodName, await GetUserIdAsync(user)); return Logger?.BeginScope(state); } + /// + /// Releases the unmanaged resources used by the role manager and optionally releases the managed resources. + /// + /// true to release both managed and unmanaged resources; false to release only unmanaged resources. + protected virtual void Dispose(bool disposing) + { + if (disposing && !_disposed) + { + Store.Dispose(); + _disposed = true; + } + } + + // IUserFactorStore methods + internal IUserTwoFactorStore GetUserTwoFactorStore() + { + var cast = Store as IUserTwoFactorStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserTwoFactorStore); + } + return cast; + } + + // IUserLockoutStore methods + internal IUserLockoutStore GetUserLockoutStore() + { + var cast = Store as IUserLockoutStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserLockoutStore); + } + return cast; + } + + // IUserEmailStore methods + internal IUserEmailStore GetEmailStore(bool throwOnFail = true) + { + var cast = Store as IUserEmailStore; + if (throwOnFail && cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserEmailStore); + } + return cast; + } + + // IUserPhoneNumberStore methods + internal IUserPhoneNumberStore GetPhoneNumberStore() + { + var cast = Store as IUserPhoneNumberStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserPhoneNumberStore); + } + return cast; + } + + // Two factor APIS + internal async Task CreateSecurityTokenAsync(TUser user) + { + return Encoding.Unicode.GetBytes(await GetSecurityStampAsync(user)); + } + + // Update the security stamp if the store supports it + internal async Task UpdateSecurityStampInternal(TUser user) + { + if (SupportsUserSecurityStamp) + { + await GetSecurityStore().SetSecurityStampAsync(user, NewSecurityStamp(), CancellationToken); + } + } + + internal async Task UpdatePasswordHash(IUserPasswordStore passwordStore, + TUser user, string newPassword, bool validatePassword = true) + { + if (validatePassword) + { + var validate = await ValidatePasswordInternal(user, newPassword); + if (!validate.Succeeded) + { + return validate; + } + } + var hash = newPassword != null ? PasswordHasher.HashPassword(user, newPassword) : null; + await passwordStore.SetPasswordHashAsync(user, hash, CancellationToken); + await UpdateSecurityStampInternal(user); + return IdentityResult.Success; + } + + private IUserRoleStore GetUserRoleStore() + { + var cast = Store as IUserRoleStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserRoleStore); + } + return cast; + } + + private static string NewSecurityStamp() + { + return Guid.NewGuid().ToString(); + } + + // IUserLoginStore methods + private IUserLoginStore GetLoginStore() + { + var cast = Store as IUserLoginStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserLoginStore); + } + return cast; + } + + private IUserSecurityStampStore GetSecurityStore() + { + var cast = Store as IUserSecurityStampStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserSecurityStampStore); + } + return cast; + } + + private IUserClaimStore GetClaimStore() + { + var cast = Store as IUserClaimStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserClaimStore); + } + return cast; + } + + + private static string GetChangeEmailPurpose(string newEmail) + { + return "ChangeEmail:" + newEmail; + } + + private async Task ValidateUserInternal(TUser user) + { + var errors = new List(); + foreach (var v in UserValidators) + { + var result = await v.ValidateAsync(this, user); + if (!result.Succeeded) + { + errors.AddRange(result.Errors); + } + } + return errors.Count > 0 ? IdentityResult.Failed(errors.ToArray()) : IdentityResult.Success; + } + + private async Task ValidatePasswordInternal(TUser user, string password) + { + var errors = new List(); + foreach (var v in PasswordValidators) + { + var result = await v.ValidateAsync(this, user, password); + if (!result.Succeeded) + { + errors.AddRange(result.Errors); + } + } + return errors.Count > 0 ? IdentityResult.Failed(errors.ToArray()) : IdentityResult.Success; + } + + /// + /// Validate user and update. Called by other UserManager methods + /// + /// + /// + private async Task UpdateUserAsync(TUser user) + { + var result = await ValidateUserInternal(user); + if (!result.Succeeded) + { + return result; + } + await UpdateNormalizedUserNameAsync(user); + await UpdateNormalizedEmailAsync(user); + return await Store.UpdateAsync(user, CancellationToken); + } + + // IUserPasswordStore methods + private IUserPasswordStore GetPasswordStore() + { + var cast = Store as IUserPasswordStore; + if (cast == null) + { + throw new NotSupportedException(Resources.StoreNotIUserPasswordStore); + } + return cast; + } + private void ThrowIfDisposed() { if (_disposed) @@ -2005,17 +2236,5 @@ namespace Microsoft.AspNet.Identity } } - /// - /// When disposing, actually dipose the store context - /// - /// - protected virtual void Dispose(bool disposing) - { - if (disposing && !_disposed) - { - Store.Dispose(); - _disposed = true; - } - } } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Identity/UserOptions.cs b/src/Microsoft.AspNet.Identity/UserOptions.cs index e8cdf38b86..ef2688e302 100644 --- a/src/Microsoft.AspNet.Identity/UserOptions.cs +++ b/src/Microsoft.AspNet.Identity/UserOptions.cs @@ -47,8 +47,7 @@ namespace Microsoft.AspNet.Identity /// Gets or sets a flag indicating whether the application requires unique emails for its users. /// /// - /// A flag indicating whether the application requires unique emails for its users. - /// This will be true if the application requires each user to have their own, unique email, otherwise false. + /// True if the application requires each user to have their own, unique email, otherwise false. /// public bool RequireUniqueEmail { get; set; } } diff --git a/src/Microsoft.AspNet.Identity/UserValidator.cs b/src/Microsoft.AspNet.Identity/UserValidator.cs index fb97450b04..cc9616f069 100644 --- a/src/Microsoft.AspNet.Identity/UserValidator.cs +++ b/src/Microsoft.AspNet.Identity/UserValidator.cs @@ -15,23 +15,30 @@ namespace Microsoft.AspNet.Identity /// /// Provides validation services for user classes. /// - /// + /// The type encapsulating a user. public class UserValidator : IUserValidator where TUser : class { + /// + /// Creates a new instance of / + /// + /// The used to provider error messages. public UserValidator(IdentityErrorDescriber errors = null) { Describer = errors ?? new IdentityErrorDescriber(); } + /// + /// Gets the used to provider error messages for the current . + /// + /// Yhe used to provider error messages for the current . public IdentityErrorDescriber Describer { get; private set; } /// - /// Validates a user before saving + /// Validates the specified as an asynchronous operation. /// - /// - /// - /// - /// + /// The that can be used to retrieve user properties. + /// The user to validate. + /// The that represents the asynchronous operation, containing the of the validation operation. public virtual async Task ValidateAsync(UserManager manager, TUser user) { if (manager == null)