IAuthenticationService

Description

The Authentication abstraction layer.

Properties

Identity

Gets the identity for the currently authenticated user.

IIdentity Identity { get; }

Methods

AddUserToRole(string, string)

Assigns a role to a user.

string AddUserToRole(string userName, string roleName)

Parameters

• userName – The username of the user who should be assigned the role.
• roleName – The name of the role to assign to the user.

Returns

• An empty string if the assignment was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the assignment.

AllowOnlyAlphanumericUserNames()

Indicates whether or not usernames for users are only allowed to contain alphanumeric characters.

bool AllowOnlyAlphanumericUserNames()

Returns

• True if usernames are only allowed to contain alphanumeric characters.

ChangePassword(string, string, string)

Changes the password for the specified user.

bool ChangePassword(string userName, string oldPassword, string newPassword)

Parameters

• userName – The username of the user whose password should be changed.
• oldPassword – The user's current password.
• newPassword – The new password to be used for the user's account.

Returns

• True if the change was successful.

CreateRole(string)

Creates a new role with the specified role name.

string CreateRole(string roleName)

Parameters

• roleName – The name of the role to create.

Returns

• An empty string if the assignment was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the operation.

CreateUser(string, string)

Creates a new user without a password.

string CreateUser(string userName, string email)

Parameters

• userName – The username to use when creating the user.
• email – The email address to use when creating the user.

Returns

• An empty string if the operation was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the operation.

CreateUser(string, string, string)

Creates a new user using the specified password.

string CreateUser(string userName, string email, string password)

Parameters

• userName – The username to use when creating the user.
• email – The email address to use when creating the user.
• password – The password to be used for the user's account.

Returns

• An empty string if the operation was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the operation.

DeleteRole(string)

Deletes the specified role.

string DeleteRole(string roleName)

Parameters

• roleName – The name of the role to delete.

Returns

• An empty string if the delete was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the delete.

DeleteUser(string)

Deletes the specified user.

string DeleteUser(string userName)

Parameters

• userName – The username of the user to delete.

Returns

• An empty string if the delete was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the delete.

EmailAlreadyExists(string)

Checks if an email address is already being used by an existing user.

bool EmailAlreadyExists(string email)

Parameters

• email – The email address to check against existing users.

Returns

• True if the email address is already being used.

GeneratePassword()

Generates a valid password based on password complexity requirements.

string GeneratePassword()

Returns

• A valid password.

GeneratePasswordResetUrl(string, bool)

Generates a password reset URL for the specified user. The user can use the URL to reset his or her account password.

string GeneratePasswordResetUrl(string userName, bool isReset)

Parameters

• userName – The user name of the user for which to generate a password reset URL.
• isReset – True if the URL is for a password reset operation, otherwise for an account activation operation.

Returns

• A password reset URL that includes a reset token.

GetAllRoles()

Returns all the roles available in the application.

ReadOnlyCollection<RoleDto> GetAllRoles()

Returns

Collection of available roles.

GetAllUsersWithRoles(IEnumerable)

Returns all users who have any of the specified roles assigned.

IEnumerable<string> GetAllUsersWithRoles(IEnumerable<string> roles)

Parameters

• roles – The collection of rolenames to use when searching for users.

Returns

• All users who have any of the specified roles assigned.

GetRolesForUser(string)

Gets the roles assigned to a user.

IList<RoleDto> GetRolesForUser(string userName)

Parameters

• userName – The username of the user for which to return assigned roles.

Returns

• The roles assigned to a user.

IsAuthenticated()

Returns whether or not the current user is currently authenticated.

bool IsAuthenticated()

Returns

• True if the current user is currently authenticated.

IsLockedOut(string)

Returns whether or not the current user is locked out of the application. This can check the status of both Admin Console and Storefront users.

bool IsLockedOut(string userName)

Parameters

• userName – The username of the user for which to check the locked out status.

Returns

• True if the current user is locked out of the application.

IsUserInRole(string, string)

Indicates whether or not the role is assigned to the user.

bool IsUserInRole(string userName, string roleName)

Parameters

• userName – The username of the user for which to check for the role assignment.
• roleName – The name of the role to check for the role assignment.

Returns

• True if the role is assigned to the user.

IsValidPassword(string)

Check a password to see if it meets complexity requirements.

bool IsValidPassword(string password)

Parameters

• password – The password to check for validity.

Returns

• True if the password meets the complexity requirements.

LockUserOut(string)

Locks a user out of the application. For Admin Console users, this will apply to the Admin Console. For Storefront users, this will apply to the Storefront.

void LockUserOut(string userName)

Parameters

• userName – The username of the user to lock out.

MinRequiredDigits()

In regards to password complexity, returns the minimum number of digits required for a valid password.

int MinRequiredDigits()

Returns

• The minimum number of digits required for a valid password.

MinRequiredLowercaseCharacters()

In regards to password complexity, returns the minimum number of lowercase characters required for a valid password.

int MinRequiredLowercaseCharacters()

Returns

• The minimum number of lowercase characters required for a valid password.

MinRequiredNonAlphanumericCharacters()

In regards to password complexity, returns the minimum number of non-alphanumeric characters required for a valid password.

int MinRequiredNonAlphanumericCharacters()

Returns

• The minimum number of non-alphanumeric characters required for a valid password.

MinRequiredPasswordLength()

In regards to password complexity, returns the minimum length (total number of characters) required for a valid password.

int MinRequiredPasswordLength()

Returns

• The minimum length required for a valid password.

MinRequiredUppercaseCharacters()

In regards to password complexity, returns the minimum number of uppercase characters required for a valid password.

int MinRequiredUppercaseCharacters()

Returns

• The minimum number of uppercase characters required for a valid password.

RemoveUserFromRole(string, string)

Unassigns the role from the user.

string RemoveUserFromRole(string userName, string roleName)

Parameters

• userName – The username of the user for which to unassign the role.
• roleName – The name of the role to unassign from the user.

Returns

An empty string if the unassignment was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the unassignment.

RequiresQuestionAndAnswer()

In regards to account creation, indicates whether or not a security question and answer are required.

bool RequiresQuestionAndAnswer()

Returns

• True if a security question and answer are required.

RequiresUniqueEmail()

In regards to account creation, indicates whether or not email addresses must be unique among all users.

bool RequiresUniqueEmail()

Returns

• True if email addresses must be unique among all users.

ResetPassword(string)

Resets the current user's password to a randomly-generated, valid password.

string ResetPassword(string userName)

Parameters

• userName – The username of the user for which the password should be reset.

Returns

• The new password for the user's account.

ResetPasswordForUser(string, string, string)

Changes the password for a user, assuming the reset token is valid.

bool ResetPasswordForUser(string userName, string newPassword, string resetToken)

Parameters

• userName – The username of the user for which the password should be changed.
• newPassword – The new password to use for the user's account.
• resetToken – The reset token generated previously for the user to change his or her password.

Returns

• True if the password change was successful.

RoleExists(string)

Indicates whether or not the role exists in the application.

bool RoleExists(string roleName)

Parameters

• roleName – The name of the role to check for existence.

Returns

• True if the role exists in the application.

SetUserAsAuthenticated(string)

Authenticates the specified user. This is used during impersonation, access token validation, and punchout session initialization.

void SetUserAsAuthenticated(string userName)

Parameters

• userName – The username of the user to authenticate.

SignOut()

Ends the currently authenticated user's session.

void SignOut()

UnlockUser(string)

Unlocks the account for the user. The account should be locked out in order for this to work.

void UnlockUser(string userName)

Parameters

• userName – The username of the user for which the account should be unlocked.

UpdateUser(string, string)

Updates the email address for the user.

string UpdateUser(string userName, string email)

Parameters

• userName – The username of the user for which the email address should be updated.
• email – The new email address for the user.

Returns

• An empty string if the update was successful. Otherwise, it returns a comma-delimited string of error messages that resulted from the update.

UserNameAlreadyExists(string)

Checks if a username is already being used by an existing user.

bool UserNameAlreadyExists(string userName)

Parameters

• userName – The username to check against existing users.

Returns

• True if the username is already being used by an existing user.

ValidateUser(string, string)

Validates the specified user credentials.

bool ValidateUser(string userName, string password)

Parameters

• userName – The username to validate.
• password – The password to validate.

Returns

• True if the credentials are valid.

VerifyPasswordResetTokenForUser(string, string)

Indicates whether or not the supplied reset token is valid.

bool VerifyPasswordResetTokenForUser(string userName, string resetToken)

Parameters

• userName – The username to use when validating the reset token.
• resetToken – The reset token to validate.

Returns

• True the supplied reset token is valid.

Example

The example below is a handler that password data from a user resetting his or her current password to a new password. A reset token is expected, which is appended to the password reset URL previously generated using the IAuthenticationService.GeneratePasswordResetUrl method.

Code Sample

[DependencyName(nameof(ChangePasswordWithToken))]
    public sealed class ChangePasswordWithToken : HandlerBase<UpdateSessionParameter, UpdateSessionResult>
    {
        private readonly Lazy<IAuthenticationService> authenticationService;
     
        public ChangePasswordWithToken(Lazy<IAuthenticationService> authenticationService)
        {
            this.authenticationService = authenticationService;
        }
     
        public override int Order => 800;
     
        public override UpdateSessionResult Execute(IUnitOfWork unitOfWork, UpdateSessionParameter parameter, UpdateSessionResult result)
        {
            if (parameter.ResetToken.IsBlank() || parameter.NewPassword.IsBlank())
            {
                return this.NextHandler.Execute(unitOfWork, parameter, result);
            }
     
            if (parameter.UserName.IsBlank())
            {
                return this.CreateErrorServiceResult(result, SubCode.AccountServiceUserProfileNotFound, MessageProvider.Current.User_Not_Found);
            }
     
            if (!this.authenticationService.Value.IsValidPassword(parameter.NewPassword))
            {
                return this.CreateErrorServiceResult(result, SubCode.AccountServicePasswordDoesNotMeetComplexity, MessageProvider.Current.ChangePasswordInfo_Password_Not_Meet_Requirements);
            }
     
            if (!this.authenticationService.Value.ResetPasswordForUser(parameter.UserName, parameter.NewPassword, parameter.ResetToken))
            {
                return this.CreateErrorServiceResult(result, SubCode.AccountServiceUnableToChangePassword, MessageProvider.Current.ChangePasswordInfo_Unable_To_Change_Password);
            }
     
            var userProfile = unitOfWork.GetTypedRepository<IUserProfileRepository>().GetByNaturalKey(parameter.UserName);
            if (userProfile == null)
            {
                return this.CreateErrorServiceResult(result, SubCode.AccountServiceAccountDoesNotExist, MessageProvider.Current.Forgot_Password_Error);
            }
     
            this.authenticationService.Value.UnlockUser(parameter.UserName);
     
            userProfile.PasswordChangedOn = DateTimeProvider.Current.Now;
            userProfile.IsPasswordChangeRequired = false;
            userProfile.ActivationStatus = UserActivationStatus.Activated.ToString();
     
            return this.NextHandler.Execute(unitOfWork, parameter, result);
        }
    }