APIs - Authentication PDF

IAuthenticationService Describes the Authentication abstraction layer. Suggest Edits Description The Authentication abstraction layer. Properties Identity Gets the identity for the currently authenticated user. C# IIdentity Identity { get; } Methods A...

IAuthenticationService Describes the Authentication abstraction layer. Suggest Edits Description The Authentication abstraction layer. Properties Identity Gets the identity for the currently authenticated user. C# IIdentity Identity { get; } Methods AddUserToRole(string, string) Assigns a role to a user. C# 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. C# bool AllowOnlyAlphanumericUserNames() Returns True if usernames are only allowed to contain alphanumeric characters. ChangePassword(string, string, string) Changes the password for the specified user. C# 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. C# 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. C# 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. C# 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. C# 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. C# 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. C# 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. Text 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. C# 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. C# ReadOnlyCollection GetAllRoles() Returns Collection of available roles. GetAllUsersWithRoles(IEnumerable) Returns all users who have any of the specified roles assigned. C# IEnumerable GetAllUsersWithRoles(IEnumerable 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. C# IList 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. C# 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. C# 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. C# 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. C# 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. C# 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. C# 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. C# 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. C# 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. C#  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. C# int MinRequiredUppercaseCharacters() Returns The minimum number of uppercase characters required for a valid password. RemoveUserFromRole(string, string) Unassigns the role from the user. C# 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. C# 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. C# 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. C# 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. C# 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. C# 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. C#  void SetUserAsAuthenticated(string userName) Parameters userName – The username of the user to authenticate. SignOut() Ends the currently authenticated user's session. C# void SignOut() UnlockUser(string) Unlocks the account for the user. The account should be locked out in order for this to work. C# 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. C# 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. C# 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. C# 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. C# 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 C# [DependencyName(nameof(ChangePasswordWithToken))] public sealed class ChangePasswordWithToken : HandlerBase { private readonly Lazy authenticationService; public ChangePasswordWithToken(Lazy 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().GetByNaturalKey(paramete r.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); } }