com.atlassian.crowd.manager.login
Interface ForgottenLoginManager

public interface ForgottenLoginManager

Manages functionality related to retrieving forgotten usernames or resetting forgotten passwords.

To reset a user's password, clients of ForgottenLoginManager would do the following:

1. sendResetLink sends the user a unique link to reset their password
2. resetUserCredential verifies that the reset token given by the user is correct using isValidResetToken, then resets if the user credentials if the token is valid.

Since:

v2.1.0

Field Summary

static int

DEFAULT_TOKEN_EXPIRY_SECONDS

Method Summary

ExpirableUserToken	createAndStoreResetToken(long directoryId, String username, String email, int tokenExpirySeconds) Creates an ExpirableUserToken for a given username in the given directory.
boolean	isValidResetToken(long directoryId, String username, String token) Returns true if the password reset token for the user with the specified username and directory ID are valid and not expired.
boolean	removeByDirectoryAndUsername(long directoryId, String username) Removes the password reset tokens associated to a username in a directory.
void	resetUserCredential(long directoryId, String username, PasswordCredential credential, String token) Resets the user credentials and invalidates the token.
void	sendResetLink(Application application, String username, int tokenExpirySeconds) Sends a reset link to the first user with the matching username from all the active directories assigned to the application.
void	sendResetLink(long directoryId, String username, int tokenExpirySeconds) Sends a reset link to the user with specified username and directory ID.
boolean	sendUsernames(Application application, String email) Sends the usernames associated with the given email address.

Field Detail

DEFAULT_TOKEN_EXPIRY_SECONDS

static final int DEFAULT_TOKEN_EXPIRY_SECONDS

Method Detail

sendResetLink

void sendResetLink(Application application,
                   String username,
                   int tokenExpirySeconds)
                   throws UserNotFoundException,
                          InvalidEmailAddressException,
                          ApplicationPermissionException

Sends a reset link to the first user with the matching username from all the active directories assigned to the application.

Parameters:

application - user is searched in application's assigned directories

username - username of the user to send the password reset link

tokenExpirySeconds - number of seconds before generated token expires, or DEFAULT_TOKEN_EXPIRY_SECONDS

Throws:

UserNotFoundException - if no user with the supplied username exists

InvalidEmailAddressException - if the user does not have a valid email address to send the password reset email to

ApplicationPermissionException - if the application does not have permission to modify the user

IllegalArgumentException - if tokenExpirySeconds is less than 0

sendUsernames

boolean sendUsernames(Application application,
                      String email)
                      throws InvalidEmailAddressException

Sends the usernames associated with the given email address. No email will be sent if there are no usernames associated with a given email.

The method returns a boolean, which should only ever be passed to authenticated applications to avoid leaking information.

Parameters:

application - search application's assigned directories for usernames associated with the email

email - email address of the user

Returns:

true if any users with that address were found.

Throws:

InvalidEmailAddressException - if the email is not valid

sendResetLink

void sendResetLink(long directoryId,
                   String username,
                   int tokenExpirySeconds)
                   throws DirectoryNotFoundException,
                          UserNotFoundException,
                          InvalidEmailAddressException,
                          OperationFailedException

Sends a reset link to the user with specified username and directory ID.

Similar to sendResetLink(Application, String, int) except applying to a directory-specific user.

Parameters:

directoryId - directory ID of the user to modify

username - username of the user to send the password reset link

tokenExpirySeconds - number of seconds before generated token expires, or DEFAULT_TOKEN_EXPIRY_SECONDS

Throws:

DirectoryNotFoundException - if the directory specified by directoryId could not be found

UserNotFoundException - if the user specified by username could not be found

InvalidEmailAddressException - if the user does not have a valid email address to send the password reset email to

IllegalArgumentException - if tokenExpirySeconds is less than 0

OperationFailedException

isValidResetToken

boolean isValidResetToken(long directoryId,
                          String username,
                          String token)

Returns true if the password reset token for the user with the specified username and directory ID are valid and not expired. The valid password reset token is created by sendResetLink(com.atlassian.crowd.model.application.Application, java.lang.String, int).

Parameters:

directoryId - directory ID of the user to validate

username - username of the user to verify the token

token - password reset token

Returns:

true if the username and reset token are a valid combination and the reset token has not expired.

resetUserCredential

void resetUserCredential(long directoryId,
                         String username,
                         PasswordCredential credential,
                         String token)
                         throws DirectoryNotFoundException,
                                UserNotFoundException,
                                InvalidResetPasswordTokenException,
                                OperationFailedException,
                                InvalidCredentialException,
                                DirectoryPermissionException

Resets the user credentials and invalidates the token.

Parameters:

directoryId - directory ID of the user

username - user name of the user to perform a credential reset

credential - new credentials

token - password reset token

Throws:

DirectoryNotFoundException - if the directory could not be found.

UserNotFoundException - if the user could not be found in the given directory.

InvalidResetPasswordTokenException - if the reset token is not valid.

OperationFailedException - if there was an error performing the operation or instantiating the backend directory.

InvalidCredentialException - if the user's credential does not meet the validation requirements for an associated directory.

DirectoryPermissionException - if the directory is not allowed to perform the operation

createAndStoreResetToken

ExpirableUserToken createAndStoreResetToken(long directoryId,
                                            String username,
                                            String email,
                                            int tokenExpirySeconds)

Creates an ExpirableUserToken for a given username in the given directory. Note: no check is done to verify that the user actually exists in the given directory; if this is not the case, the returned token will be useless.

Parameters:

directoryId - the directory id associated with the user

username - the username of the user to create the token for

email - the email of the user to create the token for

tokenExpirySeconds - number of seconds before generated token expires, or DEFAULT_TOKEN_EXPIRY_SECONDS

Returns:

The ExpirableUserToken

Throws:

IllegalArgumentException - if tokenExpirySeconds is less than 0

removeByDirectoryAndUsername

boolean removeByDirectoryAndUsername(long directoryId,
                                     String username)

Removes the password reset tokens associated to a username in a directory.

Parameters:

directoryId - directory where the user lives

username - username

Returns:

true if some tokens were removed